Programming: PL/I and C

IBM Tivoli NetView for z/OS Version 6 Release 2

IBM

SC27-2860-01

IBM Tivoli NetView for z/OS Version 6 Release 2

Programming: PL/I and C

IBM

SC27-2860-01 Note Before using this information and the product it supports, read the information in “Notices” on page 287.

This edition applies to version 6, release 2 of IBM Tivoli NetView for z/OS (product number 5697-NV6) and to all subsequent versions, releases, and modifications until otherwise indicated in new editions. This edition replaces SC27-2860-00. © Copyright IBM Corporation 1997, 2013. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents

Figures ...... xi

About this publication ...... xiii Intended audience ...... xiii Publications ...... xiii IBM Tivoli NetView for z/OS library ...... xiii Related publications ...... xv Accessing terminology online ...... xv Using NetView for z/OS online help ...... xvi Accessing publications online ...... xvi Ordering publications...... xvi Accessibility ...... xvii Service Management Connect ...... xvii Tivoli technical training ...... xvii Tivoli user groups...... xvii Downloads ...... xvii Support information...... xviii Conventions used in this publication ...... xviii Typeface conventions ...... xviii Operating system-dependent variables and paths ...... xix Syntax diagrams ...... xix

Part 1. Overview ...... 1

Chapter 1. High-level language services ...... 3 Running synchronous commands ...... 3 Sending commands (running asynchronous commands) ...... 3 Client and server request response handling ...... 3 Operator interaction ...... 3 Line mode input ...... 4 Line mode output ...... 4 Full-screen input/output ...... 4 Data access ...... 4 Message trapping...... 4 NetView message automation ...... 4 NetView MSU automation ...... 4 System symbolic access ...... 5 Command list variable access...... 5 Querying NetView information ...... 5 VSAM files ...... 5 Data queue manipulation ...... 5 Logical Unit 6.2 transport ...... 6 Operating remote systems ...... 6 Communication Network Management Interface ...... 6 NetView partitioned data sets ...... 7 Dynamic file allocation/deallocation ...... 7 Storage copying ...... 7 Named storage ...... 7 User-defined lock management ...... 7 Parsing character strings ...... 7 Command authorization checking ...... 7 NetView message logging ...... 8 NetView Bridge ...... 8 NetView Bridge remote access ...... 8

Chapter 2. HLL installation exit routines ...... 11 Overview of installation exit routines ...... 11 Coding restrictions ...... 11 Performance considerations ...... 12 General return codes ...... 12 Deleting messages ...... 12 Replacing messages...... 12 Installation exits ...... 14 BNJPALEX: Alert generation exit routine ...... 14 DSIEX01: Input from the operator ...... 14 DSIEX02A: Output to the operator...... 14 DSIEX03: Input before command processing ...... 15 DSIEX04: Log output ...... 15 DSIEX05: Before VTAM command invocation ...... 16 DSIEX06: Solicited VTAM messages ...... 16 DSIEX07: Cross-domain command send ...... 17 DSIEX09: Output to the system console ...... 17 DSIEX10: Input from the system console...... 17 DSIEX11: Unsolicited VTAM messages ...... 17 DSIEX12: Logon validation ...... 18 DSIEX13: OST/NNT message receiver ...... 19 DSIEX14: Before logoff...... 19 DSIEX16: Post-automation table installation exit for messages ...... 20 DSIEX16B: Post-automation table installation exit for MSUs ...... 20 DSIEX17: MVS message and DOM receive ...... 20 DSIEX18: Log browse installation exit ...... 20 DSIEX19: RUNCMD Installation exit ...... 20 DSIEX20: SAW exit ...... 21 DSIEX21: Encryption key for DSITCPRF installation exit ...... 21 XITBN: BSAM empty file ...... 21 XITBO: BSAM output ...... 22 XITCI: CNM interface input ...... 22 XITCO: CNM interface output ...... 24 XITDI: Data services task initialization ...... 25 XITVI: VSAM input ...... 25 XITVN: VSAM empty file ...... 25 XITVO: VSAM output ...... 26 XITXL: External logging ...... 26

Chapter 3. HLL Data Services command processors ...... 27 Installing the Data Services task ...... 27 Data Services command processors ...... 28 CNM Data Services...... 28 VSAM services ...... 29 User-defined services ...... 29 Scheduling commands under the DST ...... 29

Part 2. Enabling a high-level language program ...... 31

Chapter 4. Preinitialized and non-preinitialized environments ...... 33 Languages supported ...... 33 Advantages and disadvantages of preinitialized environments ...... 33 Steps for implementing command processors and installation exits ...... 34 Non-preinitialized environments ...... 34 Preinitialized environments ...... 34 HLL definition facilities ...... 35 iv Programming: PL/I and C Interface modules ...... 36 HLLENV command ...... 36 HLL runtime options ...... 38 Using the HLL runtime options for preinitialized environments ...... 40 Examples ...... 41 Non-preinitialized example ...... 41 Preinitialized example ...... 41

Chapter 5. Compiling, link-editing, and running your HLL program ...... 43 Compiling ...... 43 Link-editing ...... 43 Running ...... 45

Part 3. Writing a PL/I program ...... 47

Chapter 6. Coding HLL command processors and installation exits ...... 49 Initial parameters ...... 49 Runtime options...... 50 CEEUOPT runtime option CSECT ...... 50 z/OS Language Environment preinitialization defaults ...... 50 PSTACK and PHEAP ...... 51 LEOPTS static external variable...... 51 Parameters passed to HLL Service routines ...... 51 Pointer variables...... 52 Integer variables...... 53 Fixed-length character strings ...... 54 Varying length character strings ...... 54 Control blocks and Include files ...... 55 PL/I Input and output considerations ...... 56 PL/I Input and output considerations in a preinitialized environment ...... 57 PL/I runtime considerations...... 57 Considerations for HLL command processors ...... 57 Return codes ...... 58 Restrictions for HLL programs written in PL/I ...... 58 Restrictions for PL/I programs running in a preinitialized environment ...... 58

Chapter 7. PL/I high-level language services ...... 59 PL/I sample template ...... 59 Data queue management ...... 61 Sending messages ...... 61 Parsing input strings similar to NetView Command List Language ...... 62 Parsing input string similar to REXX ...... 63 Parsing input string in CNMSCAN ...... 63 Starting synchronous commands ...... 65 Sending commands...... 65 Waiting and trapping ...... 66 Example of using the TRAP and WAIT commands (PL/I) ...... 66 Example of using the PIPE command (PL/I) ...... 67 Retrieving information...... 69 Command list variable access ...... 70 Accessing common global variables (PL/I) ...... 70 Accessing stem variables using the PIPE command (PL/I)...... 70 Using locks ...... 71 Operator input ...... 72 VIEW Command processor ...... 73 Message processing...... 74 Command authorization checking ...... 75 Command authorization checking using CMDAUTH=TABLE ...... 75 Command authorization checking using CMDAUTH=SAF ...... 76 Command authorization checking sample code ...... 77

Contents v Altering data ...... 78 Storage access ...... 79 Data set access ...... 80 Communicating with devices ...... 81 Performing I/O on a VSAM file (Keyed File Access)...... 83 Coding a DST installation exit ...... 85 Coding an installation exit ...... 86 Coding the WAIT FOR DATA function ...... 87 Requesting data (PL/I) ...... 88 Sending data (PL/I) ...... 89 Automating MSUs ...... 90 Translating code points ...... 91 Registering applications with MS transport and operations management ...... 92 Registering applications with the high-performance transport ...... 94 Sending an alert over the MS transport ...... 95 Sending an alert over the high-performance transport ...... 96 Sending an MDB to NetView for processing ...... 97

Part 4. Writing a C program ...... 101

Chapter 8. Coding your C program interfaces and restrictions ...... 103 Initial parameters ...... 103 C runtime options ...... 103 #pragma runopts ...... 104 z/OS Language Environment preinitialization defaults ...... 104 PSTACK and PHEAP...... 105 LEOPTS static external variable ...... 105 Parameters passed to HLL service routines ...... 105 Pointer variables ...... 106 Integer variables ...... 107 Fixed-length character strings ...... 108 Varying length character strings ...... 108 CNMVLC: converting a string to a varying length character string ...... 110 CNMNVLC: converting a string to a varying length character string using length ...... 111 Control blocks and include files ...... 112 C input/output considerations ...... 113 C runtime considerations ...... 114 Considerations for HLL command processors...... 115 Return codes ...... 115 Restrictions for HLL programs written in C language ...... 115 Restrictions for C programs running in a preinitialized environment ...... 116

Chapter 9. C high-level language services ...... 117 C sample template...... 117 Varying length character strings ...... 119 CNMVLC ...... 119 CNMNVLC ...... 120 Defining varying length character strings ...... 120 Data queue management ...... 121 Sending messages ...... 122 Starting synchronous commands ...... 123 Sending commands ...... 123 Waiting and trapping...... 125 Example of using the TRAP and WAIT commands (C) ...... 125 Example of using the PIPE command (C) ...... 127 Retrieving information ...... 129 Command list variable access ...... 130 Accessing common global variables (C)...... 130 Accessing stem variables using the PIPE command (C) ...... 131 Using locks ...... 133 vi Programming: PL/I and C Operator input ...... 134 VIEW command processor ...... 136 Message processing ...... 137 Command authorization checking ...... 138 Command authorization checking using CMDAUTH=TABLE ...... 139 Command authorization checking Using CMDAUTH=SAF ...... 139 Command authorization checking sample code ...... 140 Altering data ...... 141 Storage access ...... 143 Data set access ...... 144 Communicating with devices ...... 145 Performing I/O on a VSAM File (Keyed File Access) ...... 149 Coding a DST installation exit ...... 151 Coding an installation exit ...... 152 Coding the WAIT FOR DATA function ...... 153 Requesting data ...... 154 Sending data ...... 156 Automating Management Services Units (MSUs) ...... 157 Translating code points ...... 158 Registering applications with MS transport and operations management ...... 158 Registering applications with the high-performance transport ...... 159 Sending an alert over the MS transport...... 160 Sending data over the high-performance transport ...... 161 Sending an MDB to NetView for processing ...... 162

Part 5. HLL debugging and service routine reference ...... 165

Chapter 10. Testing and debugging ...... 167 Using RID to monitor a task ...... 167 RID command ...... 167 RID scenario ...... 169

Chapter 11. Service reference ...... 173 Composite return codes ...... 173 Command reference ...... 175 GLOBALV command ...... 176 GO command ...... 177 PIPE command ...... 177 QUEUE command...... 178 RESET command ...... 179 TRAP command ...... 182 WAIT command ...... 182 HLL service routine reference ...... 183 CNMALTD (CNMALTDATA): alter data on a queue ...... 183 CNMAUTO (CNMAUTOTAB): Invoke automation table ...... 185 CNMCELL (CNMSTRCELL): storage cell ...... 186 CNMCMD (CNMCOMMAND): Invoke NetView commands ...... 187 CNMCNMI (CNMI): CNMI access under a DST...... 189 CNMCPYS (CNMCOPYSTR): Copy storage ...... 190 CNMC2T (CNMCODE2TXT): Code point translation ...... 192 CNMGETA (CNMGETATTR): Query message attributes ...... 193 CNMGETD (CNMGETDATA): Data queue manipulation ...... 204 CNMHRGS (CNMHREGIST): high-performance transport application registration ...... 208 CNMHSMU (CNMHSENDMU): Send high-performance message unit ...... 212 CNMINFC (CNMINFOC): Query NetView Character Information ...... 218 CNMINFI (CNMINFOI): Query NetView Integer Information ...... 221 CNMIPXL (CNMIPXLATE): IP Address Translation ...... 224 CNMKIO (CNMKEYIO): Keyed File Access Under a DST ...... 227 CNMLK (CNMLOCK): Controlling a Lock ...... 229 CNMMEMC (CNMCLOSMEM): Close NetView Partitioned Data Set...... 231

Contents vii CNMMEMO (CNMOPENMEM): Open NetView Partitioned Data Set ...... 232 CNMMEMR (CNMREADMEM): Read NetView Partitioned Data Set ...... 233 CNMNAMS (CNMNAMESTR): Named Storage ...... 234 CNMPMDB (CNMPRSMDB): Process Message Data Block ...... 236 CNMPOOL (CNMSTRPOOL): Storage Pool ...... 237 CNMQAPI (CNMOPREP): Resource Object Data Manager ...... 239 CNMRGS (CNMREGIST): Application Registration ...... 241 CNMSCAN (CNMSSCAN): Parse or Convert Character String–PL/I Only ...... 246 CNMSCOP (CNMSCOPECK): Command, Keyword, and Value Authorization Checking ...... 249 CNMSMSG (CNMSENDMSG): Send Message or Command ...... 251 CNMSMU (CNMSENDMU): Send Message Unit ...... 254 CNMSUBS (CNMSUBSYM): Substitute System Symbolics ...... 261 CNMVARS (CNMVARPOOL): Set or Retrieve Variables ...... 263

Part 6. Appendixes ...... 267

Appendix A. PL/I Control Blocks and Include Files ...... 269

Appendix B. PL/I samples ...... 271 PL/I samples table ...... 271 PTMPPLT (CNMS4200) ...... 272 PEXIT3 (CNMS4210) ...... 272 PSNDDAT (CNMS4211) ...... 272 PWATDAT (CNMS4212) ...... 273 PEXIT2A (CNMS4213) ...... 273 PCNMI (CNMS4214) ...... 273 PKEYIO (CNMS4215)...... 273 PSCOPCK (CNMS4216) ...... 274 PFLVIEW (CNMS4217) ...... 274 PACTLU (CNMS4218) ...... 274 PSEQLOG (CNMS4219) ...... 274 PXITDI (CNMS4220) ...... 274 PXITVN (CNMS4221) ...... 274 PSNDDST (CNMS4222) ...... 275 PDOVSAM (CNMS4223) ...... 275 PPRIME (CNMS4224) ...... 275 PHSNDMU (CNMS4226) ...... 275 PRODMCON (CNMS4230) ...... 275 PAUTOTB (CNMS4231) ...... 275 PREGSTR (CNMS4232) ...... 276 PSENDMU (CNMS4233)...... 276 PHREGSTR (CNMS4236) ...... 276 PPRSMDB (CNMS4239) ...... 276 PACTPIP (CNMS4305) ...... 277

Appendix C. C language control blocks and include files ...... 279

Appendix D. C samples ...... 281 C language samples table ...... 281 CTMPPLT (CNMS4201) ...... 282 CEXIT3 (CNMS4240) ...... 282 CSNDDAT (CNMS4241) ...... 282 CWATDAT (CNMS4242)...... 282 CEXIT2A (CNMS4243) ...... 283 CCNMI (CNMS4244) ...... 283 CKEYIO (CNMS4245) ...... 283 CSCOPCK (CNMS4246) ...... 283 CFLVIEW (CNMS4247) ...... 284 CACTLU (CNMS4248) ...... 284 viii Programming: PL/I and C CSEQLOG (CNMS4249) ...... 284 CXITDI (CNMS4250) ...... 284 CXITVN (CNMS4251) ...... 284 CSNDDST (CNMS4252) ...... 284 CDOVSAM (CNMS4253) ...... 284 CPRIME (CNMS4254) ...... 284 CHSNDMU (CNMS4256) ...... 285 CRODMCON (CNMS4260) ...... 285 CAUTOTB (CNMS4261) ...... 285 CREGISTR (CNMS4262) ...... 285 CSENDMU (CNMS4263) ...... 285 CHREGSTR (CNMS4266) ...... 285 CPRSMDB (CNMS4269) ...... 286 CACTPIP (CNMS4405) ...... 286

Notices ...... 287 Programming Interfaces ...... 289 Trademarks ...... 289 Privacy policy considerations ...... 289

Index ...... 291

Contents ix x Programming: PL/I and C Figures

1. Example of Link-Editing a PL/I Program ...... 44 2. Sample panel definition ...... 74 3. Syntax for PWATDAT ...... 87 4. Flow of the WAIT FOR DATA Function (PL/I) ...... 88 5. Sample Full-Screen View ...... 137 6. Flow of the WAIT FOR DATA Function ...... 154 7. System response to RID invocation ...... 169 8. PL/I Entry Screen for YOURPGM ...... 170 9. Entry Screen for CNMSMSG ...... 171 10. Exit Screen for CNMSMSG ...... 171 11. PL/I Exit Screen for YOURPGM ...... 172 12. Example of command procedure cancellation (1) ...... 180 13. Example of command procedure cancellation (2) ...... 180 14. Example of command procedure cancellation (3) ...... 181 15. Example of command procedure cancellation (4) ...... 181

The IBM® Tivoli® NetView® for z/OS® product provides advanced capabilities that you can use to maintain the highest degree of availability of your complex, multi-platform, multi-vendor networks and systems from a single point of control. This publication, IBM Tivoli NetView for z/OS Programming: PL/I and C, describes how to write command processors and installation exit routines for the NetView product using PL/I and C.

Intended audience This publication is for system programmers who are knowledgeable about PL/I and C and familiar with the functions provided by the NetView program. This publication is also useful for network operators.

Publications This section lists publications in the IBM Tivoli NetView for z/OS library and related documents. It also describes how to access Tivoli publications online and how to order Tivoli publications. IBM Tivoli NetView for z/OS library The following documents are available in the IBM Tivoli NetView for z/OS library: v Administration Reference, SC27-2869, describes the NetView program definition statements required for system administration. v Application Programmer's Guide, SC27-2870, describes the NetView program-to-program interface (PPI) and how to use the NetView application programming interfaces (APIs). v Automation Guide, SC27-2846, describes how to use automated operations to improve system and network efficiency and operator productivity. v Command Reference Volume 1 (A-N), SC27-2847, and Command Reference Volume 2 (O-Z), SC27-2848, describe the NetView commands, which can be used for network and system operation and in command lists and command procedures. v Customization Guide, SC27-2849, describes how to customize the NetView product and points to sources of related information. v Data Model Reference, SC27-2850, provides information about the Graphic Monitor Facility host subsystem (GMFHS), SNA topology manager, and MultiSystem Manager data models. v Installation: Configuring Additional Components, GC27-2851, describes how to configure NetView functions beyond the base functions. v Installation: Configuring Graphical Components, GC27-2852, describes how to install and configure the NetView graphics components. v Installation: Configuring the GDPS Active/Active Continuous Availability Solution, SC14-7477, describes how to configure the NetView functions that are used with the GDPS Active/Active Continuous Availability solution. v Installation: Configuring the NetView Enterprise Management Agent, GC27-2853, describes how to install and configure the NetView for z/OS Enterprise Management Agent.

© Copyright IBM Corp. 1997, 2013 xiii v Installation: Getting Started, GI11-9443, describes how to install and configure the base NetView program. v Installation: Migration Guide, GC27-2854, describes the new functions that are provided by the current release of the NetView product and the migration of the base functions from a previous release. v IP Management, SC27-2855, describes how to use the NetView product to manage IP networks. v Messages and Codes Volume 1 (AAU-DSI), GC27-2856, and Messages and Codes Volume 2 (DUI-IHS), GC27-2857, describe the messages for the NetView product, the NetView abend codes, the sense codes that are included in NetView messages, and generic alert code points. v Programming: Assembler, SC27-2858, describes how to write exit routines, command processors, and subtasks for the NetView product using assembler language. v Programming: Pipes, SC27-2859, describes how to use the NetView pipelines to customize a NetView installation. v Programming: PL/I and C, SC27-2860, describes how to write command processors and installation exit routines for the NetView product using PL/I or C. v Programming: REXX and the NetView Command List Language, SC27-2861, describes how to write command lists for the NetView product using the Restructured Extended Executor language (REXX) or the NetView command list language. v Resource Object Data Manager and GMFHS Programmer's Guide, SC27-2862, describes the NetView Resource Object Data Manager (RODM), including how to define your non-SNA network to RODM and use RODM for network automation and for application programming. v Security Reference, SC27-2863, describes how to implement authorization checking for the NetView environment. v SNA Topology Manager Implementation Guide, SC27-2864, describes planning for and implementing the NetView SNA topology manager, which can be used to manage subarea, Advanced Peer-to-Peer Networking, and TN3270 resources. v Troubleshooting Guide, GC27-2865, provides information about documenting, diagnosing, and solving problems that occur in the NetView product. v Tuning Guide, SC27-2874, provides tuning information to help achieve certain performance goals for the NetView product and the network environment. v User's Guide: Automated Operations Network, SC27-2866, describes how to use the NetView Automated Operations Network (AON) component, which provides event-driven network automation, to improve system and network efficiency. It also describes how to tailor and extend the automated operations capabilities of the AON component. v User's Guide: NetView, SC27-2867, describes how to use the NetView product to manage complex, multivendor networks and systems from a single point. v User's Guide: NetView Enterprise Management Agent, SC27-2876, describes how to use the NetView Enterprise Management Agent. v User's Guide: NetView Management Console, SC27-2868, provides information about the NetView management console interface of the NetView product. v Licensed Program Specifications, GC31-8848, provides the license information for the NetView product. v Program Directory for IBM Tivoli NetView for z/OS US English, GI11-9444, contains information about the material and procedures that are associated with installing the IBM Tivoli NetView for z/OS product.

xiv Programming: PL/I and C v Program Directory for IBM Tivoli NetView for z/OS Japanese, GI11-9445, contains information about the material and procedures that are associated with installing the IBM Tivoli NetView for z/OS product. v Program Directory for IBM Tivoli NetView for z/OS Enterprise Management Agent, GI11-9446, contains information about the material and procedures that are associated with installing the IBM Tivoli NetView for z/OS Enterprise Management Agent. v IBM Tivoli NetView for z/OS V6R2 Online Library, LCD7-4913, contains the publications that are in the NetView for z/OS library. The publications are available in PDF and HTML formats. Related publications You can find additional product information on the NetView for z/OS web site at http://www.ibm.com/software/tivoli/products/netview-zos/.

For information about the NetView Bridge function, see Tivoli NetView for OS/390 Bridge Implementation, SC31-8238-03 (available only in the V1R4 library). Accessing terminology online The IBM Terminology web site consolidates the terminology from IBM product libraries in one convenient location. You can access the Terminology web site at http://www.ibm.com/software/globalization/terminology/.

For NetView for z/OS terms and definitions, see the IBM Terminology web site. The following terms are used in this library: NetView For the following products: v Tivoli NetView for z/OS version 6 release 2 v Tivoli NetView for z/OS version 6 release 1 v Tivoli NetView for z/OS version 5 release 4 v Tivoli NetView for z/OS version 5 release 3 v Tivoli NetView for OS/390® version 1 release 4 v NetView releases that are no longer supported CNMCMD For the CNMCMD member and the members that are included in it using the %INCLUDE statement CNMSTYLE For the CNMSTYLE member and the members that are included in it using the %INCLUDE statement DSIOPF For the DSIOPF member and the members that are included in it using the %INCLUDE statement PARMLIB For SYS1.PARMLIB and other data sets in the concatenation sequence MVS™ For z/OS operating systems MVS element For the base control program (BCP) element of the z/OS operating system VTAM® For Communications Server - SNA Services

About this publication xv IBM Tivoli Network Manager For either of these products: v IBM Tivoli Network Manager v IBM Tivoli OMNIbus and Network Manager IBM Tivoli Netcool/OMNIbus For either of these products: v IBM Tivoli Netcool/OMNIbus v IBM Tivoli OMNIbus and Network Manager

Unless otherwise indicated, topics to programs indicate the latest version and release of the programs. If only a version is indicated, the topic is to all releases within that version.

When a topic is made about using a personal computer or workstation, any programmable workstation can be used. Using NetView for z/OS online help The following types of NetView for z/OS mainframe online help are available, depending on your installation and configuration: v General help and component information v Command help v Message help v Sense code information v Recommended actions Accessing publications online The documentation DVD, IBM Tivoli NetView for z/OS V6R2 Online Library contains the publications that are in the product library. The publications are available in PDF and HTML formats. Refer to the readme file on the DVD for instructions on how to access the documentation.

IBM posts publications for this and all other Tivoli products, as they become available and whenever they are updated, to the Tivoli Documentation Central website at https://www.ibm.com/developerworks/mydeveloperworks/wikis/ home/wiki/Tivoli%20Documentation%20Central

Note: If you print PDF documents on other than letter-sized paper, set the option in the File > Print window that enables Adobe Reader to print letter-sized pages on your local paper. Ordering publications You can order many Tivoli publications online at http://www.ibm.com/e- business/linkweb/publications/servlet/pbi.wss

You can also order by telephone by calling one of these numbers: v In the United States: 800-879-2755 v In Canada: 800-426-4968

In other countries, contact your software account representative to order Tivoli publications. To locate the telephone number of your local representative, perform the following steps: 1. Go to http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss. 2. Select your country from the list and click Go. xvi Programming: PL/I and C 3. Click About this site to see an information page that includes the telephone number of your local representative.

Accessibility Accessibility features help users with a physical disability, such as restricted mobility or limited vision, to use software products successfully. Standard shortcut and accelerator keys are used by the product and are documented by the operating system. Refer to the documentation provided by your operating system for more information.

For additional information, see the Accessibility appendix in the User's Guide: NetView.

Service Management Connect Connect, learn, and share with Service Management professionals: product support technical experts who provide their perspectives and expertise.

Access Service Management Connect at http://www.ibm.com/developerworks/ servicemanagement/z/. Use Service Management Connect in the following ways: v Become involved with transparent development, an ongoing, open engagement between other users and IBM developers of Tivoli products. You can access early designs, sprint demonstrations, product roadmaps, and prerelease code. v Connect one-on-one with the experts to collaborate and network about Tivoli and the NetView community. v Read blogs to benefit from the expertise and experience of others. v Use wikis and forums to collaborate with the broader user community.

Tivoli technical training For Tivoli technical training information, refer to the following IBM Tivoli Education website at http://www.ibm.com/software/tivoli/education.

Tivoli user groups Tivoli user groups are independent, user-run membership organizations that provide Tivoli users with information to assist them in the implementation of Tivoli Software solutions. Through these groups, members can share information and learn from the knowledge and experience of other Tivoli users.

Downloads Clients and agents, NetView product demonstrations, and several free NetView applications can be downloaded from the NetView for z/OS support web site:

http://www.ibm.com/software/sysmgmt/products/support/ IBMTivoliNetViewforzOS.html

In the “Support shortcuts” pane, expand Tivoli NetView for z/OS, and click Fixes (downloads) to go to a page where you can search for or select downloads.

These applications can help with the following tasks:

About this publication xvii v Migrating customization parameters and initialization statements from earlier releases to the CNMSTUSR member and command definitions from earlier releases to the CNMCMDU member. v Getting statistics for your automation table and merging the statistics with a listing of the automation table v Displaying the status of a job entry subsystem (JES) job or canceling a specified JES job v Sending alerts to the NetView program using the program-to-program interface (PPI) v Sending and receiving MVS commands using the PPI v Sending Time Sharing Option (TSO) commands and receiving responses

Support information If you have a problem with your IBM software, you want to resolve it quickly. IBM provides the following ways for you to obtain the support you need: Online Access the Tivoli Software Support site at http://www.ibm.com/software/ sysmgmt/products/support/index.html?ibmprd=tivman. Access the IBM Software Support site at http://www.ibm.com/software/support/ probsub.html. IBM Support Assistant The IBM Support Assistant is a free local software serviceability workbench that helps you resolve questions and problems with IBM software products. The Support Assistant provides quick access to support-related information and serviceability tools for problem determination. To install the Support Assistant software, go to http://www.ibm.com/software/ support/isa/. Troubleshooting information For more information about resolving problems with the NetView for z/OS product, see the IBM Tivoli NetView for z/OS Troubleshooting Guide. Additional support for the NetView for z/OS product is available through the NetView user group on Yahoo at http://groups.yahoo.com/group/ NetView/. This support is for NetView for z/OS customers only, and registration is required. This forum is monitored by NetView developers who answer questions and provide guidance. When a problem with the code is found, you are asked to open an official problem management record (PMR) to obtain resolution.

Conventions used in this publication This section describes the conventions that are used in this publication. Typeface conventions This publication uses the following typeface conventions: Bold v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text v Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) xviii Programming: PL/I and C v Keywords and parameters in text Italic v Citations (examples: titles of publications, diskettes, and CDs v Words defined in text (example: a nonswitched line is called a point-to-point line) v Emphasis of words and letters (words as words example: “Use the word that to introduce a restrictive clause.”; letters as letters example: “The LUN address must start with the letter L.”) v New terms in text (except in a definition list): a view is a frame in a workspace that contains data. v Variables and values you must provide: ... where myname represents... Monospace v Examples and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user v Text that the user must type v Values for arguments or command options Operating system-dependent variables and paths For workstation components, this publication uses the UNIX convention for specifying environment variables and for directory notation.

When using the Windows command line, replace $variable with %variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths. The names of environment variables are not always the same in the Windows and UNIX environments. For example, %TEMP% in Windows environments is equivalent to $TMPDIR in UNIX environments.

Note: If you are using the bash shell on a Windows system, you can use the UNIX conventions. Syntax diagrams The following syntax elements are shown in syntax diagrams. Read syntax diagrams from left-to-right, top-to-bottom, following the horizontal line (the main path). v “Symbols” v “Parameters” on page xx v “Punctuation and parentheses” on page xx v “Abbreviations” on page xxi For examples of syntax, see “Syntax examples” on page xxi. Symbols The following symbols are used in syntax diagrams: ►► Marks the beginning of the command syntax. ► Indicates that the command syntax is continued. | Marks the beginning and end of a fragment or part of the command syntax. ►◄ Marks the end of the command syntax.

About this publication xix Parameters The following types of parameters are used in syntax diagrams: Required Required parameters are shown on the main path. Optional Optional parameters are shown below the main path. Default Default parameters are shown above the main path. In parameter descriptions, default parameters are underlined.

Syntax diagrams do not rely on highlighting, brackets, or braces. In syntax diagrams, the position of the elements relative to the main syntax line indicates whether an element is required, optional, or the default value.

When you issue a command, spaces are required between the parameters unless a different separator, such as a comma, is specified in the syntax.

Parameters are classified as keywords or variables. Keywords are shown in uppercase letters. Variables, which represent names or values that you supply, are shown in lowercase letters and are either italicized or, in NetView help, displayed in a differentiating color.

In the following example, the USER command is a keyword, the user_id parameter is a required variable, and the password parameter is an optional variable.

►► USER user_id ►◄ password

Punctuation and parentheses You must include all punctuation that is shown in the syntax diagram, such as colons, semicolons, commas, minus signs, and both single and double quotation marks.

When an operand can have more than one value, the values are typically enclosed in parentheses and separated by commas. For a single value, the parentheses typically can be omitted. For more information, see “Multiple operands or values” on page xxii.

If a command requires positional commas to separate keywords and variables, the commas are shown before the keywords or variables.

When examples of commands are shown, commas are also used to indicate the absence of a positional operand. For example, the second comma indicates that an optional operand is not being used: COMMAND_NAME opt_variable_1,,opt_variable_3

You do not need to specify the trailing positional commas. Trailing positional and non-positional commas either are ignored or cause a command to be rejected. Restrictions for each command state whether trailing commas cause the command to be rejected.

xx Programming: PL/I and C Abbreviations Command and keyword abbreviations are listed in synonym tables after each command description. Syntax examples The following examples show the different uses of syntax elements: v “Required syntax elements” v “Optional syntax elements” v “Default keywords and values” v “Multiple operands or values” on page xxii v “Syntax that is longer than one line” on page xxii v “Syntax fragments” on page xxii

Required syntax elements: Required keywords and variables are shown on the main syntax line. You must code required keywords and variables.

►► REQUIRED_KEYWORD required_variable ►◄

A required choice (two or more items) is shown in a vertical stack on the main path. The items are shown in alphanumeric order.

►► REQUIRED_OPERAND_OR_VALUE_1 ►◄ REQUIRED_OPERAND_OR_VALUE_2

Optional syntax elements: Optional keywords and variables are shown below the main syntax line. You can choose not to code optional keywords and variables.

►► ►◄ OPTIONAL_OPERAND

A required choice (two or more items) is shown in a vertical stack below the main path. The items are shown in alphanumeric order.

►► ►◄ OPTIONAL_OPERAND_OR_VALUE_1 OPTIONAL_OPERAND_OR_VALUE_2

Default keywords and values: Default keywords and values are shown above the main syntax line in one of the following ways: v A default keyword is shown only above the main syntax line. You can specify this keyword or allow it to default. The following syntax example shows the default keyword KEYWORD1 above the main syntax line and the rest of the optional keywords below the main syntax line. v If an operand has a default value, the operand is shown both above and below the main syntax line. A value below the main syntax line indicates that if you specify the operand, you must also specify either the default value or another value shown. If you do not specify the operand, the default value above the main syntax line is used. The following syntax example shows the default values for operand OPTION=* above and below the main syntax line.

About this publication xxi KEYWORD1 OPTION=* ►► COMMAND_NAME ►◄ KEYWORD1 OPTION= * KEYWORD2 VALUE1 KEYWORD3 VALUE2

Multiple operands or values: An arrow returning to the left above a group of operands or values indicates that more than one can be selected or that a single one can be repeated.

►► KEYWORD= ( ▼ value_n ) ►◄ ,

▼ REPEATABLE_OPERAND_OR_VALUE_1 REPEATABLE_OPERAND_OR_VALUE_2 REPEATABLE_OPERAND_OR_VALUE_3

Syntax that is longer than one line: If a diagram is longer than one line, each line that is to be continued ends with a single arrowhead and the following line begins with a single arrowhead.

►► OPERAND1 OPERAND2 OPERAND3 OPERAND4 OPERAND5 OPERAND6 OPERAND7 ►

► OPERAND8 ►◄

Syntax fragments: Some syntax diagrams contain syntax fragments, which are used for lengthy, complex, or repeated sections of syntax. Syntax fragments follow the main diagram. Each syntax fragment name is mixed case and is shown in the main diagram and in the heading of the fragment. The following syntax example shows a syntax diagram with two fragments that are identified as Fragment1 and Fragment2.

►► COMMAND_NAME Fragment1 ►◄ Fragment2

Fragment1

KEYWORD_A=valueA KEYWORD_B KEYWORD_C

Fragment2

KEYWORD_D KEYWORD_E=valueE KEYWORD_F

xxii Programming: PL/I and C Part 1. Overview

You can use Tivoli NetView for z/OS V6R2 to manage complex, multivendor networks and systems from a single point. This chapter describes NetView services available for designing your command processor or installation exit routine.

Note: Before reading this chapter, review the information in the IBM Tivoli NetView for z/OS Customization Guide. You must have experience with the NetView program and programming experience in PL/I or C for the tasks described in this book.

Running synchronous commands High-level language (HLL) command processors can call any NetView command, including the following commands: v Simple commands v Command lists v REXX command procedures v Assembler command processors v NetView applications such as the session monitor v Other HLL command processors

The command must be executable in the calling environment. For example, data services commands can be called only from a data services command processor.

Sending commands (running asynchronous commands) HLL installation exit routines cannot call NetView commands directly. However, all HLL command processors and installation exit routines can schedule NetView commands to be run asynchronously under any NetView task.

Client and server request response handling The NetView program supports server tasks that service and reply to requests from one or more operator tasks. This is accomplished by the following: v Allowing the requesting command processor to wait for the reply: – The requesting command processor suspends during the wait. – The task continues processing other commands. – The suspended command processor resumes processing after receiving the reply. v Allowing the requests and replies to be sent over NetView-to-NetView cross-domain operator sessions. v Correlating the reply with the correct activation of the requesting HLL command processor. This correlation then allows multiple active instances of the requesting command processor under a single operator task.

Operator interaction The following sections describe operator interaction in line mode and full-screen mode.

Line mode input HLL command processors running under an operator station task (OST), NetView-NetView task (NNT), or primary program operator interface task (PPT) can accept line mode input from an operator. This function is similar to that provided by the NetView command list language &PAUSE statement, except that the HLL command processor can continue to run while waiting for operator input.

Operators do not need to know the language in which a command procedure is written. They can use the GO command to provide input to a command procedure written in the NetView command list language, REXX, or HLL. For more information, see “GO command” on page 177. Line mode output HLL command processors and most installation exit routines can send line mode output to the following receivers: v A NetView operator v The operating system console v Another task v The authorized receiver v A group of operators defined by the NetView ASSIGN command

Multiline messages can be sent as a single unit using a multiline write-to-operator (MLWTO) so that an operator receives them in sequence, with no messages interspersed from other sources. This type of output appears on the command facility panel or on the operating system console. Full-screen input/output HLL command processors can call the NetView VIEW command to provide full-screen interaction with an operator. This function is similar to the use of the VIEW command from a command list. You can also roll among NetView applications, including HLL command processors. HLL command processors are treated like command lists when determining roll groups. NetView also provides the capability to asynchronously update a panel while it is being displayed.

Data access The following sections describe data access techniques available to HLL command processors or installation exit routines. Message trapping Frequently, command procedures must intercept or trap and process messages that usually go to an operator. The NetView HLL application programming interface (API) provides this function for single and multiline messages. NetView message automation NetView message automation can pass both single and multiline messages and their resulting command strings to an HLL command processor. It also provides services to alter the contents of the messages. NetView MSU automation The NetView automation table supports the automation of alerts and management services units (MSUs). NetView MSU automation allows the invocation of HLL

4 Programming: PL/I and C High-Level Language Services

command processors from the automation table upon receipt of MSUs. NetView also provides the command processor with access to the command and the MSU that called the command. System symbolic access HLL command processors and installation exits can query the values of the MVS- and user-defined system symbolics, as well as the local NetView defined &DOMAIN symbol. The &DOMAIN value is unique across the NetView program in which the HLL command processor is running, while the MVS- and user-defined system symbolics are unique across the z/OS system on which they are defined. Command list variable access NetView command lists and assembler command processors can store data in task global and common global command list variables that can be accessed by other command procedures. HLL command processors and installation exit routines can access and update these variables. Querying NetView information HLL command processors and installation exit routines can query certain information (such as domain ID or message attributes) about the current NetView environment. This information is similar to that provided by control variables in the NetView command list language and control block fields in assembly language. VSAM files HLL data services command processors can read, write, update, and delete records in VSAM files associated with the task under which the command processor is running. Other command processors are allowed to run while the input/output (I/O) requests are running.

The pipeline facility supports the use of the CNMCMD service to call DSIVSAM and DSIVSMX to access VSAM files. Refer to the IBM Tivoli NetView for z/OS Command Reference or the NetView online help for information about DSIVSAM and DSIVSMX. Data queue manipulation An HLL command processor or installation exit routine can manipulate HLL data queues. Each HLL command processor and installation exit routine has a set of queues from which it can receive data. Each of these types of input data has a queue: v Operator messages trapped for processing v Input from a NetView operator v Data from another HLL command processor or installation exit routine v Initial data associated with the following messages or MSUs: – The full message or MSU that caused an HLL command processor to be called – The full message that caused DSIEX02A to be called – The multiple domain support message unit (MDS-MU) for unsolicited requests or asynchronous replies v Data solicited over the communication network management (CNM) interface v MDS-MUs received synchronously

Chapter 1. High-level language services 5 High-Level Language Services

Logical Unit 6.2 transport The NetView logical unit 6.2 (LU 6.2) transport is a programming interface that implements designed protocols to enable applications in network nodes to communicate using conversations over LU 6.2 sessions.

The NetView LU 6.2 transport consists of two similar application programming interfaces: the management services (MS) transport and the high performance transport. For applications that run in NetView, each transport provides a high-level programming interface to mask the LU 6.2 complexities. An application registered with the appropriate transport can send data in designed envelopes to a partner application and receive data in return.

Although both transports provide the same functions and mask the LU 6.2 complexities, each transport offers its own advantages.

High Performance Transport v Uses different LU 6.2 protocols that are faster than the protocols used by the MS transport. v Provides general error notification rather than specific error notification about data. v Enables programmers to define session parameters such as RU size.

MS Transport v Uses LU 6.2 conversation protocols that generate more network traffic than the high performance transport protocols to transport each piece of data. v Guarantees delivery of data or specific error notification about the data. Refer to the IBM Tivoli NetView for z/OS Application Programmer's Guide for a more detailed description of the LU 6.2 transports.

Operating remote systems With operations management support, you can use operations management served applications that are provided by the NetView program or written by users to send designed operations management data to be run on remote systems. Operations management makes it possible to have a command routed to the appropriate command processor to be run in the target system, and to get the acceptance reports, completion reports, and other delayed replies from the target system back to the operator controlling that system. In this way, the system can be activated or deactivated by command, the system clock can be set, and other device–specific commands can be set to operate the system remotely.

Communication Network Management Interface HLL data services command processors can send and receive data over the communication network management (CNM) interface. The CNM interface is used to forward commands to and collect data from devices in the network. For example, response time monitor (RTM) data is collected from PU type 2 control units using the CNM interface. HLL command processors can also process unsolicited data received over the CNM interface. Solicited replies are pseudo-synchronous.

6 Programming: PL/I and C High-Level Language Services

NetView partitioned data sets HLL command processors and installation exit routines have read access to the NetView partitioned data sets. This enables you to write a program using the information in the NetView partitioned data sets. This function is completely synchronous.

Dynamic file allocation/deallocation NetView provides facilities to dynamically allocate and deallocate files by using NetView ALLOCATE and FREE commands. Refer to the NetView online help for more information.

When allocated, these files can be accessed using the file I/O facilities present in the language being used.

Storage copying HLL command processors and installation exit routines can make a copy of any area of virtual storage in the NetView address space in which the HLL command processor or installation exit routine is running. A request to copy an area outside of this space results in a return code instead of an 0C4 ABEND. This feature is useful for debugging because it enables you to intercept and act upon a return code instead of failing with a hard abend.

Note: Ensure that the storage area to which the copy is made belongs to your program.

Named storage HLL command processors or installation exit routines can allocate and free an area of virtual storage and associate a name with it so that other HLL command processors and installation exit routines running under the same task can access this area of storage. Transaction-oriented applications can use this function to save data across transactions.

User-defined lock management HLL command processors and installation exit routines can obtain, release, and test the control of a named lock. The lock management scheme uses a simple alphanumeric hierarchy. Locking is useful when updating common global variables, or to serialize any other common resource.

Parsing character strings A parsing service is provided as part of the HLL support for PL/I. This service is similar to the SSCANF function available in the C language and is intended to facilitate the parsing of commands and messages.

Command authorization checking The NetView command authorization services can be called by HLL command processors and installation exit routines to determine whether a particular operator is authorized to issue a command with restricted operands or operand values.

Chapter 1. High-level language services 7 High-Level Language Services

NetView message logging All HLL command processors and most installation exit routines can send message output to the following logs: v The network log v An external log such as system management facilities (SMF) v A sequential log

NetView Bridge The NetView Bridge option allows data to be transported between a NetView system running in a z/OS environment and a non-NetView database. This option is useful when you must access a non-NetView database to create and update problem records, or to access and retrieve configuration data. The NetView Bridge is also an effective means of connecting an active NetView installation to other databases by using user-written command procedures.

For additional information about the NetView Bridge option, refer to the Information Management for z/OS Guide to Integrating with Tivoli Applications.

NetView Bridge remote access The NetView Bridge remote access option enables you to access servers that reside on hosts other than the one in which the transaction was generated. You can collect data from the resources in your network, and create and update records in a database residing in another system. NetView Bridge remote access can operate from a NetView program running on a z/OS operating system. Transactions are forwarded to the resident host by using the high performance transport API to access a z/OS system running both NetView Bridge and NetView Bridge remote access.

Debugging support The NetView HLL API provides two debugging tools for users: an interactive debugger that displays the operands and results of all HLL API service routine invocations, and a continuous first failure data capture trace for ABEND debugging.

In addition, you can use the NetView internal trace. For more information, see the IBM Tivoli NetView for z/OS Troubleshooting Guide. Remote Interactive Debugger (RID) The RID enables NetView HLL service routine calls to be trapped and displayed to the programmer. You can implement RID using NetView commands and messages to create debugging procedures using NetView command list language, REXX, or HLL command procedures. In addition, because the NetView program provides facilities to route commands and messages to remote systems, use RID from one system to debug an HLL command processor or installation exit routine running on another system.

RID operates at the subtask level, so using RID to stop an HLL command processor or installation exit routine running under one subtask does not affect other subtasks in the same NetView address space.

8 Programming: PL/I and C High-Level Language Services

First Failure Data Capture Trace (FFDCT) Each HLL command processor or installation exit routine maintains an 8-entry continuously wrapping trace area. Trace entries are recorded at entry to, and exit from, HLL service routines and at other key points inside the HLL routines. In the event of an ABEND, this area gives some indication of what was occurring before the ABEND. For more information, see the IBM Tivoli NetView for z/OS Troubleshooting Guide.

Chapter 1. High-level language services 9 10 Programming: PL/I and C Chapter 2. HLL installation exit routines

This chapter contains product-sensitive programming interfaces and associated guidance information provided by the NetView program.

You can write installation exit routines to view, delete, or replace data flowing to, from, or through the NetView program. For example, your code can examine the messages passing through the NetView program, record relevant data, and initiate work requests based on the data. In addition, your code can delete any unnecessary messages from further processing or substitute a modified message in place of the original message. Thus, installation exit routines can handle a specific event with nonstandard processing and automate processes based on message information.

Overview of installation exit routines There are two types of installation exits for which you can write routines: v Global installation exits (DSIEXnn), which apply to all NetView tasks. The global installation exit routines are loaded when the NetView program starts. See Table 1 on page 13 for a list of installation exits. v DST installation exits (XITnn and BNJPALEX), which apply only to DSTs. The DST installation exit routines are loaded when their DST starts. Each DST can have its own set of installation exit routines.

Note: Changes do not take effect until you recycle the NetView program.

Each installation exit handles a particular event, such as the reception of data from the system console. When that event occurs, control is passed to the appropriate installation exit routine for processing. After processing, the installation exit routine returns control and passes a return code to the NetView program. Optionally, up to 10 DST installation exit routines can be concatenated. If the first exit did not indicate USERDROP, the NetView program then calls the next one in the sequence. This process continues until the last DST exit has returned control to the program.

For more information about input to the installation exit routines, see Chapter 6, “Coding HLL command processors and installation exits,” on page 49 and Chapter 8, “Coding your C program interfaces and restrictions,” on page 103. Coding restrictions The following HLL service routines cannot be called from any installation exit: v CNMCMD v CNMCNMI v CNMKIO

In addition, CNMSMSG cannot be issued from DSIEX04 and DSIEX09. Only CNMSMSG with a destination type of TASK can be issued from DSIEX02A. DSIEX02A, DSIEX04, and DSIEX09 can be called only in the mainline environment if written in HLL. If written in assembler, these installation exit routines can be called in both the mainline and the interruption request block (IRB) exit environments. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for additional information about exits running in the IRB exit environment.

Performance considerations Preinitialized environments can significantly improve the performance of installation exits written in PL/I and C. Instead of repeatedly allocating and deallocating environments for each invocation of an installation exit routine, the NetView program manages global pools of preinitialized environments. Exit routines can then run in these environments, without initializing them, each time an exit program is run.

Preinitialized environments are supported in all NetView-supported releases of PL/I and in the z/OS Language Environment®. See Chapter 4, “Preinitialized and non-preinitialized environments,” on page 33 for more information about preinitialized environments.

Note: Programs compiled with Enterprise PL/I for z/OS cannot use NetView's preinitialized language environments.

Avoid coding installation exits for frequently called functions, such as VSAM input/output (I/O), because performance can be degraded significantly. General return codes Unless otherwise noted, installation exit routines pass the following return codes to the NetView program in the return code field (HLBRC for PL/I or Hlbrc for C) to indicate that the messages are to be unchanged, deleted, or replaced: USERASIS (0) Use the message as presented to the installation exit; do not delete or replace it. USERDROP (4) Delete the message from the terminal and from the network log, system log, and hardcopy log; stop processing before the message appears on the screen. For more information about how to delete messages, see “Deleting messages.” USERSWAP (8) Replace the message with the modified CMDBUF (Cmdbuf). For more information, see “Replacing messages.” Deleting messages To delete a message entirely, use return code USERDROP.

When the NetView program receives a USERDROP return code, no further installation exit routines are called. Thus, if you have concatenated DST installation exit routines, a USERDROP return code prevents the next installation exit routine from being called. Replacing messages To replace a message, use return code USERSWAP and set the input CMDBUF (Cmdbuf) contents to the desired data. For installation exits written in PL/I, the replacement data must be less than or equal in length to the original CMDBUF (Cmdbuf) data; otherwise it is truncated to the original length of the CMDBUF (Cmdbuf) data.

12 Programming: PL/I and C HLL Installation Exit Routines

For installation exits written in C, the replacement data must be less than or equal in length to the original CMDBUF (Cmdbuf) data. If the replacement data is longer than the original data, storage overlay can occur which causes abends and other unpredictable results.

Installation exit DSIEX02A provides a more flexible interface for replacing messages using CNMALTD. See “CNMALTD (CNMALTDATA): alter data on a queue” on page 183.

You can concatenate DST installation exit routines when replacing messages. In this case, the buffer containing the replacement message becomes the input for the subsequent DST installation exit routine. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for message flows.

Table 1 lists all HLL installation exits and the task environments under which they can be called. Table 1. Installation Exit Environments Exit Description Applicable Tasks Associated Samples BNJPALEX Not supported in HLL DSIEX01 Not supported in HLL DSIEX02A Message output this domain NNT, OST, PPT NNT, OST, CNMS4213, CNMS4243 or CNMCSSIR Message output cross-domain DSIEX03 Input before command processing (1) NNT, OST, PPT CNMS4210, CNMS4211, CNMS4212, CNMS4240, CNMS4241, CNMS4242 DSIEX04 Log output for buffers not processed by Main task or any subtask DSIEX02A DSIEX05 Before VTAM command invocation (2) NNT, OST, PPT DSIEX06 Solicited VTAM messages (2) NNT, OST, PPT DSIEX07 Cross-domain command send NNT, OST DSIEX09 Output to the system console Main task or any subtask DSIEX10 Input from the system console DSIWTOMT DSIEX11 Unsolicited VTAM messages (2) PPT DSIEX12 Logon validation NNT, OST DSIEX13 OST/NNT message receiver NNT, OST, PPT DSIEX14 Before logging off NNT, OST DSIEX16 Not supported in HLL DSIEX16B Not supported in HLL DSIEX17 Not supported in HLL DSIEX18 Not supported in HLL DSIEX19 Service point application authorization NNT, OST, PPT checking during RUNCMD processing DSIEX20 Not supported in HLL DSIEX21 Encryption key for DSITCPRF CNMTAMEL DSIEX21 XITBN BSAM empty file DST XITBO BSAM output DST

Chapter 2. HLL installation exit routines 13 HLL Installation Exit Routines

Table 1. Installation Exit Environments (continued) Exit Description Applicable Tasks Associated Samples XITCI CNM interface input DST XITCO CNM interface output DST XITDI DST initialization DST CNMS4220, CNMS4223, CNMS4250, CNMS4253 XITVI VSAM input DST XITVN VSAM empty file DST CNMS4221, CNMS4223, CNMS4224, CNMS4245, CNMS4251, CNMS4253, CNMS4254 XITVO VSAM output DST XITXL External logging DST Note: 1. This includes a buffer of type HDRTYPEX received from an NNT. A buffer of type HDRTYPEX, when received by the secondary LU in an OST-NNT or NNT-NNT session, is treated as a command. 2. When using NetView POI only. Does not include VTAM messages from other sources, such as the subsystem interface (SSI). You can process these messages in DSIEX02A.

Installation exits The NetView program provides a number of installation exits that are described in the following sections. For a description of message flows and interception points in OSTs, NNTs, and PPTs, refer to IBM Tivoli NetView for z/OS Programming: Assembler. BNJPALEX: Alert generation exit routine This exit is available only through assembly language. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for a description of the exit. DSIEX01: Input from the operator This exit is available only through assembly language. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for a description. DSIEX02A: Output to the operator Description: The NetView program calls DSIEX02A just before &WAIT (or WAIT) message processing and before the automation table is scanned to determine processing actions. DSIEX02A is called for standard output to an operator’s terminal. DSIEX02A runs before the device-dependent output is inserted and the data is logged. If DSIEX02A is called, DSIEX04 is not called because logging options can be specified in either DSIEX02A or the NetView automation table.

Example of Use: Because the message has been formatted but not yet displayed or logged, you can use DSIEX02A to delete or replace the message before it is automated, logged, or displayed. Messages are reformatted by removing, changing, and adding new buffers to the original message. DSIEX02A prevents OVERRIDE command options from taking effect for messages.

Changes to the English message text are not reflected in the translated messages.

14 Programming: PL/I and C HLL Installation Exit Routines

CNMSMSG can be issued from DSIEX02A, but only with the destination type of TASK. The message resulting from the CNMSMSG call does not re-drive DSIEX02A.

Return Codes: The DSIEX02A user exit sets register 15 to 0 when it returns control to the NetView program.

Note: 1. Do not use the USERSWAP return code to swap messages. Use the CNMALTD service. See “CNMALTD (CNMALTDATA): alter data on a queue” on page 183 2. Messages issued by DSIPSS with TYPE=FLASH are not exposed.

DSIEX02A is supported only in 31-bit addressing mode. DSIEX03: Input before command processing Description: All regular commands call DSIEX03. Regular commands include commands: v Issued by a command procedure v Received from another subtask v Used to start the hardcopy log at logon v Used as the initial command v Entered as simulated terminal input v Resulting from the NetView automation table v Entered for an MVS console operator task v Entered from a terminal v Received as HDRTYPEX messages from an NNT v Queued using the EXCMD command

Before running, all commands are passed to either DSIEX01 or DSIEX03. Immediate commands are passed to DSIEX01. Regular commands entered from a command facility panel are passed to DSIEX01 and DSIEX03. The remaining command types previously listed are passed to DSIEX03.

Example of Use: If your conditions are more complex than those provided by the authority table for NetView commands, you can use DSIEX03 to restrict the use of particular regular commands. DSIEX04: Log output Description: The NetView program calls DSIEX04 during the logging and tracing process. DSIEX04 is located within log services and applies to messages logged on the network log, the external trace log, the MVS system log, and the hardcopy log. It runs before the message is reformatted and sent to the log. DSIEX04 is not called if DSIEX02A is called, because logging options can be specified in either DSIEX02A or the NetView automation table.

Chapter 2. HLL installation exit routines 15 HLL Installation Exit Routines

Example of Use: Use DSIEX04 to edit information sent to the network log, the MVS system log, or the hardcopy log. You can use DSIEX04 to send certain messages to a specific log or to no log at all.

Coding Considerations: DSIEX04 can run under any subtask that initiates message logging. Ensure that any HLL services you request are supported by the subtask under which the routine is running. To determine the subtask under which your routine is running, see the TASK option under icname in “CNMINFC (CNMINFOC): Query NetView Character Information” on page 218.

Return Codes: In addition to USERASIS, USERDROP, and USERSWAP, DSIEX04 can pass these codes: Return Code Meaning USERLOG (12) Write the message to the network or MVS system log only. USERLOGR (16) Write the substituted message to the network or MVS system log only. USERHCL (20) Write the message to the hardcopy log only. USERHCLR (24) Write the substituted message to the hardcopy log only. USERNSL (28) Do not write to the MVS system log. USERNSLR (32) Do not write to the MVS system log. Use the substituted message to write to the network log, external trace log, and the hardcopy log. DSIEX05: Before VTAM command invocation Description: The NetView program calls DSIEX05 when preparing to pass a command to VTAM through the program operator interface (POI); domain qualifiers have been removed and all span checking has been completed.

Example of Use: You can use DSIEX05 to verify that an operator is authorized to issue a particular command.

Coding Considerations: This exit applies only to commands entered directly, without using the MVS command, that are passed through NetView’s POI.

Commands passed to DSIEX05 have already been processed under DSIEX03 (and possibly DSIEX01). DSIEX06: Solicited VTAM messages Description: The NetView program calls DSIEX06 when it receives a solicited VTAM message, which is generated in response to a VTAM command the user or the PPT issued. The message has not yet been processed or logged.

Example of Use: You can use DSIEX06 to change the message number or text of a VTAM message or to process VTAM messages.

16 Programming: PL/I and C HLL Installation Exit Routines

Coding Considerations: This exit applies only to responses to commands entered directly, without using the MVS command, that are passed through the NetView POI.

NetView automation is called after this installation exit routine has been called. Therefore, any changes made to messages in this installation exit can affect NetView automation. NetView automation is not called for a message that has been deleted by this installation exit routine.

Messages processed (and not dropped) in DSIEX06 are later processed by DSIEX02A. DSIEX07: Cross-domain command send Description: The NetView program calls DSIEX07 before commands are sent cross-domain to an NNT.

Example of Use: You can use DSIEX07 to monitor cross-domain traffic through the network. DSIEX09: Output to the system console Description: The NetView program calls DSIEX09 when a message is written to the system console operator using the DSIWCS macro. The message has not been formatted for transmission. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for a description of the DSIWCS macro.

Example of Use: You can use DSIEX09 to edit messages sent to the system console.

Coding Considerations: DSIEX09 is called as a result of DSIWCS macro calls. The output of the MVS console OST is processed by DSIEX02A instead of DSIEX09. DSIEX10: Input from the system console Description: The NetView program calls DSIEX10 when input is received from the system console operator. The exit is called after the command has been entered, but before it is called or logged.

Example of Use: You can use DSIEX10 so the system console operator can enter command abbreviations and synonyms. These can then be expanded in the installation exit routine.

Coding Considerations: DSIEX10 can be called only from the DSIWTOMT task, not from a subtask.

DSIEX10 is not called for commands entered by an operator using an MVS OST. DSIEX03 is called instead of DSIEX10. DSIEX11: Unsolicited VTAM messages Description: The NetView program calls DSIEX11 when an unsolicited VTAM message is received through the POI interface. When the VTAM PPOLOG=YES modify or start option is used, copies of the messages are presented to DSIEX11. This installation exit is called before the resource name is analyzed and before the message is logged.

Example of Use: DSIEX11 can issue CNMSMSG to send a copy of the message buffer prior to processing by the NetView program.

Chapter 2. HLL installation exit routines 17 HLL Installation Exit Routines

Coding Considerations: NetView automation is called after this installation exit routine has been called. Therefore, any changes made for messages in this installation exit can affect NetView automation. NetView automation is not called for a message that is deleted by this installation exit routine. DSIEX12: Logon validation Description: The NetView program calls DSIEX12 at the completion of the logon process, after the logon has been accepted by the NetView program.

Example of Use: You can use DSIEX12 to perform additional checking of authorization and environmental customization. DSIEX12 can also send messages to other operators.

Non-Takeover and Takeover Operator Task Processing: When DSIEX12 gets control for a non-takeover or a takeover operator task, the input to DSIEX12 includes the takeover operator ID name field.

For a non-takeover logon, the operator ID is listed in the Operator ID name field and the Takeover Operator ID field is blank.

For a takeover logon, the value "takeover" is listed in the Operator ID field and the Takeover Operator ID name field contains the operator ID that is taken over.

For a takeover operator task, DSIEX12 is called mainly to validate the operator ID and password. Therefore, first check the Operator ID field to determine if this exit was called for a takeover operator task.

Coding Considerations: If the installation exit routine issues a return code of 0, the logon proceeds. If specified, your hardcopy log starts and the initial command runs. If the issued return code is nonzero, the operator is logged off.

This exit is called under all OSTs and NNTs, including unattended operator and MVS console operator tasks.

The accompanying structure maps the header information in the CMDBUF buffer (Cmdbuf) that is passed to the DSIEX12 exit. OFFSET and LENGTH values are given in bytes. Table 2. DSIEX12 Command buffer parameter field descriptions Offset Length Function 0 8 Operator ID name or "takeover" 8 8 Operator LU name 16 8 Password 24 8 Hardcopy device name 32 8 Profile name 40 8 New password 48 8 Takeover Operator ID. The operator ID that is taken over when operator ID is "takeover".

18 Programming: PL/I and C HLL Installation Exit Routines

DSIEX13: OST/NNT message receiver Description: When certain subtask-subtask communication buffers are received on a subtask resulting from the use of the DSIMQS macro on another task, the NetView program calls DSIEX13. DSIEX13 is called when: v A user-defined internal function request (IFRCODCR) is received through the DSIMQS macro for an OST, a NetView-to-NetView task (NNT), or a primary POI task (PPT). v A message buffer (with HDRMTYPE=HDRTYPEM) is received through the DSIMQS macro on OSTs or NNTs.

Note: The DSI039I message is an example of a HDRTYPEM message received by an OST or NNT. The DSI039I message has a HDRMTYPE=HDRTYPEN when sent to the PPT. In addition, the PPT does not call DSIEX13 for any other HDRTYPEM buffer.

Example of Use: You can use DSIEX13 with IFRCODCR to initiate a user function with a buffer. Code DSIEX13 to perform the user function specified by IFRCODCR. The IFRCODCR message buffer can be sent (using the DSIMQS macro) to another task or queued to the task that you are running. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information about internal function requests.

You can also use DSIEX13 to monitor DSI039I messages received by OSTs or NNTs.

Coding Considerations: DSIEX13 must not free (DSIFRE) the IFRCODCR or HDRTYPEM buffers.

Return Codes: HDRTYPEM messages and IFRCODCR buffers are treated differently: v The NetView program does not process IFRCODCR buffers after DSIEX13 is called. The NetView program frees the buffer using DSIFRE. This method is consistent with the method used with other buffers that are received through DSIMQS. v HDRTYPEM buffers are displayed unless the return code USERDROP is used. The following occur for displayed messages just as for typical NetView messages: – DSIEX02A and DSIEX16 exits are called. – Automation is called. – Automation table processing occurs. – The messages are logged. DSIEX14: Before logoff Description: The NetView program calls DSIEX14 when an OST or NNT is preparing to end for any of these reasons: v If LOGOFF is entered at the operator’s terminal. v If the subtask LOSTERM exit is driven (VTAM). v If the subtask is posted to end.

The exit cannot communicate with the operator’s terminal. However, you can write to the system console and write entries to the log.

Example of Use: You can use DSIEX14 to save accounting information, update tables, or free storage.

Chapter 2. HLL installation exit routines 19 HLL Installation Exit Routines

Non-Takeover and Takeover Operator Task Processing: For a non-takeover operator task, the NetView program calls DSIEX12 after a logon is accepted. When the task ends (for example, the operator logs off), the NetView program calls DSIEX14.

For a takeover operator task, the NetView program calls DSIEX12 as mentioned above. For this type of task, DSIEX12 is called mainly to validate the operator ID and password. When the takeover processing completes, the task for the session that is being taken over is the task used for the session, and the takeover operator task is cleaned up. For the takeover task processing, the NetView program does not call DSIEX14.

Coding Considerations: Because a buffer is not associated with logoff processing, DSIEX14 does not receive an input buffer (the length of the command buffer is 0).

Return Codes: The NetView program ignores any return code received from this installation exit routine. DSIEX16: Post-automation table installation exit for messages This exit is available only through an assembler interface. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. DSIEX16B: Post-automation table installation exit for MSUs This exit is available only through an assembler interface. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. DSIEX17: MVS message and DOM receive This exit is available only through an assembler interface. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. DSIEX18: Log browse installation exit This exit is available only through an assembler interface. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. DSIEX19: RUNCMD Installation exit Description: The NetView RUNCMD exit DSIEX19 is called after usual command security checking has authorized the use of the RUNCMD command. The text following the RUNCMD command verb is passed to the exit.

Example of Use: You can use DSIEX19 to provide security checking at the service point command level. This security checking can be done by calling CNMSCOP or by using your own technique. To use CNMSCOP for security checking, you can define a CMDDEF statement in CNMCMD specifying DSISPCMD. You can then define command, keyword, and value authorization checking based on the CMDDEF statement. For example, to define the service point command ADP to enable checking with CNMSCOP, define: CMDDEF.ADP.MOD=DSISPCMD

Coding Considerations: The following input is provided to DSIEX19 upon invocation of the exit in the DSIUSE control block: v DSIEX19 is passed a read-only copy of a command buffer in the USERMSG field. Table 3 on page 21 shows the exit parameters in the CMDBUF passed to the exit.

20 Programming: PL/I and C HLL Installation Exit Routines

Table 3. DSIEX19 Command buffer parameter field descriptions Offset Length Description 0 8 User ID against which command authorization checking was done for the RUNCMD. 8 8 Reserved. 16 80 Security product token for the source issuer of the RUNCMD, if available. 96 8 The service point name entered on the RUNCMD. 104 8 The service point application entered on the RUNCMD. 112 8 The NETID entered on the RUNCMD. 120 2 Length of the service point command string. 122 Variable The service point command string. The length of the string varies, dependent on the individual command string.

v Other DSIUSE fields passed are: USERLU, USEROPID, USERSWB and USERTVB. The value of the USERPDB field is set to zero (0).

Return Codes: DSIEX19 can pass these return codes: USERASIS Continue RUNCMD processing to send the command to the service point. Any return code other than USERASIS Discontinue RUNCMD processing. Message BNH192E is to be issued indicating that processing of the RUNCMD has stopped. DSIEX20: SAW exit This exit is available only through an assembler interface. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. DSIEX21: Encryption key for DSITCPRF installation exit The DSIZKNYJ command is used to edit encrypted definition member DSITCPRF in DSIPRF. Refer to the IBM Tivoli NetView for z/OS Security Reference for more information. XITBN: BSAM empty file Description: The DST calls XITBN if the DST encounters a BSAM open failure because of an empty data set or file.

Example of Use: You can use XITBN to place a record in the empty data set. Code this installation exit only if you want to write a BSAM subtask using the DST as a base.

Coding Considerations: XITBN can use only the service facilities available to the DST.

Return Codes: To initialize the BSAM data set or file, return the USERSWAP return code and set the command buffer to the record to be used. A return code other than USERSWAP causes the DST to end.

Chapter 2. HLL installation exit routines 21 HLL Installation Exit Routines

XITBO: BSAM output Description: The DST calls XITBO immediately before the record is written to the BSAM database.

Example of Use: You can use XITBO to modify the record before it is sent to the BSAM data set or file.

Coding Considerations: XITBO can use only the service facilities available to the DST.

Avoid coding installation exits for frequently called functions, such as BSAM I/O, because performance can be degraded significantly. XITCI: CNM interface input Description: The DST calls XITCI after communication network management (CNM) interface data is received through the CNM interface or MS transport.

Example of Use: You can use XITCI to modify CNM input data for the hardware monitor.

Coding Considerations: XITCI can use only the service facilities available to the DST.

If you specify USERSWAP (8), the substitute buffer must contain a valid network services request unit (RU) of the same type as the input RU. Refer to the SNA library for a description of RU formats.

DSICRTR is the subtask responsible for routing RECMS, RECFMS, ROUTE-INOP, CNM, NMVT, and cross-domain alerts. XITCI called under the DSICRTR subtask provides access to unsolicited CNM data before the NetView program routing.

Control point management services units (CP-MSUs) and MDS-MUs are not routed through DSICRTR and are only accessible under the BNJDSERV subtask.

XITCI called under a DST other than DSICRTR can access CNM data routed to that particular subtask.

Network services request units are routed as shown in Table 4. Table 4. Routing of Network Services Request Units Request Header Value Receiving Subtask RECMS X'010381' BNJDSERV RECFMS X'410384' AAUTSKLP, BNJDSERV ROUTE-INOP X'410289' AAUTSKLP CNM X'810814' AAUTSKLP NMVT X'41038D' AAUTSKLP, BNJDSERV, DSIGDS CP-MSU X'1212' BNJDSERV, DSIGDS MDS-MU X'1310' BNJDSERV, DSIGDS Cross-domain alert X'1040' BNJDSERV

22 Programming: PL/I and C HLL Installation Exit Routines

For the various receiving subtasks listed, Table 5 shows the major vector keys that can be found in the specific RU. Table 5. Routing of RUs by Major Vector Key Major Vector Key Description Receiving Subtask X'0000' Alert BNJDSERV X'0001' Link event BNJDSERV X'0002' Resolution BNJDSERV X'000F' CMIP statistics BNJDSERV X'0010' Trace AAUTSKLP X'0025' PD statistics BNJDSERV X'006F' Send message to operator DSIGDS X'0080' RTM AAUTSKLP X'132E' RECFMS envelope BNJDSERV X'1332' Link configuration data BNJDSERV X'13FF' Reserved BNJDSERV X'154D' Routing and targeting instruction BNJDSERV

The focal point transfer RU header is part of the communication network management (CNM) router support. All cross-domain unsolicited alert data is routed to the CNM router, and the focal point transfer RU header carries management services information between distributed host and the focal point.

The fields in the focal point transfer RU header are listed in Table 6. Table 6. Focal Point transfer RU header Offset Name Length Description 0 HDR LEN 2 bytes, binary Length of the total RU (includes RU header and NMVT) 2 HDR ID 2 bytes Always X'1040' 4 Reserved 11 bytes For NetView use only 15 DOMID LEN 1 byte, binary Originator's domain ID length 16 DOMAIN ID 8 bytes, char Originator's domain ID, padded with blanks 24 Reserved 20 bytes For NetView use only 44 Name Variable NMVT data

If the data is an alert forwarded using the NV-UNIQ/LUC alert forwarding protocol, the first 44 bytes of the data are mapped by the focal point transfer RU and the remainder of the data is the actual network management vector transport (NMVT).

The first 2 bytes of the focal point transfer RU contain the length of the entire buffer (FPT RU + NMVT). The next 2 bytes contain the header ID, which is always X'1040'. The 16th byte contains the length of the originating domain ID. When returning a substitute buffer, do not modify the focal point transfer RU (the first 44 bytes); replace only the NMVT portion of the buffer with a valid NMVT.

Chapter 2. HLL installation exit routines 23 HLL Installation Exit Routines

For more information about the format of a specific RU, refer to the SNA library and NCP and EP Reference Summary and Data Areas.

Return Codes: XITCI can use two other return codes in addition to USERASIS, USERDROP, and USERSWAP. USEREXLG (252) The hardware monitor, running under the BNJDSERV task, records the message only to system management facilities (SMF) and then discards it. No data is logged to the database. This processing is the same for all alerts including forwarded alerts. This occurs when you designate NPDA REPORTS ON. Refer to the NetView online help for more information about the REPORTS command. USEREVNT (253) The hardware monitor, running under task BNJDSERV, records the message as an event or statistic on its database, but not as an alert. The hardware monitor recording filters are not applied to the message as they would be normally. Instead, the ESREC filter is set to PASS and all other recording filters are set to BLOCK. For SNA-MDS forwarded alerts from non-NetView entry points, only event data is recorded to the database; this processing is the same as for local alerts that are not forwarded. For NV-UNIQ/LUC alert forwarding protocol forwarded alerts and SNA-MDS forwarded alerts from an entry point NetView, no data is recorded to the database. Refer to the description for the SRFILTER command in the NetView online help for an explanation of the recording filters.

Note: Some alerts displayed by the hardware monitor do not drive the XITCI installation exit and are, therefore, still logged as alerts. One example is the alerts generated by the 4700 Support Facility.

If return code USEREXLG (252) or USEREVNT (253) is returned for an input record, the input record is not processed as an alert. The hardware monitor alert recording filter is not passed, so the input record is not forwarded to the alert focal point.

Messages that are blocked as a result of a filter from the rate function might not be automated. You can use the AUTORATE statement to control this.

Refer to the RATE and AUTORATE statements in the IBM Tivoli NetView for z/OS Administration Reference for information about these statements. XITCO: CNM interface output Description: The DST calls XITCO prior to a request for CNM interface output.

Example of Use: You can use XITCO to modify the request for CNM data (forward RU).

Coding Considerations: XITCO can use only the service facilities available to the DST. If a substitute buffer is returned, the data must be a valid SNA RU.

Refer to the SNA library for a description of RU formats.

24 Programming: PL/I and C HLL Installation Exit Routines

XITDI: Data services task initialization Description: The DST calls XITDI for each statement read by the DST during initialization. When the end of file is reached, this installation exit is entered and the length of the input command buffer is 0. You can code up to 10 module names for each user-written exit routine. See Chapter 3, “HLL Data Services command processors,” on page 27 for more information about XITDI during DST initialization.

Example of Use: You can add XITDI to the DST initialization deck to provide user initialization values to DST initialization.

Coding Considerations: Do not replace the DST XITDI exits that are provided with the NetView program.

XITDI can use only the service facilities available to the DST subtask.

Note: If all initialization data is to be processed by XITDI, specify the DST initialization statement that identifies XITDI as the first statement in the DST initialization member.

Return Codes: XITDI can prevent the DST from processing a definition statement by passing return code USERDROP.

When XITDI is called for an end-of-file situation, a nonzero return code indicates that the DST must be stopped. XITVI: VSAM input Description: The DST calls XITVI after a CNMKIO call for input is issued. The record has been read from the VSAM database, but it is not yet passed to the requesting data services command processor.

Example of Use: You can use XITVI to modify the record after it has been retrieved from a VSAM data set or file.

Coding Considerations: XITVI can use only the service facilities available to the DST.

Avoid coding installation exits for frequently called functions, such as VSAM I/O, because performance can be degraded significantly. XITVN: VSAM empty file Description: The DST calls XITVN if the DST encounters a VSAM open failure because of an empty data set or file.

Example of Use: You can use XITVN to place a record in the empty data set. The NetView program provides its own XITVN for VSAM logs generated under DST. Code this installation exit only if you want to write your own VSAM subtask using DST as a base.

Coding Considerations: XITVN can use only the service facilities available to the DST.

Note: 1. Only VSAM key-sequenced data sets are supported.

Chapter 2. HLL installation exit routines 25 HLL Installation Exit Routines

2. Do not replace the XITVN exits that are provided with the NetView program for the DSILOG and DSITRACE subtasks.

Return Codes: To initialize the VSAM data set or file, return the USERSWAP return code and set the command buffer to the record to be used. A return code other than USERSWAP causes the DST to end. XITVO: VSAM output Description: The DST calls XITVO immediately before the record is written to the VSAM database through the CNMKIO service.

Example of Use: You can use XITVO to modify the record before it is sent to the VSAM data set or file.

Coding Considerations: XITVO can use only the service facilities available to the DST. The text portion is mapped by DSILOGDS when using this exit for the DSILOG task.

Avoid coding installation exits for frequently called functions, such as VSAM I/O, because performance can be degraded significantly. XITXL: External logging Description: The DST calls XITXL whenever data is to be sent to an external log using CNMSMSG with the EXTLOG operand. For example, the session monitor performs external logging of response time and configuration data.

Example of Use: You can use XITXL to write user-defined data to a user-defined log.

Coding Considerations: XITXL can use only the service facilities available to the DST.

You can use the following offsets (in byte values) to access the CMDBUF (Cmdbuf): Table 7. XITXL Buffer Parameters Offset Length Name Function 0 2 ELBLENG Unsigned length of header 2 2 ELBRLENG Unsigned length of record 4 1 ELBTYPE Log type 5 3 ELBLOG EBCDIC log type 8 4 Reserved by NetView 12 Start of record

26 Programming: PL/I and C Chapter 3. HLL Data Services command processors

HLL command processors that use the CNMCNMI and CNMKIO services must run under a DST. The DST provides the underlying interfaces required by both CNMCNMI and CNMKIO.

A DST is a set of NetView interfaces built on top of the NetView optional task base. The NetView optional task is described in IBM Tivoli NetView for z/OS Programming: Assembler. A DST provides a subtask processing module (DSIZDST) together with the following interfaces: v An initialization exit v A data services command processor (DSCP) that provides support for VSAM (through CNMKIO) and CNMI (through CNMCNMI) v Various installation exits. See Table 1 on page 13.

For more information about the TASK and DSTINIT statements referenced in this chapter, refer to IBM Tivoli NetView for z/OS Administration Reference.

Installing the Data Services task To install the data services task, code a TASK statement for the DST subtask in the CNMSTUSR or CxxSTGEN member. For information about adding CNMSTYLE statements, see IBM Tivoli NetView for z/OS Installation: Getting Started.

When the DST is started, the initialization data set specified by the MEM keyword on the TASK statement is read, and the DSTINIT statements are processed.

The following DSTINIT keywords are related to initialization: v FUNCT - Specifies which DST services are required. In all cases, the ability to call HLL DSCPs is provided. The function choices are: OTHER The DST does not require the CNMI or VSAM interfaces. BOTH Both the VSAM and CNMI interfaces are required. CNMI Only the CNMI interface is required. VSAM Only the VSAM interface is required. v XITDI - Specifies the name of the user-provided initialization exit. The exit is called with the standard NetView installation exit interface, as documented in Chapter 2, “HLL installation exit routines,” on page 11. This exit is called once for every statement in the specified initialization member (MEM keyword of TASK statement). When the end of file is reached, the length of CMDBUF (Cmdbuf) is 0. For each statement (except end-of-file condition), the standard installation exit return codes cause these actions: USERASIS (0) The statement is processed by the NetView DST module (DSIZDST). If it is not a valid DSTINIT statement, DSIZDST rejects it with an error message and continues processing.

USERDROP (4) The statement is not processed by DSIZDST. Use this return code if your installation exit is going to process the statement. (You can define your own initialization statements). USERSWAP (8) The swapped buffer is processed by DSIZDST. If the swapped buffer does not contain a valid DSTINIT statement, it is rejected by DSIZDST and processing continues. When returning from the last call (for end of file), any nonzero return code ends the DST. Termination occurs only if the initialization process fails.

Data Services command processors Command processors running under DSTs are called data services command processors (DSCP) and must be defined as TYPE=D (DST only) or TYPE=RD (regular or DST). The next sections describe services that are available to DSCPs. CNM Data Services You must define an APPL definition with AUTH=CNM to VTAM for the DST (use the TSKID name as the APPL name). The DST provides access to both solicited and unsolicited CNM data. You can use CNMCNMI to solicit CNM data from the network. You can define an HLL DSCP to receive unsolicited CNM data from VTAM. Unsolicited CNM data interface VTAM provides a default table (ISTMGC01) that controls the routing of unsolicited CNM RUs. You can write a supplemental table (ISTMGC00) to override the default routing information provided by VTAM. The routing information consists of a particular RU type and the name of an application that is to receive the particular type of data.

When a DST is defined with CNM services, an access method control block (ACB) is opened with an ACB name (the application name) equivalent to the task name as defined by the TSKID operand in the DST TASK definition statement. (The one exception is the hardware monitor, whose CNMI DST task name is BNJDSERV, but the application name is BNJHWMON.) If the DST task name is entered as the application name in the VTAM routing table, the unsolicited data RU is passed to the unsolicited data services command processor for that DST.

The following DSTINIT keywords are related to the unsolicited CNM data interface: v UNSOL - Specifies the command verb name of the module that is to serve as the unsolicited DSCP for this DST. The unsolicited DSCP must not issue the CNMCNMI macro, but can issue the CNMKIO macro. v DSRBU - Specifies the number of unsolicited data services request blocks (DSRBs) that are to be allocated to this DST. If unsolicited CNM data will not be processed by this DST, set this value to 0; otherwise set it to 1.

When the unsolicited HLL DSCP receives control, CNMDBUF (Cmdbuf) contains the unsolicited data RU. Solicited CNM data interface An HLL DSCP can use CNMCNMI to acquire communications network management data from the network.

28 Programming: PL/I and C HLL Data Services Command Processors

The DSTINIT keyword DSRBO specifies the number of solicited DSRBs that are required by this task and limits the number of concurrent CNMCNMI or CNMKIO requests, or both. This value must be at least 1 and no greater than 862. (A DSCP is not called until a solicited DSRB is available.) VSAM services A DSCP can call the CNMKIO service routine to perform input or output for a specified VSAM data set. The following DSTINIT keywords are related to CNMKIO service routine: v DSRBO - Specifies the number of solicited DSRBs that are required by this task, and limits the number of concurrent CNMCNMI or CNMKIO service routines, or both. This value must be at least 1 and no greater than 862. (A DSCP is not called until a solicited DSRB is available.) v PDDNM - Specifies the ddname of the primary data set to be used by VSAM services. v PPASS - Specifies the VSAM password to be used when the primary data set ACB is opened. v SDDNM - Specifies the ddname of the secondary data set to be used by VSAM services. Use the NetView SWITCH command to control which data set is the active data set. v SPASS - Specifies the VSAM password to be used when the secondary data set ACB is opened. v MACRF - Specifies local resource sharing. v XITVI - Specifies an installation exit to receive control upon input from the VSAM data set before the input record is passed to the requesting DSCP. v XITVN - Specifies an installation exit to receive control when an empty VSAM data set has been opened for processing. This exit enables you to put an initialization record into the data set. v XITVO - Specifies an installation exit to receive control before output of a record to the VSAM data set. User-defined services HLL command processors defined as TYPE=D or TYPE=RD can be called under the DST to perform user-defined functions in addition to CNMKIO or CNMCNMI functions.

Scheduling commands under the DST You use the CNMSMSG service routine to schedule a DSCP and, with the WAIT command, to wait for the DSCP to send back the results of the scheduled work. For samples of DSCPs and installation exit routines, see Appendix B, “PL/I samples,” on page 271 for PL/I, and Appendix D, “C samples,” on page 281 for C.

Chapter 3. HLL Data Services command processors 29 30 Programming: PL/I and C Part 2. Enabling a high-level language program

The NetView program supports preinitialized and non-preinitialized environments for PL/I and C programs.

If you use non-preinitialized environments, a unique environment is set up and freed each time a program is run.

Preinitialized environments significantly improve the performance of command processors and installation exits. Instead of repeatedly allocating and deallocating environments for each invocation of a command processor or installation exit, the NetView program manages a global pool of preinitialized environments. Command processors or installation exits are then able to enter and exit these environments more efficiently.

The NetView program supports regular and critical preinitialized environments. Critical preinitialized environments are reserved for programs that always run in a preinitialized environment. Regular preinitialized environments are available to all preinitialization-enabled programs.

Languages supported The following language environments are supported: v z/OS C and C++ v IBM PL/I for MVS and VM V1R1M1 and Enterprise PL/I for z/OS The minimum version of Enterprise PL/I for z/OS is V3R9M0.

Note: Programs compiled with Enterprise PL/I for z/OS cannot use NetView's preinitialized language environments.

Advantages and disadvantages of preinitialized environments The steps required to run your program in a non-preinitialized environment are fewer than those required to run with preinitialized environments. But, by running non-preinitialized you lose the performance enhancements available with preinitialized environments.

Preinitialized environments have a predefined set of options and are allocated a predefined initial amount of storage which is increased in fixed increments. If your program requires different runtime options, it cannot be run preinitialized. For information about runtime options, see Chapter 6, “Coding HLL command processors and installation exits,” on page 49 and Chapter 8, “Coding your C program interfaces and restrictions,” on page 103. For information about defining the size of your preinitialized environments, see “HLLENV command” on page 36

The following programs are good candidates for running in a preinitialized environment: v Installation exits v Frequently used command processors that run for a brief period such as those called from the NetView automation table

Run programs in a non-preinitialized environment if any of the following statements are true: v Initialization overhead is smaller than the overall runtime of the program. v The program is used infrequently. v The program must run with more STACK or HEAP storage than that defined for the preinitialized environment. When your program runs in a preinitialized environment, the HLLENV PSTACK and PHEAP values for the preinitialized environment are used instead of the values defined in your program. See “HLLENV command” on page 36 for more information. v It is a PL/I program that: – Uses language-specific file I/O, excluding stream-oriented output to SYSPRINT. – Uses CONTROLLED variables. – Uses FETCH and RELEASE statements. – Uses the STOP statement. – Starts an assembler routine containing SVC LINK. – Uses the EXIT statement. v It is a C program that: – Uses the exit() statement. – Starts an assembler routine containing SVC LINK.

Note: Language and storage restrictions are required so that different programs can reuse the same environment. For more information about restrictions resulting from shared use of preinitialized environments, refer to the IBM PL/I for MVS and VM V1R1M1 library, the Enterprise PL/I for z/OS library, or the z/OS Language Environment library.

Steps for implementing command processors and installation exits The following are high-level steps to help you understand the process for creating programs to run in non-preinitialized and preinitialized environments. Information about the individual facilities and commands can be found in “HLL definition facilities” on page 35. Non-preinitialized environments The following steps create and run a program in a non-preinitialized environment: 1. Write the command processor or installation exit code using PL/I or C. 2. Add the appropriate HLLOPTS that specifies whether your program: v Accepts queued input. v Ends on CANCEL/RESET 3. Compile your program. 4. Link edit your program with DSIHSTUB and the interface module appropriate to your language environment. See Table 8 on page 36. 5. Run your program. Preinitialized environments The following steps create and run a program in a preinitialized environment. 1. Use the following steps to design and implement the preinitialized environments for your system:

34 Programming: PL/I and C Preinitialized and Non-Preinitialized Environments

a. Define the size of each preinitialized environment using HLLENV PSTACK and PHEAP. b. Define the appropriate number of regular preinitialized environments for your system using HLLENV REGENVS. c. Define the maximum number of critical preinitialized environments required for your system using HLLENV CRITENVS. d. Specify whether preinitialization-enabled programs will default to run in a preinitialized environment (HLLENV DEFAULT=PREINIT) or in a non-preinitialized environment (HLLENV DEFAULT=NOTPREINIT) unless the default is overridden within individual programs using HLLOPTS.

Restriction: A NetView program compiled with IBM Enterprise PL/I for z/OS cannot use the preinitialized environment that the NetView program creates. 2. Code your command processor or installation exit using PL/I or C. 3. Add the appropriate HLLOPTS that specifies whether your program: v Accepts queued input v Ends on CANCEL/RESET v Overrides the HLLENV DEFAULT=PREINIT or HLLENV DEFAULT=NOTPREINIT setting for your system v Is critical to run in a preinitialized environment 4. Compile your program. For preinitialization-enabled PL/I programs, ensure that your program is compiled with the SYSTEM(MVS) compile option. You can do this in one of the following ways: v Compile on MVS and allow the compiler to default to SYSTEM(MVS). v Explicitly specify SYSTEM(MVS) with the PROCESS statement in your PL/I source. For example, include: *PROCESS SYSTEM(MVS); v Specify SYSTEM(MVS) in the EXEC statement of the compiler JCL. For preinitialization-enabled C programs, ensure that your program is compiled with the TARGET(MVS) compile option. You can do this in one of the following ways: v Compile on MVS and allow the compiler to default to TARGET(MVS). v Explicitly specify TARGET(MVS) with the #pragma options preprocessor directive in your C source. For example, include: #pragma options (TARGET(MVS)) v Specify TARGET(MVS) in the EXEC statement of the compiler JCL. 5. Link edit your program with the DSIHSTUB module and the interface module appropriate to your language environment. See Table 8 on page 36. Programs linked with the DSIHSTUB module and either the DSIEXAPP module or the DSIEXAPC module are considered preinitialization-enabled. 6. Run your program. Whether your program runs in a preinitialized mode depends on your system settings for HLLENV DEFAULT, the HLLOPTS defined in the program, and the available preinitialized environments.

HLL definition facilities The NetView program provides the facilities that allow you to define preinitialized environments. Combinations of the following facilities enable your programs to run as preinitialized command processors or installation exits. However, you can run the programs in either preinitialized or non-preinitialized environments:

Chapter 4. Preinitialized and non-preinitialized environments 35 Preinitialized and Non-Preinitialized Environments

v Interface Modules v HLLENV v HLLOPTS Interface modules To identify your program to the NetView program as a command processor or installation exit, link edit your program load-module with DSIHSTUB. DSIHSTUB must be the entry point.

Also, link edit your program with the interface module appropriate to your program type.

Note: 1. You can link your modules with preinitialization-enabled interface modules and then use HLLOPTS and HLLENV to control whether the modules run preinitialized or non-preinitialized. You can also explicitly link your modules with a non-preinitialized interface module if you want the module to always run non-preinitialized. 2. For non-preinitialized environments, to ensure that multiple environments under a single task are supported, include an ORDER statement for the interface module immediately after the DSIHSTUB module. Table 8 lists supported environments and their associated interface modules. Table 8. Language, interface modules, and HLLENV Type values cross-reference Compiler and Interface Program Type Library Module HLLENV TYPE PL/I z/OS Language DSIEXANP Non-preinitialized Environment PL/I z/OS Language DSIEXAPP IBMADPLI Preinitialization-enabled Environment Language Environment z/OS Language DSIEXANC Non-preinitialized Environment Language Environment z/OS Language DSIEXAPC IBMADC Preinitialization-enabled Environment Enterprise for z/OS Language DSIEXENP PL/I for z/OS Environment (Non-preinitialized)

For an example of link-edit JCL, see Chapter 5, “Compiling, link-editing, and running your HLL program,” on page 43. HLLENV command Preinitialized environments are defined and managed by the NetView HLLENV command. This command creates global pools of preinitialized environments that can be used and then returned when programs that use them end.

The HLLENV command defines and manages these types of preinitialized environments: v PL/I v C

36 Programming: PL/I and C Preinitialized and Non-Preinitialized Environments

For more information about the HLLENV command, refer to the NetView online help.

For each language, you can define preinitialized environments using the HLLENV command. The HLLENV TYPE keyword specifies definitions for the following languages: IBMADPLI HLLENV specifications are for PL/I programs. IBMADC HLLENV specifications are for C programs. Defining preinitialized environments When defining preinitialized environments, consider how many environments must be allocated, the STACK and HEAP storage required, and how preinitialization is specified in individual programs. Storage Keywords HLLENV keywords enable you to customize the amount of initial storage allocated for preinitialized environments.

For PL/I and C, the HLLENV PSTACK and PHEAP keywords are used to specify the STACK and HEAP storage to be allocated for preinitialized environments. The HLLENV PSTACK and PHEAP values override STACK or HEAP values declared in the program.

See Chapter 6, “Coding HLL command processors and installation exits,” on page 49 and Chapter 8, “Coding your C program interfaces and restrictions,” on page 103 for more information about STACK, PHEAP, and HEAP and how they apply to the PL/I and C environments. REGENVS and CRITENVS Keywords The REGENVS and CRITENVS keywords of the HLLENV command let you specify two pools of preinitialized environments for each language environment.

The REGENVS keyword specifies the number of preinitialized environments to be immediately allocated. Environments defined with REGENVS are retained by NetView and are available to all preinitialization-enabled programs of the applicable TYPE.

The CRITENVS keyword specifies the maximum number of preinitialized environments that can be allocated and made available to critical preinitialized programs. Critical preinitialized programs are defined using HLLOPTS. See “HLL runtime options” on page 38 for more information about HLLOPTS.

The following sections describe how preinitialized environments created with the REGENVS and CRITENVS keyword are distributed.

For programs that should run in a preinitialized environment: The program uses one of the preinitialized environments from the global pool set-up with the REGENVS keyword of the HLLENV command. If an environment is not available, the program runs non-preinitialized and initializes its own environment resulting in no performance benefit.

For critical preinitialized programs: The program first tries to use one of the preinitialized environments from the global pool allocated with the HLLENV

Chapter 4. Preinitialized and non-preinitialized environments 37 Preinitialized and Non-Preinitialized Environments

REGENVS command. If an environment is not available in the global pool, the program tries to use an environment allocated with the HLLENV CRITENVS command.

If an environment is still not available, the program runs non-preinitialized. However, if the number of environments allocated for critical preinitialized programs does not exceed the value specified with the CRITENVS keyword of the HLLENV command, a newly created preinitialized environment is allocated for other critical programs to use. This makes it more likely that a preinitialized environment will be available the next time that a critical program runs.

Note: Even when a program is defined as critical, there is no guarantee that it can run in a preinitialized environment. For example, if the number of preinitialized environments in use equals the total number of environments defined for both the REGENVS and CRITENVS keywords of HLLENV, your critical program will not run in a preinitialized environment. DEFAULT keyword of the HLLENV command The DEFAULT keyword specifies whether all programs link-edited with an interface module for a preinitialized environment (DSIEXAPP or DSIEXAPC) can run in a preinitialized environment.

Use the DEFAULT=PREINIT keyword on the HLLENV command to specify that all preinitialization-enabled programs run in a preinitialized environment. Use the DEFAULT=NOTPREINIT keyword on the HLLENV command to specify that none of your preinitialization-enabled programs run in a preinitialized environment. Whether an individual program runs in a preinitialized environment also depends on the HLLOPTS settings for bits 2, 3, and 4.

You can override DEFAULT=PREINIT for individual programs by setting bit 2 in the HLL runtime options (HLLOPTS) to 1. When this bit is set to 1, the program does not run preinitialized even though DEFAULT=PREINIT is specified.

You can override DEFAULT=NOTPREINIT for individual programs by setting bit 3 in HLLOPTS to 1. When this bit is set to 1, the program runs preinitialized even though DEFAULT=NOTPREINIT is specified. HLL runtime options You can specify HLL runtime options when coding your program by declaring and initializing the external variable named HLLOPTS. If you do not code HLL runtime options, the default of all bits being set to zero (0) is assumed. The bits defined in HLLOPTS are: Table 9. Bits Defined in HLLOPTS Bit Position Field Name Description 0 HLL_QUEUED_INPUT Determines whether an HLL program accepts queued input. Refer to the QUEUE command in the NetView online help for more information. 0 = HLL program does not accept queued input. 1 = HLL program accepts queued input.

38 Programming: PL/I and C Preinitialized and Non-Preinitialized Environments

Table 9. Bits Defined in HLLOPTS (continued) Bit Position Field Name Description 1 HLL_NO_CANCEL Determines whether an HLL program ends on CANCEL/RESET. Refer to the RESET command in the NetView online help for more information. 0 = Cancelable. 1 = Non-cancelable 2 OVER_DEFAULT_PREINIT Overrides the DEFAULT=PREINIT setting on the HLLENV command. When DEFAULT=PREINIT, bit 2 specifies: 0 = Programs run in a preinitialized environment. 1 = Programs run in a non-preinitialized environment. Note: This bit is only checked when DEFAULT=PREINIT is specified on the HLLENV command. 3 OVER_DEFAULT_NOTPREINIT Overrides the DEFAULT=NOTPREINIT setting on the HLLENV command. When DEFAULT=NOTPREINIT, bit 3 specifies: 0 = Programs run in a non-preinitialized environment. 1 = Programs run in a preinitialized environment Note: This bit is only checked when DEFAULT=NOTPREINIT is specified on the HLLENV command. 4 HLL_CRIT_PREINIT Specifies that a critical program be run in a preinitialized environment. 0 = It is not critical for the program to run in a preinitialized environment. 1 = It is critical for the program to run in a preinitialized environment. Note: This bit is only checked if the program is to run preinitialized. That is, if: v DEFAULT=PREINIT is specified on the HLLENV command and the HLLOPTS bit 2 is set to zero (0). v DEFAULT=NOTPREINIT is specified on the HLLENV command and the HLLOPTS bit 3 is set to 1. 5-31 Reserved for internal use. Do not assign any values to these fields.

For example, to override the default HLL runtime options in an HLL program and make the program non-cancelable, include: PL/I Program

DCL HLLOPTS BIT(32) STATIC EXTERNAL INIT(’01000000000000000000000000000000’B);

C Program

#pragma variable(HLLOPTS,NORENT) extern unsigned int HLLOPTS = 0X40000000;

For C, the #pragma variable preprocessor directive indicates that the variable named HLLOPTS is to be used in a non-reentrant fashion. This directive does not affect the reentrance of the HLL program.

Chapter 4. Preinitialized and non-preinitialized environments 39 Preinitialized and Non-Preinitialized Environments

Using the HLL runtime options for preinitialized environments The HLL runtime options for preinitialized environments (bits 2, 3, and 4) are used with the DEFAULT keyword of the HLLENV command. The DEFAULT keyword specifies that either all or none of the preinitialization-enabled programs run in a preinitialized environment. When you have chosen a DEFAULT value, individual programs can set bit 2 or 3 to override the DEFAULT value.

Set bit 4 in HLLOPTS for preinitialization-enabled programs where it is critical that the programs run in a preinitialized environment. Programs defined this way are termed critical preinitialized programs.

Table 10 summarizes the interaction of bits 2, 3, and 4 in HLLOPTS and the DEFAULT values on the HLLENV command. Table 10. DEFAULT Keyword Setting and HLLOPTS Bit Interaction HLLENV HLLENV Bit 2 Bit 3 Bit 4 DEFAULT=PREINIT DEFAULT=NOTPREINIT 0 0 0 Preinitialized Non-preinitialized 0 0 1 Critical preinitialized Non-preinitialized 0 1 0 Preinitialized Preinitialized 0 1 1 Critical preinitialized Critical preinitialized 1 0 0 Non-preinitialized Non-preinitialized 1 0 1 Non-preinitialized Non-preinitialized 1 1 0 Non-preinitialized Preinitialized 1 1 1 Non-preinitialized Critical preinitialized

The following combinations of settings for HLLOPTS bits 2, 3, and 4, are important to highlight: v If you want a preinitialization-enabled program to run in a preinitialized environment, regardless of the DEFAULT value on the HLLENV command, set bits 2, 3, and 4 - 010. For example, include: PL/I Program

DCL HLLOPTS BIT(32) STATIC EXTERNAL INIT(’00010000000000000000000000000000’B);

C Program

#pragma variable(HLLOPTS,NORENT) extern unsigned int HLLOPTS = 0X10000000; v If you want a preinitialization-enabled program to run as a critical preinitialized program regardless of the DEFAULT value on the HLLENV command, set bits 2, 3, and 4 - 011. For example, include: PL/I Program

DCL HLLOPTS BIT(32) STATIC EXTERNAL INIT(’00011000000000000000000000000000’B);

C Program

#pragma variable(HLLOPTS,NORENT) extern unsigned int HLLOPTS = 0X18000000;

40 Programming: PL/I and C Preinitialized and Non-Preinitialized Environments

v If you want a preinitialization-enabled program to run in a non-preinitialized environment regardless of the DEFAULT value on the HLLENV command, set bits 2, 3, and 4 - 100. For example, include: PL/I Program

DCL HLLOPTS BIT(32) STATIC EXTERNAL INIT(’00100000000000000000000000000000’B);

C Program

#pragma variable(HLLOPTS,NORENT) extern unsigned int HLLOPTS = 0X20000000;

Examples The following sections include various examples of setting up programs to run in non-preinitialized and preinitialized environments. Non-preinitialized example In this example, you have a command processor written in PL/I language. Because no other programs in your environment require a preinitialized environment, do not set up one for this program. The following steps complete the example: 1. Write the command processor or installation exit code. Include in your PL/I code the following HLLOPTS external declaration, specifying that your command processor accepts queued input: DCL HLLOPTS BIT(32) STATIC EXTERNAL INIT(’10000000000000000000000000000000’B); 2. Compile the program. 3. Link edit the program with DSIHSTUB and choose between the following items: v If you are using PL/I for MVS and VM, link edit the program with DSIEXANP. v If you are using Enterprise PL/I for z/OS, link edit the program with DSIEXENP. See Table 8 on page 36 for additional detail on the interface modules. 4. Run your program. Preinitialized example In the next example, all command processors run in preinitialized environments to improve performance. Most of your programs require 8192 bytes of STACK and HEAP storage. You estimate that 5 preinitialized environments and 3 additional environments for critical programs are required.

The first command processor you write is in PL/I. You want this command processor to accept all defaults for HLLOPTS. Although you prefer that the program run in a preinitialized environment, you do not consider it to be critical. The following steps complete this example: 1. Define the preinitialized environments for PL/I using the HLLENV command: HLLENV CHANGE,REGENVS=5,CRITENVS=3,PSTACK=131072,PHEAP=131072, DEFAULT=PREINIT,TYPE=IBMADPLI 2. Code the command processor or installation exit. 3. Compile the program with the SYSTEM(MVS) compile option.

Chapter 4. Preinitialized and non-preinitialized environments 41 Preinitialized and Non-Preinitialized Environments

4. Link edit the program with DSIHSTUB and DSIEXAPP. The program cannot be compiled with Enterprise PL/I for z/OS. 5. Run the program.

In the next example, the PL/I command processor requires different STACK and HEAP storage from that defined using the PSTACK and PHEAP keywords on the HLLENV command. The new command processor cannot run in a preinitialized environment because it requires more initial storage than is defined for preinitialized programs. The following steps complete the example: 1. Compile the program with the SYSTEM(MVS) compile option. 2. Link edit the program with DSIHSTUB and DSIEXAPP. 3. Run the program.

In another example, you decide to start writing command processors using the Language Environment. For the Language Environment-based C preinitialized environment, you estimate 3 preinitialized environments and 2 additional preinitialized environments for critical programs are required. For Language Environment programs, you decide to set the default to run all programs in a non-preinitialized environment. However, your first command processor written in the Language Environment is performance-sensitive and you feel that it is critical that it runs in a preinitialized environment. Take the following steps: 1. Define the preinitialized environments for the Language Environment using the HLLENV command: HLLENV CHANGE,REGENVS=3,CRITENVS=2,DEFAULT=NOTPREINIT,TYPE=IBMADC 2. Write the command processor or installation exit code. a. Include in your C code the following HLLOPTS external declaration specifying that it is critical that your command processor run preinitialized. The following HLLOPTS specification overrides your HLLENV DEFAULT=NOTPREINIT command and specifies that your program is critical. #pragma variable(HLLOPTS,NORENT) extern unsigned int HLLOPTS = 0X18000000; b. Define the runtime options required for your program. 3. Compile the program with the TARGET(MVS) compile option. 4. Link edit the program with DSIHSTUB and DSIEXAPC. 5. Run the program.

42 Programming: PL/I and C Chapter 5. Compiling, link-editing, and running your HLL program

If you have a PL/I or C compiler installed, you can modify the compile and link-edit JCL for use with the NetView program. This chapter describes how to make these modifications.

Use the examples provided in this chapter to modify the compile and link-edit JCL samples that you received with your compiler.

Note: You must have completed the installation steps for HLL before attempting to start programs in the NetView environment.

Compiling To compile programs using NetView services, modify the compile step in the JCL to reference the NetView macro libraries and include a SYSLIB statement for SYS1.MACLIB. An example of modifications to the compile step JCL for PL/I follows: //COMPILE EXEC PGM=IEL1AA,REGION=1000K, // PARM=’OBJECT,MACRO,LIST,RENT’ . . . //SYSLIB DD DSN=NETVIEW.V6R2M0.SCNMMAC1,DISP=SHR // DD DSN=SYS1.MACLIB,DISP=SHR . . .

The following example shows how to modify the compile step JCL for C: //COMPILE EXEC PGM=CCNDRVR,PARM=(’RENT’),REGION=&CREGSIZ . . . //SYSLIB DD DSN=NETVIEW.V6R2M0.SCNMMAC1,DISP=SHR // DD DSN=SYS1.MACLIB,DISP=SHR . . .

Note: 1. When you compile PL/I programs, you can ignore the IEL0548I message. 2. When you compile with Enterprise PL/I for z/OS, message IBM1195I can be ignored. Under some circumstances, message IBM2619I occurs; it can also be ignored.

Link-editing Consider the following when you link-edit modules: v All load modules must be reentrant. v Load modules can reside in 24- or 31-bit storage and can be entered in either addressing mode.

v You must link edit all load modules with DSIHSTUB and the appropriate interface module; DSIHSTUB must be the entry point.

To link edit a module to run with the NetView program, modify the link-edit step in the JCL to reference the appropriate NetView libraries. This enables you to include DSIHSTUB and the appropriate interface module when link-editing.

Add SYS1.CNMLINK to the list of automatic call libraries defined by SYSLIB in the link-edit step of the JCL. For C, add SYS1.CNMLINK and SYS1.NVULIB.

Figure 1 shows a sample JCL stream for link-editing a PL/I program:

//LKED EXEC PGM=IEWL, // PARM=’XREF,RENT,LET,LIST,AMODE=&AMODE,RMODE=&RMODE’, // REGION=4096K,COND=(8,LE,COMPILE) . . . //SYSLIB DD DSN=SYS1.CNMLINK,DISP=SHR // DD DSN=Link-Edit Library Data Set,DISP=SHR . . . INCLUDE SYSLIB(DSIHSTUB) INCLUDE SYSLIB(Interface Module) ORDER DSIHSTUB ORDER Interface Module ENTRY DSIHSTUB MODE AMODE(31),RMODE(ANY) NAME LMODNAME(R)

Figure 1. Example of Link-Editing a PL/I Program

“Example of Link-Editing a C Program” shows a sample JCL stream for link-editing a C program. Example of Link-Editing a C Program //LKED EXEC PGM IEWL, // PARM=’XREF,RENT,LET,LIST,AMODE=&AMODE,RMODE=&RMODE’, // REGION=4096K,COND=(8,LE,COMPILE) . . //SYSLIB DD DSN=SYS1.CNMLINK,DISP=SHR // DD DSN=SYS1.NVULIB,DISP=SHR // DD DSN=Link-Edit Library Data Set,DISP=SHR . . . INCLUDE SYSLIB(DSIHSTUB) INCLUDE SYSLIB(Interface Module) ORDER DSIHSTUB ORDER Interface Module ENTRY DSIHSTUB MODE AMODE(31),RMODE(ANY) NAME LMODNAME(R)

Link-edit library data sets and interface modules are listed in Table 11 on page 45.

44 Programming: PL/I and C Compiling, Link-Editing, and Running Your HLL Program

Table 11. Link-Edit Libraries and Interface Modules Link-Edit Library Data Interface HLLENV Compiler and Program Type Library set Module TYPE z/OS Language SYS1.SCEELKED DSIEXANP PL/I Environment Non-preinitialized z/OS Language SYS1.SCEELKED DSIEXAPP IBMADPLI PL/I Environment Preinitialization-enabled z/OS Language SYS1.SCEELKED DSIEXANC z/OS XL C/C++ Environment Non-preinitialized z/OS Language SYS1.SCEELKED DSIEXAPC IBMADC z/OS XL C/C++ Environment Preinitialization-enabled z/OS Language See the Usage Notes DSIEXENP Enterprise for PL/I for z/OS Environment following this table for Non-preinitialized several items related to compiling a program with Enterprise for PL/I for z/OS.

Usage for a program compiled with Enterprise PL/I for z/OS: 1. Add a link-edit control statement after the INCLUDE statements in Figure 1 on page 44: INCLUDE SYSLIB(PLICALLB) 2. Add the following link-edit library data sets in the specified order: a. SIBMCAL2 b. SCEELKED 3. Programs compiled with Enterprise PL/I for z/OS cannot use preinitialized environments.

All HLL modules must be reentrant. v For PL/I, include the REENTRANT option on the PL/I procedure statement, then link edit the resulting object decks with the RENT option. v For C, start the PRE-LINKEDIT step, then link edit the resulting object decks with the RENT option.

If you want to run your existing non-preinitialized load modules with z/OS Language Environment, first relink them with the z/OS Language Environment runtime libraries.

Running To start a command processor or installation exit in the NetView environment, you must modify your NetView startup procedure to reference the appropriate runtime libraries.

The runtime libraries appropriate for your command processor type are shown in Table 12 on page 46. You must ensure that the required library is available at runtime. One way to do so is to specify the required runtime library in the STEPLIB of your NetView startup procedure.

Chapter 5. Compiling, link-editing, and running your HLL program 45 Compiling, Link-Editing, and Running Your HLL Program

Table 12. Runtime Libraries Compiler and Program Type Library Runtime Library Data Set PL/I z/OS Language Environment SYS1.SCEERUN Non-preinitialized PL/I z/OS Language Environment SYS1.SCEERUN Preinitialization-enabled z/OS XL C/C++ z/OS Language Environment SYS1.SCEERUN Non-preinitialized z/OS XL C/C++ z/OS Language Environment SYS1.SCEERUN Preinitialization-enabled

HLL command processors require a CMDDEF statement in member CNMCMD of the DSIPARM data set. Installation exits are loaded at initialization and should conform to installation exit naming conventions. For more information see Chapter 2, “HLL installation exit routines,” on page 11.

46 Programming: PL/I and C Part 3. Writing a PL/I program

This chapter contains the following information for coding HLL command processors and installation exits in PL/I: v Initial parameters v HLL runtime options v PL/I runtime options v Parameters passed to HLL service routines v Control blocks and include files v Input and output considerations v Restrictions

PL/I command processors and installation exits are supported for IBM PL/I for MVS and VM V1.1.1 and Enterprise PL/I for z/OS.

Initial parameters The following initial parameters are passed to an HLL program upon invocation: v CMDBUF v HLBPTR v ORIGBLCK Chapter 7, “PL/I high-level language services,” on page 59 contains a sample template for coding the main procedure statement and the initial parameter declarations in PL/I. CMDBUF A varying length character field that contains the command or message that drives this program. If this program is driven as an installation exit (other than DSIEX02A), this field contains the message that drives this exit. If driven as DSIEX02A, CMDBUF does not contain any useful information, and you must retrieve the message from the initial data queue (IDATAQ). HLBPTR A 4-byte pointer field containing the address of the HLB control block (DSIPHLB). The HLB control block is the HLL API interface control block used to communicate between the HLL service routines and HLL programs in the NetView environment. This pointer is required on all HLL service routine invocations. The HLB control block is unique for each invocation of an HLL program. NetView automatically inserts HLBPTR for the PL/I macro format. See Appendix A, “PL/I Control Blocks and Include Files,” on page 269 for more information. ORIGBLCK A 40-byte structure that describes the origin of the request that called this program. ORIGBLCK is mapped by DSIPORIG. See Appendix A, “PL/I Control Blocks and Include Files,” on page 269 for more information.

Runtime options The method you use to specify PL/I runtime options depends on the type of PL/I support you use for your programs. The way you specify PL/I runtime options, therefore, depends on the following: v Compiler v Library (z/OS Language Environment) v Preinitialization Support (Enabled or Disabled)

In addition, you must consider information about: v Running non-preinitialized, either intentionally or because of availability v Type of runtime option, whether the option is a general option or a storage option.

Use Table 13 as a starting point to familiarize yourself with the specific methods of specifying the runtime options for your program. The table indicates the methods to use based on the interface module that is being link-edited with a program. Following the table, each method for specifying runtime options is described in more detail.

Tip: Runtime options can also be specified by the CEEPRMxx member of PARMLIB. Table 13. Interface Modules and How to Specify PL/I General Runtime Options Interface Library and Program Module Type General Runtime Options Storage Options DSIEXANP z/OS Language CEEUOPT v CEEUOPT Environment non-preinitialized DSIEXAPP z/OS Language z/OS Language v PSTACK Environment Environment preinitialized v PHEAP non-preinitialized defaults or LEOPTS static v LEOPTS static external variable external variable DSIEXAPP z/OS Language z/OS Language v PSTACK Environment Environment preinitialized v PHEAP preinitialization-enabled defaults DSIEXENP Enterprise PL/I for z/OS z/OS Language (non-Preinitialized) Environment

CEEUOPT runtime option CSECT For PL/I programs, you can specify the runtime options using the CEEUOPT CSECT. For more information about the CEEUOPT CSECT, refer to the z/OS library. z/OS Language Environment preinitialization defaults The following PL/I runtime options are automatically set for PL/I programs that request to run in a preinitialized environment. Except for the STACK and HEAP values, you cannot change the values. Values for pstack and pheap are taken from the values specified for PSTACK and PHEAP on the HLLENV command. v STACK(pstack,128K,ANY,FREE) v BELOWHEAP(8,0,FREE)

50 Programming: PL/I and C Coding PL/I Programs

v HEAP(pheap,128K,ANY,FREE,8,0) v LIBSTACK(8,0,FREE) v THREADHEAP(8,0,ANY,FREE) v STORAGE(,,,0) v ALL31(ON) v TRAP(OFF) v INTERRUPT(OFF) v NOTEST(ALL,*,*) v MSGQ(1) v PLITASKCOUNT(1)

Refer to the z/OS Language Environment library for more information about these options. PSTACK and PHEAP The STACK and HEAP storage values are set using the PSTACK and PHEAP keywords of the HLLENV command. The initial values for PSTACK and PHEAP are 131072 bytes each. These values can be changed dynamically with the HLLENV command.

The following example shows how to override the initial values for PSTACK and PHEAP for a PL/I program that requests to run in a preinitialized environment: HLLENV CHANGE,PSTACK=262144,PHEAP=524288,TYPE=IBMADPLI LEOPTS static external variable When your program uses the DSIEXAPP interface module and explicitly forces non-preinitialization through the combination of the HLLENV DEFAULT value and the HLLOPTS bits, you can specify the runtime options using the LEOPTS static external variable.

When you define LEOPTS in your program, the runtime options specified are used instead of those described in “z/OS Language Environment preinitialization defaults” on page 50 and “PSTACK and PHEAP.”

For example, you can override the default z/OS Language Environment preinitialization, PSTACK, and PHEAP runtime options in a PL/I program as shown in the following LEOPTS declaration. DCL LEOPTS CHAR(255) STATIC EXTERNAL INIT(( ’STACK(256K,256K,ANY,FREE) HEAP(256K,512K,ANY,FREE,8,0) TRAP(OFF) MSGQ(1)’ || ’ BELOWHEAP(8,0,FREE) LIBSTACK(8,0,FREE) THREADHEAP(8,0,ANY,FREE)’ || ’ INTERRUPT(OFF) NOTEST(ALL,*,* ) STORAGE(,,,0) ALL31(ON)’ || ’ PLITASKCOUNT(1)’));

Parameters passed to HLL Service routines Four types of parameters can be passed to HLL service routines. Each parameter, as described in Chapter 11, “Service reference,” on page 173, falls into one of four categories: v Pointer variables v Integer variables v Fixed-length character strings v Varying length character strings

Chapter 6. Coding HLL command processors and installation exits 51 Coding PL/I Programs

A discussion of each parameter type follows. The sections describe how you can declare, initialize, and pass each parameter type to the HLL service routines. This chapter provides examples for writing HLL programs in PL/I.

Note: These examples are not complete. They are included to emphasize how you might declare, initialize, and pass the HLL service routine parameters. For complete examples of user-written HLL programs, refer to the HLL samples shipped with the NetView program, or see Appendix B, “PL/I samples,” on page 271. Pointer variables A pointer variable is a 4-byte pointer field containing an address. All HLL service routines require at least one argument called HLBPTR. The NetView program calculates the value of HLBPTR and passes it to a PL/I HLL command processor or installation exit. Therefore, HLBPTR must be declared only in PL/I. Do not assign a value to the HLBPTR variable. This is the only parameter of this type that you do not have to assign.

Note: You do not need to specify the HLBPTR parameter when coding the HLL service routine invocation in the PL/I macro format. HLBPTR is inserted for you before the HLL service routine is started.

If an HLL service routine expects an address in a pointer field, you are responsible for assigning a value to that pointer field before starting the HLL service routine. In PL/I, you can use the ADDR function when passing pointer variables to HLL service routines rather than creating a separate pointer variable for this purpose. This ensures that the pointer variable has been assigned a value before starting the HLL service routine.

“Using Pointer Variables in PL/I” shows how to use pointer variables in PL/I. More information for the numbered steps follows the figure. Using Pointer Variables in PL/I DCL VARTOVAR CHAR(8) INIT(’VARTOVAR’); /* VARTOVAR constant */

▌1▐ DCL HLBPTR PTR; /* HLB pointer MUST BE DECLARED! */ ▌2▐ DCL SRCPTR PTR; /* Source pointer */ DCL DSTPTR PTR; /* Destination pointer */

DCL DSTLEN FIXED BINARY(31,0); /* Length of Destination */

DCL SRCBUF CHAR(255) VARYING; /* Source buffer */ DCL DSTBUF CHAR(255) VARYING; /* Destination buffer */

▌3▐ SRCPTR = ADDR(SRCBUF); /* Address of source buffer */ DSTPTR = ADDR(DSTBUF); /* Address of destination buffer */

DSTLEN = LENGTH(DSTBUF); /* Length of destination buffer */ SRCBUF = (255)’A’; /* Initialize source buffer */ DSTBUF = (255)’ ’; /* Initialize destination buffer */

▌4▐ CALL CNMCPYS(HLBPTR,SRCPTR,DSTPTR,DSTLEN,VARTOVAR); /* Copy buffer*/

The descriptions for the steps shown in “Using Pointer Variables in PL/I” are: ▌1▐ HLBPTR is declared as a pointer (PTR) variable to be used in the CNMCPYS invocation. You must not assign a value to HLBPTR. HLBPTR is specified for this invocation because you started CNMCPYS using the PL/I call format, rather than the PL/I macro format. Chapter 11, “Service

52 Programming: PL/I and C Coding PL/I Programs

reference,” on page 173 contains examples of how to start HLL service routines using the PL/I macro format. ▌2▐ SRCPTR is declared as a pointer (PTR) variable. ▌3▐ SRCPTR is assigned the address of the source buffer (SRCBUF) to be used in the CNMCPYS invocation. ▌4▐ Both HLBPTR and SRCPTR have been passed as parameters to CNMCPYS. Using the ADDR function eliminates the need to declare pointer (PTR) variables. Note here the use of a character constant instead of the VARTOVAR variable: CALL CNMCPYS(HLBPTR,ADDR(SRCBUF),ADDR(DSTBUF),DSTLEN,’VARTOVAR’);

Note: If you use the ADDR built-in function to represent a pointer to a varying length character string and the program is compiled with IBM PL/I for MVS and VM V1R1M1, then the IEL0872I message might be generated by the compiler. Integer variables Several of the HLL service routines require you to pass a 4-byte integer value to be used as a length, count, queue number, and so on. “Using Integer Variables in PL/I” illustrates the use of integer variables in the PL/I environment. (Descriptions for other statements in this figure are described in “Fixed-length character strings” on page 54 and “Varying length character strings” on page 54.) Using Integer Variables in PL/I %INCLUDE DSIPLI; /* Include the HLL macros */ DCL HLBPTR PTR; /* HLB pointer MUST BE DECLARED! */ DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ DCL ORIGBLCK CHAR(40); DCL SPNAME CHAR(8) VARYING INIT(’POOLNAME’); /* Subpool name */ DCL SPFUNC CHAR(8); /* Subpool function */ ▌1▐ DCL SPTOKEN FIXED BIN(31,0); /* Subpool token (returned) */ ▌2▐ DCL SPLENG FIXED BIN(31,0); /* Cell size */ DCL SPPRICNT FIXED BIN(31,0); /* Number of cells in primary */ DCL SPSECCNT FIXED BIN(31,0); /* Number of cells in secondary */ DCL SPCLASS FIXED BIN(31,0); /* Class of storage */

SPFUNC = ’ALLOC’; /* Function is ALLOCATE */

▌3▐ SPTOKEN = 0; /* Initialize subpool token */ ▌4▐ SPLENG = 256; /* Cell size = 256 bytes */ SPPRICNT = 3; /* Primary count = 3 */ SPSECCNT = 2; /* Secondary count = 2 */ SPCLASS = 1; /* Class = 31 bit addressable */

▌5▐ CALL CNMPOOL(HLBPTR,SPFUNC,SPTOKEN,SPNAME,SPLENG,SPPRICNT,SPSECCNT, SPCLASS); /* Allocate subpool */

The descriptions for the steps shown in “Using Integer Variables in PL/I” are: ▌1▐ SPTOKEN is declared as a 4-byte integer (FIXED BIN(31,0)). ▌2▐ SPLENG is declared as a 4-byte integer (FIXED BIN(31,0)) ▌3▐ SPTOKEN is initialized to zero (0). A value is returned in SPTOKEN upon successful completion of the CNMPOOL invocation. ▌4▐ SPLENG is assigned a value of 256 to be used in the call to CNMPOOL. ▌5▐ SPTOKEN and SPLENG are passed to CNMPOOL. The value of SPTOKEN is returned to you upon successful completion of the call to CNMPOOL.

Chapter 6. Coding HLL command processors and installation exits 53 Coding PL/I Programs

Fixed-length character strings Most HLL service routines require you to pass one or more fixed-length character strings as arguments. “Using Fixed-Length Variables in PL/I” highlights fixed-length variables in the PL/I environment. Using Fixed-Length Variables in PL/I ▌1▐ %INCLUDE DSIPLI; /* Include the HLL macros */ DCL HLBPTR PTR; /* HLB pointer MUST BE DECLARED! */ DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ ▌2▐ DCL ORIGBLCK CHAR(40); DCL SPNAME CHAR(8) VARYING INIT(’POOLNAME’); /* Subpool name */ ▌3▐ DCL SPFUNC CHAR(8); /* Subpool function */ DCL SPTOKEN FIXED BIN(31,0); /* Subpool token (returned) */ DCL SPLENG FIXED BIN(31,0); /* Cell size */ DCL SPPRICNT FIXED BIN(31,0); /* Number of cells in primary */ DCL SPSECCNT FIXED BIN(31,0); /* Number of cells in secondary */ DCL SPCLASS FIXED BIN(31,0); /* Class of storage */

▌4▐ SPFUNC = ’ALLOC’; /* Function is ALLOCATE */

SPTOKEN = 0; /* Initialize subpool token */ SPLENG = 256; /* Cell size = 256 bytes */ SPPRICNT = 3; /* Primary count = 3 */ SPSECCNT = 2; /* Secondary count = 2 */ SPCLASS = 1; /* Class = 31 bit addressable */

▌5▐ CALL CNMPOOL(HLBPTR,SPFUNC,SPTOKEN,SPNAME,SPLENG,SPPRICNT,SPSECCNT, SPCLASS); /* Allocate subpool */ ▌1▐ PL/I constants for most fixed-length character strings are in the DSIPCONS include file. DSIPCONS is optional and can be tailored to your specific needs. See Appendix A, “PL/I Control Blocks and Include Files,” on page 269 for more information about DSIPCONS. ▌2▐ HLL service routines use two types of origin blocks: ORIGBLCK and an origin block defined by you. The first type of origin block, ORIGBLCK, is a 40-byte structure that you must declare. This is a required initial parameter described in “Initial parameters” on page 49. Do not alter this structure. You define the second type of origin block (adorigin, gdorigin). The adorigin and gdorigin must be at least 38 bytes long and must map to the first 38 bytes of the origin block structure (DSIPORIG). You must declare these origin blocks separately from ORIGBLCK. ▌3▐ SPFUNC is declared as an 8-byte character field (CHAR(8)). ▌4▐ Character string 'ALLOC' is assigned to SPFUNC to be used in the call to CNMPOOL. ▌5▐ SPFUNC is passed to CNMPOOL. SPFUNC might have been initialized or passed to CNMPOOL as a character constant as shown in the following example. In all cases, PL/I automatically pads fixed-length character fields with blanks. CALL CNMPOOL(HLBPTR,’ALLOC’,SPTOKEN,SPNAME,SPLENG,SPPRICNT,SPSECCNT, SPCLASS); /* Allocate subpool */ Varying length character strings Several HLL service routines require that you to pass a varying length character string as an argument. “Using Varying Length Character Strings in PL/I” on page 55 highlights the use of varying length character strings in the PL/I environment.

54 Programming: PL/I and C Coding PL/I Programs

Using Varying Length Character Strings in PL/I %INCLUDE DSIPLI; /* Include the HLL macros */ DCL HLBPTR PTR; /* HLB pointer MUST BE DECLARED! */ DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ DCL ORIGBLCK CHAR(40); ▌1▐ DCL SPNAME CHAR(8) VARYING INIT(’POOLNAME’);/* Subpool name */ DCL SPFUNC CHAR(8); /* Subpool function */ DCL SPTOKEN FIXED BIN(31,0); /* Subpool token (returned) */ DCL SPLENG FIXED BIN(31,0); /* Cell size */ DCL SPPRICNT FIXED BIN(31,0); /* Number of cells in primary */ DCL SPSECCNT FIXED BIN(31,0); /* Number of cells in secondary */ DCL SPCLASS FIXED BIN(31,0); /* Class of storage */

SPFUNC = ’ALLOC’; /* Function is ALLOCATE */

▌2▐ CALL CNMPOOL(HLBPTR,SPFUNC,SPTOKEN,SPNAME,SPLENG,SPPRICNT,SPSECCNT, SPCLASS); /* Allocate subpool */ ▌1▐ SPNAME is declared as a varying length character field with a maximum length of 8 bytes (CHAR(8) VARYING). SPNAME is initialized to POOLNAME in this step. ▌2▐ SPNAME is passed to CNMPOOL

Control blocks and Include files A number of control blocks and include files are required to run a PL/I program in the NetView environment. The DSIPLI include file, which contains INCLUDE statements for other PL/I control blocks, is the main file necessary to compile NetView programs written in PL/I. Optional include files are provided to assist you in coding and maintaining HLL programs. You can tailor DSIPLI, DSIPCNM, and DSIPCONS to fit your needs.

Note: Tailoring files can lead to better system performance in many cases. This is especially helpful in performance-sensitive environments such as installation exits.

Appendix A, “PL/I Control Blocks and Include Files,” on page 269 contains these include files: DSIPLI (Required) Must be included by all HLL programs written in PL/I. DSIPLI contains INCLUDE statements for all of the external HLL control blocks and include files needed to compile and run PL/I programs in the NetView environment. See the PL/I coding template in Chapter 7, “PL/I high-level language services,” on page 59 for usage. DSIPCONS (Optional) Declares constants that are helpful when coding HLL programs in PL/I. DSIPHLB (Required) Specifies PL/I mapping of the NetView HLB control block. DSIPORIG (Required) Specifies PL/I mapping of the origin block of the request that caused the execution of the program currently running.

Chapter 6. Coding HLL command processors and installation exits 55 Coding PL/I Programs

DSIPHLLS (Required) Specifies PL/I definitions for HLL service routines. DSIPCNM (Optional) Declares HLL return code constants for PL/I. DSIPPRM (Required) Specifies PL/I mapping of the NetView Bridge parameter control block.

PL/I Input and output considerations PL/I provides several input and output statements that allow you to transmit data between main storage and auxiliary storage of a computer. PL/I programs using such file I/O capabilities can run in the NetView environment. However, there are some important things to consider when doing file I/O in PL/I.

Note: See “PL/I Input and output considerations in a preinitialized environment” on page 57 for I/O considerations in a preinitialized environment.

Each file referenced from your PL/I program correlates to a physical data set in auxiliary storage. Before opening a file for I/O, you must ensure that the appropriate data set has been allocated. You can perform allocation under the time-sharing option (TSO) or by using the NetView ALLOCATE command described in the NetView online help. NetView also provides a FREE command to deallocate a data set.

If the data set is allocated from TSO, you must also add a corresponding data definition (DD) statement to the NetView startup procedure. The data definition name (ddname) must match the name of the PL/I file. The DD statement specifies a physical data set name (dsname) and gives its characteristics, as follows: //OUTFILE DD DSN=MYPROG.OUTFILE, ...

A DD statement is not necessary if the data set is allocated using the NetView ALLOCATE command.

The following example illustrates the use of file I/O in an HLL program written in PL/I. Note the use of the ON UNDEFINEDFILE statement to protect against an OPEN failure. Check for this condition before opening a file for I/O. DCL OUTFILE FILE STREAM; /* Declare output file */ . . . /********************************************************************/ /* Check for error before opening file for I/O. If UNDEFINEDFILE */ /* condition is raised, issue an error message and exit program. */ /********************************************************************/ ON UNDEFINEDFILE(OUTFILE) BEGIN; CALL CNMSMSG(HLBPTR,’OUTPUT FILE IS UNDEFINED’,’MSG’,’OPER’,’’); HLBRC = CNM_GOOD; STOP; END;

OPEN FILE(OUTFILE) OUTPUT; /* Open file for output */ . . . PUT SKIP FILE(OUTFILE) ... /* Write to output file */ CLOSE FILE(OUTFILE); /* Close output file */

56 Programming: PL/I and C Coding PL/I Programs

If you want to write to a common output file from two or more PL/I programs, the programs must coordinate access to the common file. You can accomplish this using the HLL CNMLK service routine. If access is not coordinated, you might experience a system ABEND 213.

Note: PL/I and C cannot share an open file. However, a C program can read a file created by PL/I.

If you choose to code a GET or PUT statement without the FILE option, the compiler inserts the file names SYSIN and SYSPRINT. By default, SYSIN and SYSPRINT are directed to the terminal. These defaults are not valid, and cause undetermined results if used in the NetView environment. Terminal I/O can be done using WAIT FOR OPINPUT and CNMSMSG as described in Chapter 11, “Service reference,” on page 173. For more information about files and PL/I I/O, refer to the PL/I library. PL/I Input and output considerations in a preinitialized environment Programs that you want to run in a preinitialized environment cannot perform file I/O with PL/I language-specific functions. These programs can perform stream-oriented output only to SYSPRINT, and SYSPRINT must be declared as an external file.

I/O services provided by the HLL service routines are not affected by preinitialized environments.

PL/I runtime considerations All errors detected at run time are associated with PL/I conditions that can be handled by ON-unit statements written by the programmer. An ON-unit is a user-written statement that establishes an action to be started when a particular PL/I error condition is raised. PL/I error conditions can be detected by the operating system or by PL/I.

Because PL/I programs running in a production NetView environment must run with the TRAP(OFF) option, do not code ON-unit statements for operating system detected conditions.

While debugging a PL/I program in a test NetView environment, use the TRAP(ON) option until runtime problems are resolved. If you plan to use programs in a preinitialized environment, you might want to run them non-preinitialized with TRAP(ON) until runtime problems have been resolved. Most runtime errors are represented by diagnostic messages written to the SYSPRINT file. For more information on the TRAP option, refer to the z/OS Language Environment library.

Considerations for HLL command processors Code a CMDDEF statement in CNMCMD for each HLL command processor that you write. The CMDDEF TYPE depends on the functions that your command processor performs. Keep in mind that some of the HLL services are useful only when they are run under a DST. The CMDDEF statement is described in the IBM Tivoli NetView for z/OS Administration Reference.

Chapter 6. Coding HLL command processors and installation exits 57 Coding PL/I Programs

There is no support for HLL command processors running as immediate commands (TYPE=I) or being pushed (with the macro DSIPUSH) as ABEND, LOGOFF, or RESUME routines.

Return codes When an HLL service routine is done, its completion code is stored in the return code field (HLBRC) of the HLB control block. Check this field after each HLL service routine invocation. Also, use this field when passing return codes between HLL programs.

For a complete list of HLL API return codes, see DSIPCNM in Appendix A, “PL/I Control Blocks and Include Files,” on page 269. Chapter 11, “Service reference,” on page 173 describes the return codes that apply to each HLL service routine.

Do not use PLIRETV and PLIRETC when passing return codes between HLL programs written in PL/I. Both of these routines can yield unpredictable results in the NetView environment. To end a PL/I program normally, assign a value to HLBRC and issue a RETURN statement as illustrated below: HLBRC = CNM_GOOD; /* Successful completion */ RETURN; /* Return to caller */

Restrictions for HLL programs written in PL/I Do not use these commands when coding PL/I programs to run in the NetView environment: Table 14. Restrictions for HLL Programs Written in PL/I Command Alternative DISPLAY Use the NetView CNMSMSG service routine. WAIT, DELAY Use the NetView WAIT command. ON FIXEDOVERFLOW These condition codes do not work in the NetView program ON OVERFLOW because they require SPIE and STAE. ON UNDERFLOW ON ZERODIVIDE PLIRETV PLIRETC Pass return codes through HLBRC.

Restrictions for PL/I programs running in a preinitialized environment The following restrictions apply to PL/I programs that run in a preinitialized environment: v PL/I language-specific file I/O is not valid. This excludes stream-oriented output to SYSPRINT. v CONTROLLED variables are not valid. v FETCH/RELEASE statements are not valid. v STOP statements are not valid. v Invocations of assembler routines that contain an SVC LINK are not valid. v EXIT statements must not be used.

The previous restrictions are needed so that different programs can reuse the same environment. For more information about restrictions resulting from shared use of preinitialized environments, refer to the z/OS Language Environment library.

58 Programming: PL/I and C Chapter 7. PL/I high-level language services

This chapter describes and provides examples of NetView commands and services that support PL/I. See Chapter 11, “Service reference,” on page 173 for more information.

Note: When you are compiling PL/I programs for the NetView program, you receive the IEL0548I message. When you are compiling programs for the Enterprise PL/I for z/OS program, you receive the IBM1195I message. You can ignore these messages.

PL/I sample template “PL/I sample template” is a coding template sample you can use when coding HLL programs in PL/I. Use this template, with your enhancements, to use NetView functions and commands. Use the examples in this chapter with this template. Fully functional samples of NetView command procedures written in PL/I are described in Appendix B, “PL/I samples,” on page 271. PL/I sample template *PROCESS SYSTEM(MVS); PTMPPLT: PROC(HLBPTR,CMDBUF,ORIGBLCK) OPTIONS(MAIN,REENTRANT); /********************************************************************/ /* */ /* 5697-B82 (C) COPYRIGHT IBM CORPORATION 1989, 1995 */ /* ALL RIGHTS RESERVED. */ /* */ /* IEBCOPY SELECT MEMBER=((CNMS4200,PTMPPLT,R)) */ /* */ /* (Explanations included in parentheses should be deleted) */ /* (after the pertinent information has been filled in. ) */ /* */ /* Descriptive Name: High-Level Language PL/I Template */ /* (This is the more descriptive name or title of the module.) */ /* */ /* Function: */ /* Template for writing HLL modules in PL/I. */ /* (This is the description of what the module does.) */ /* (It may be paragraph or pseudocode form. ) */ /* */ /* Dependencies: */ /* (List conditions that must be met in order for this) */ /* (module to perform. An example of this might be a ) */ /* (key data area that must already have been built. ) */ /* */ /* Restrictions: */ /* (List any limitations this module may have.) */ /* */ /* Language: PL/I */ /* */ /* Input: */ /* 1) A pointer to a 4-byte field containing the address of */ /* the HLB control block. */ /* 2) A varying length character string containing the */ /* command or message which invoked this program. */ /* If this program was invoked as a command processor, */ /* this will be a command string. */ /* If this program was invoked as an installation exit */ /* (other than DSIEX02A), this will be a message string. */

/* When driven as DSIEX02A- */ /* this string will be empty and the message must */ /* be retrieved from the Initial Data Queue (IDATAQ). */ /* 3) A 40-byte structure which describes the origin of the */ /* request that caused execution of this program. */ /* */ /* Output: */ /* (Describe any output from this module.) */ /* */ /* Return Codes: returned in Hlbrc */ /* For Command Processors: */ /* 0 = normal exit */ /* -5 = cancelled */ /* (List any other return codes meaningful to this module.) */ /* For Installation Exits: */ /* 0 = USERASIS (Leave the contents of the message buffer */ /* unchanged) */ /* 4 = USERDROP (Drop the message buffer) */ /* 8 = USERSWAP (Change the contents of the message buffer) */ /* */ /* External Module References: */ /* (List modules that are called by this module.) */ /* */ /* Change Activity: */ /* date,author: description of changes */ /* (Keep a log of the changes made to this module for) */ /* (future reference. ) */ /********************************************************************/ /********************************************************************/ /* NetView High-Level Language include files */ /********************************************************************/ %INCLUDE DSIPLI; /* Include the HLL macros */ /********************************************************************/ /* HLL Run-time options (Set to Non-Preinitialized regardless of */ /* the value specified for the DEFAULT keyword of the HLLENV */ /* command. */ /********************************************************************/ DCL HLLOPTS BIT(32) STATIC EXTERNAL INIT(’00100000000000000000000000000000’); /********************************************************************/ /* Parameter declarations */ /********************************************************************/ DCL HLBPTR PTR; /* Pointer to the HLB */ DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ DCL ORIGBLCK CHAR(40); /* Area for the Origin Block */ /********************************************************************/ /* Other declarations */ /********************************************************************/ DCL ORIGIN PTR; /* Pointer to the Origin Block */ DCL ADDR BUILTIN; /* Builtin function */ /********************************************************************/ /* Initialization */ /********************************************************************/ ORIGIN=ADDR(ORIGBLCK); /* Address of the Origin Block */ /********************************************************************/ /* Execution */ /********************************************************************/ HLBRC = CNM_GOOD; /* Successful completion */ END PTMPPLT;

60 Programming: PL/I and C PL/I High-Level Language Services

Data queue management The NetView program uses several data and message queues to work with HLL service routines. Use the CNMGETD function to manipulate information retrieved from these queues to enhance your network manageability. Table 15 describes how queues are defined for data and message management: Table 15. Data and Message Management Queues Queue Queue Name Number Function TRAPQ 1 Message queue. Contains trapped messages. See “TRAP command” on page 182. OPERQ 2 Operator input queue. See “GO command” on page 177 and “QUEUE command” on page 178. DATAQ 3 Data queue. Contains data sent from another HLL command processor or installation exit routine. See “CNMSMSG (CNMSENDMSG): Send Message or Command” on page 251. IDATAQ 4 Initial data queue. Contains the full message or MSU that starts the HLL command processor through NetView automation. It also contains messages that drive DSIEX02A and DSIEX17. This is also the queue where an application command processor receivesan MDS-MU from the NetView high-performance transport, the MS transport, or operations management for an unsolicited request or asynchronous reply. For invocations from pipes, the IDATAQ contains the data flowing into the HLL command processor. CNMIQ 5 CNMI solicited data queue. Contains RUs solicited through the CNMI service routine. Chained RUs are treated like multiline messages. See “CNMCNMI (CNMI): CNMI access under a DST” on page 189. MDSMUQ 6 MDS-MU data queue. Contains message units (MUs) received as synchronous replies. The MDS-MUs are received from operations management, the MS transport, and the high-performance transport. Refer to the IBM Tivoli NetView for z/OS Application Programmer's Guide for more information.

The examples in the following sections show how the preceding queues are used with HLL command procedures.

Sending messages “Sending messages (PL/I)” is an example of sending messages: Sending messages (PL/I) /********************************************************************/ /* SEND A MULTILINE MESSAGE TO USER */ /********************************************************************/ CALL CNMSMSG(HLBPTR,’Line 1 of 3 ’,’MSG_C’,’OPER’,’’); CALL CNMSMSG(HLBPTR,’Line 2 of 3 ’,’MSG_D’,’OPER’,’’); CALL CNMSMSG(HLBPTR,’Line 3 of 3 ’,’MSG_F’,’OPER’,’’); /********************************************************************/ /* SEND A MULTILINE MESSAGE TO A TASK */ /********************************************************************/ CALL CNMSMSG(HLBPTR,’Line 1 of 3 ’,’MSG_C’,’TASK’,’OPER2’); CALL CNMSMSG(HLBPTR,’Line 2 of 3 ’,’MSG_D’,’TASK’,’OPER2’); CALL CNMSMSG(HLBPTR,’Line 3 of 3 ’,’MSG_F’,’TASK’,’OPER2’); /********************************************************************/ /* SEND A MESSAGE TO THE CONSOLE (only 1-liners)*/

Chapter 7. PL/I high-level language services 61 PL/I High-Level Language Services

/********************************************************************/ CALL CNMSMSG(HLBPTR,’Hello Sysop ’,’MSG’,’SYSOP’,’’);

/********************************************************************/ /* SEND A MESSAGE TO THE AUTHORIZED RECEIVER */ /********************************************************************/ CALL CNMSMSG(HLBPTR,’Hello Authrcvr ’,’MSG’,’AUTHRCV’,’’); /********************************************************************/ /* SEND A MESSAGE TO THE NETWORK LOG */ /********************************************************************/ CALL CNMSMSG(HLBPTR,’This should only be in log’,’MSG’,’NETVLOG’,’’);

/********************************************************************/ /* SHOW THAT YOU CAN SEND TO SEQLOG */ /********************************************************************/ CALL CNMSMSG(HLBPTR,’test msg’,’MSG’,’SEQLOG’,’SQLOGTSK’); /********************************************************************/ /* SHOW THAT YOU CAN SEND TO A GROUP */ /********************************************************************/ CALL CNMSMSG(HLBPTR,’hello group’,’MSG’,’OPCLASS’,’+GROUP1’);

Parsing input strings similar to NetView Command List Language “Parsing an input string (PL/I)” is an example of parsing the input string that is similar to parsing with the NetView command list language. The example parses the first 10 tokens individually, just as the NetView command list language parses them into &1, &2, and so on. This example also sets an equivalent variable to &PARMSTR. Parsing an input string (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL (CLIST1,CLIST2,CLIST3, CLIST4,CLIST5,CLIST6, CLIST7,CLIST8,CLIST9, CLIST10,PARMSTR) CHAR(255) VARYING; DCL PARMCNT FIXED BIN(31,0); /* Number of tokens parsed */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ CNMSSCAN /* Parse like NetView Command ...List Language parses */ DATA(CMDBUF) /* ...input is in cmdbuf */ FORMAT(’%*S0S0S0S0S0S’)/* ...parse each token by blanks */ /* ...but skip the command */ COUNT(PARMCNT) /* ...number of tokens parsed */ P1(CLIST1) /* ...first token */ P2(CLIST2) /* ...next token */ P3(CLIST3) /* ...next token */ P4(CLIST4) /* ...next token */ P5(CLIST5) /* ...next token */ P6(CLIST6) /* ...next token */ P7(CLIST7) /* ...next token */ P8(CLIST8) /* ...next token */ P9(CLIST9) /* ...next token */ P10(CLIST10); /* ...last token */

CNMSSCAN /* Parse like NetView Command ...List Language parses */

62 Programming: PL/I and C PL/I High-Level Language Services

DATA(CMDBUF) /* ...input is in cmdbuf */ FORMAT(’%*S%{¬}’) /* ...skip over command, then */ /* ...put all parms in a target */ COUNT(PARMCNT) /* ...number of tokens parsed */ P1(PARMSTR); /* ...first token */

Parsing input string similar to REXX “Parsing an input string similar to REXX (PL/I)” parses an input string in a manner similar to that used in REXX. REXX parses the first four tokens individually and puts the rest of the input into the fifth token: arg token1 token2 token3 token4 token5

PL/I parsing is similar. Parsing an input string similar to REXX (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL (TOKEN1,TOKEN2,TOKEN3, TOKEN4,TOKEN5,MSGSTR) CHAR(255) VARYING; DCL PARMCNT FIXED BIN(31,0); /* Number of tokens parsed */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ CNMSSCAN /* Parse like TOKEN parses... */ DATA(CMDBUF) /* ...input is in cmdbuf */ FORMAT(’%*S0S0S%{¬}’) /* ...parse each token by blanks */ /* ...but skip the command and */ /* ...last token gets rest of */ /* ...the input. */ COUNT(PARMCNT) /* ...number of tokens parsed */ P1(TOKEN1) /* ...first token */ P2(TOKEN2) /* ...next token */ P3(TOKEN3) /* ...next token */ P4(TOKEN4) /* ...next token */ P5(TOKEN5); /* ...last token gets the rest ...of the input string */

CNMSSCAN /* Parse like ARG parses... */ DATA(CMDBUF) /* ...input is in cmdbuf */ FORMAT(’%*S%{¬}’) /* ...skip over command, then */ /* ...put all parms in a target */ COUNT(PARMCNT) /* ...number of tokens parsed */ P1(MSGSTR); /* ...first token */

Parsing input string in CNMSCAN “Parsing an input string in CNMSCAN (PL/I)” shows how the C SSCANF function, CNMSCAN, parses and converts in a single step and accepts any input character as a delimiter. Parsing an input string in CNMSCAN (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */

Chapter 7. PL/I high-level language services 63 PL/I High-Level Language Services

/********************************************************************/ DCL CNT FIXED BINARY(31,0); /* Number of strings parsed */ DCL INPUT_STR CHAR(256) VARYING; /* Sscan input string */ DCL FORMAT CHAR(256) VARYING; /* Sscan format string */ DCL MSGBUF CHAR(256) VARYING; /* Message buffer */ DCL (CH1,CH2,CH3,CH4,CH5,CH6) CHAR(8) VARYING; /* Char vars */ DCL (FX1,FX2,FX3) FIXED BINARY (31,0); /* Fixed vars */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ /********************************************************************/ /* Parse out a string */ /********************************************************************/ INPUT_STR=’parm1 ’|| /* Set input string up */ ’parm2 ’|| ’parm3 ’|| ’10000 ’|| ’200 ’|| ’FFFFF ’|| ’01XYZ2’|| ’ parm4’; FORMAT= /* The format string says to: ’%S’ || /* (1) Find a character string */ ’%4S’ || /* (2) Find a 4-byte character string */ ’%S’ || /* (3) Find a character string */ ’%*S’ || /* (4) Skip over a character string */ ’%D’ || /* (5) Find a decimal string */ ’%2D’ || /* (6) Find a 2-byte decimal string */ ’%*S’ || /* (7) Skip over a character string */ ’%X’ || /* (8) Find a hex string */ ’%{ Q10}’|| /* (9) Find a string that contains one of the bracketed characters, stop scanning when a non-bracketed character is found */ ’%{2ZYX}’|| /*(10) Find a string that contains one of the bracketed characters, stop scanning when a non-bracketed character is found */ ’%{¬4}’; /*(11) Find a string that does NOT contain a 4, stop scanning when a 4 is found */ CALL CNMSCAN(HLBPTR, /* Scan the input string... */ INPUT_STR, /* ...input is in here */ FORMAT, /* ...format string */ CNT, /* ...number of string parsed */ CH1, /* ...character string */ CH2, /* ...character string */ CH3, /* ...character string */ FX1, /* ...decimal string */ FX2, /* ...decimal string */ FX3, /* ...hex string */ CH4, /* ...character string */ CH5, /* ...character string */ CH6, /* ...character string */ ’’ ); /* ...not used */ /********************************************************************/

64 Programming: PL/I and C PL/I High-Level Language Services

/* After executing, the variables have these values: */ /* */ /* CH1 = "parm1" */ /* CH2 = "parm" */ /* CH3 = "2" */ /* FX1 = 10000 Decimal, 2710 Hex */ /* FX2 = 20 Decimal, 14 Hex */ /* FX3 = 1048575 Decimal, FFFFF Hex */ /* CH4 = " 01" */ /* CH5 = "XYZ2" */ /* CH6 = " parm" */ /* */ /* */ /********************************************************************/

Starting synchronous commands “Starting synchronous commands (PL/I)” is an example of an HLL command processor starting another command. The command can be another HLL command, a command list, a VTAM command, or a NetView command. Starting synchronous commands (PL/I) /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/

/* Issue the VTAM command D NET,APPLS */

CALL CNMCMD(HLBPTR, /* Invoke the command... */ ’D NET,APPLS’); /* ...text of the command to run */

Sending commands “Sending a command to run another task (PL/I)” is an example of sending a command to run under another task. The command to be run under the other task can be another HLL command, a command list, a VTAM command, or a NetView command.

Use this process to run commands under DSTs, other OSTs, or the PPT. Sending a command to run another task (PL/I) /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/

/* Issue the LOGOFF command on a task called OPER1 */

CALL CNMSMSG(HLBPTR, /* Send the command... */ ’LOGOFF’, /* ...text of the command to run */ ’COMMAND’, /* ...this is a command */ ’TASK’, /* ...run it on a task */ ’OPER1’); /* ...task name is OPER1 */ SELECT; WHEN(HLBRC=CNM_GOOD) CALL CNMSMSG(HLBPTR, /* Inform user of success... */ ’OPER1 logoff successfully scheduled’, /* ...text of msg*/ ’MSG’, /* ...this is a message */ ’OPER’, /* ...to the operator */

Chapter 7. PL/I high-level language services 65 PL/I High-Level Language Services

’’); /* ...not used */ WHEN(HLBRC=CNM_TASK_INACTIVE) CALL CNMSMSG(HLBPTR, /* Inform user task not active...*/ ’OPER1 not active’, /* ...text of message */ ’MSG’, /* ...this is a message */ ’OPER’, /* ...to the operator */ ’’); /* ...not used */ OTHERWISE CALL CNMSMSG(HLBPTR, /* Inform user bad rc... */ ’Unexpected RC from CNMSMSG’, /* ...text of message */ ’MSG’, /* ...this is a message */ ’OPER’, /* ...to the operator */ ’’); /* ...not used */ END; /* of select */

HLBRC=CNM_GOOD; /* Clear RC */

Waiting and trapping “Waiting and trapping using the TRAP and WAIT commands (PL/I)” uses the TRAP and WAIT commands to issue a command, trap the output, and respond depending on the output that is encountered. “Waiting and trapping using the PIPE command (PL/I)” on page 68 provides similar function using the PIPE command. Both examples activate the given logical unit (LU) and issue an appropriate message. Example of using the TRAP and WAIT commands (PL/I) The syntax for the command shown in “Waiting and trapping using the TRAP and WAIT commands (PL/I)” follows:

PACTLU

►► PACTLU luname ►◄

Where: luname Is the name of the LU to be activated. Waiting and trapping using the TRAP and WAIT commands (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL GETBLOCK CHAR(40); /* Area for the Orig Block */ DCL GETPTR PTR; /* Pointer to the Orig Block */ DCL INBUF CHAR(256) VAR; /* Buffer area for messages */ DCL NODENAME CHAR(8) VAR; /* Nodename to be activated */ DCL STATUS CHAR(8) VAR; /* Status of the resource */ DCL CNT FIXED BIN(31,0); /* Number of elements parsed */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ GETPTR=ADDR(GETBLOCK); /* Address the Orig Block */ /********************************************************************/ /* Scan the input for the lu name to activate */ /********************************************************************/ CALL CNMSCAN(HLBPTR, /* Parse the input ... */

66 Programming: PL/I and C PL/I High-Level Language Services

CMDBUF, /* ...command line is the input */ ’%*S%8S’, /* ...skip over command name */ CNT, /* ...returned */ NODENAME); /* ...nodename */ IF CNT=1 THEN /* Nodename specified? */ DO; /* Yes... */ CALL CNMCMD(HLBPTR, /* Trap the following VTAM msgs */ ’ TRAP AND SUPPRESS ONLY MESSAGES IST*’); CALL CNMCMD(HLBPTR,’ V NET,ACT,ID=’||NODENAME); /* Activate node*/ CALL CNMCMD(HLBPTR,’ WAIT 10 SECONDS FOR MESSAGES’); /* Wait... */ CALL CNMGETD(HLBPTR, /* Get the first trapped msg... */ ’GETMSG’, /* ...function is get a msg */ INBUF, /* ...result goes here */ 256, /* ...max input length */ GETBLOCK, /* ...must provide a work area */ TRAPQ, /* ...message is trapped */ 1); /* ...get the first one */ /****************************************************************/ /* Loop through messages until IST093I is found or no more */ /* ...messages are left */ /****************************************************************/ DO WHILE(GETPTR->ORIG_BLOCK.ORIG_PROCESS¬=’IST093I’ & HLBRC=CNM_GOOD); CALL CNMCMD(HLBPTR,’ WAIT CONTINUE’); /* Wait for next msg... */ CALL CNMGETD(HLBPTR, /* Get the next trapped msg... */ ’GETMSG’, /* ...function is get a msg */ INBUF, /* ...result goes here */ 255, /* ...max input length */ GETBLOCK, /* ...must provide a work area */ TRAPQ, /* ...message is trapped */ 1); /* ...get the top one on queue */ END; IF (HLBRC=CNM_GOOD /* Did we find IST093I? */ GETPTR->ORIG_BLOCK.ORIG_PROCESS=’IST093I’) THEN CALL CNMSMSG(HLBPTR, /* Inform user activation worked */ ’RESOURCE ’||NODENAME||’ NOW ACTIVE’, /* ...text of message */ ’MSG’, /* ...single line message */ ’OPER’, /* ...to the operator */ ’’); /* ...not needed */ ELSE /* IST093I not found, must be ...an error */ CALL CNMSMSG(HLBPTR, /* Inform user activation failed */ ’ERROR - ACTIVATION UNSUCCESSFUL’, ’’); /* ...not needed */ END; ELSE /* Nodename not specified */ CALL CNMSMSG(HLBPTR, /* Inform user need more args */ ’ERROR - NODENAME NOT SPECIFIED’, /* ...text of message */ ’MSG’, /* ...single line message */ ’OPER’, /* ...to the operator */ ’’); /* ...not needed */ Example of using the PIPE command (PL/I) The syntax for the command shown in “Waiting and trapping using the PIPE command (PL/I)” on page 68 is as follows:

PACTPIP

►► PACTPIP luname ►◄

Where:

Chapter 7. PL/I high-level language services 67 PL/I High-Level Language Services

luname Is the name of the LU to be activated. Waiting and trapping using the PIPE command (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL GETBLOCK CHAR(40); /* Area for the Orig Block */ DCL GETPTR PTR; /* Pointer to the Orig Block */ DCL INBUF CHAR(256) VAR; /* Buffer area for messages */ DCL NODENAME CHAR(8) VAR; /* Nodename to be activated */ DCL STATUS CHAR(8) VAR; /* Status of the resource */ DCL CNT FIXED BIN(31,0); /* Number of elements parsed */ DCL VARNM CHAR(16) VAR /* Var name for PIPE result */ INIT(’VNETRESULT’); /* should be VNETRESULT */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ GETPTR=ADDR(GETBLOCK); /* Address the Orig Block */ /********************************************************************/ /* Scan the input for the lu name to activate */ /********************************************************************/ CALL CNMSCAN(HLBPTR, /* Parse the input ... */ CMDBUF, /* ...command line is the input */ ’%*S%8S’, /* ...skip over command name */ CNT, /* ...returned */ NODENAME); /* ...nodename */ IF CNT=1 THEN /* Nodename specified? */ DO; /* Yes... */ CALL CNMVARS(HLBPTR, /* Declare a variable ... */ DCL, /* ...declare function */ ’, /* ...not needed */ 0, /* ...not needed */ VARNM, /* ...specifies variable name */ LOCAL); /* ...local variable pool */ /********************************************************************/ /* Build the PIPE command. */ /* The VTAM stage issues the VARY command. */ /* The CORRWAIT stage waits 10 seconds for each message to */ /* return to the pipeline. */ /* The TOSTRING stage selects messages to remain in the pipeline */ /* up to and including one having ’IST093I’ in columns 1-7. */ /* The TAKE stage selects the last message in the pipeline, */ /* discarding all others. */ /* The VAR stage writes the message to the variable specified. */ /********************************************************************/ CALL CNMCMD(HLBPTR,’PIPE VTAM V NET,ACT,ID=’||NODENAME|| ’| CORRWAIT 10 ’ || ’| TOSTRING FIRST 1.7 /IST093I/ ’ || ’| TAKE LAST 1 ’ || ’| VAR ’ || VARNM );

CALL CNMVARS(HLBPTR, /* Read the variable ... */ GET, /* ...get the value */ INBUF, /* ...result goes here */ 256, /* ...max input length */ VARNM, /* ...specifies variable name */ LOCAL); /* ...local variable pool */

IF (SUBSTR(INBUF,1,7) = ’IST093I’) THEN /* Did we find IST093I? */ CALL CNMSMSG(HLBPTR, /* Inform user activation worked */ ’RESOURCE ’||NODENAME||’ NOW ACTIVE’,

68 Programming: PL/I and C PL/I High-Level Language Services

/* ...text of message */ ’MSG’, /* ...single line message */ ’OPER’, /* ...to the operator */ ’’); /* ...not needed */ ELSE /* IST093I not found, must be ...an error */ CALL CNMSMSG(HLBPTR, /* Inform user activation failed */ ’ERROR - ACTIVATION UNSUCCESSFUL’, /* ...text of message */ ’MSG’, /* ...single line message */ ’OPER’, /* ...to the operator */ ’’); /* ...not needed */ END; ELSE /* Nodename not specified */ CALL CNMSMSG(HLBPTR, /* Inform user need more args */ ’ERROR - NODENAME NOT SPECIFIED’, /* ...text of message */ ’MSG’, /* ...single line message */ ’OPER’, /* ...to the operator */ ’’); /* ...not needed */

For more information about the PIPE command, refer to IBM Tivoli NetView for z/OS Programming: Pipes.

Retrieving information “Retrieving Information (PL/I)” is an example of how an HLL command processor or installation exit routine can retrieve information from the NetView program.

For more information, see “CNMINFC (CNMINFOC): Query NetView Character Information” on page 218 and “CNMINFI (CNMINFOI): Query NetView Integer Information” on page 221 for a list of the values supported. Retrieving Information (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL CDATA CHAR(18) VAR; /* Character information holder */ DCL IDATA FIXED BIN(31,0); /* Integer information holder */

/********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ CALL CNMINFC(HLBPTR, /* Retrieve the date & time... */ ’DATETIME’, /* ...specify the variable */ CDATA, /* ...result goes here */ 18); /* ...at most 18 bytes */ CALL CNMINFI(HLBPTR, /* Retrieve the number of colors */ /* ...that the terminal supports */ ’COLORS’, /* ...specify the variable */ IDATA); /* ...result goes here */

Chapter 7. PL/I high-level language services 69 PL/I High-Level Language Services

Command list variable access “Accessing common global variables (PL/I)” shows the capability of updating common global variables. This example increments a global variable named GVARIABLE by 1. Task global variables are updated and read the same way. The only difference is the pool name TGLOBAL is specified instead of CGLOBAL.

“Accessing stem variables using the PIPE command (PL/I)” shows how to retrieve values from a stem variable after issuing a PIPE command with the STEM stage command. Accessing common global variables (PL/I) Accessing common global variables (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL DATA_IN CHAR(24) VAR; /* Holds the input data */ DCL DATA_IN_LEN FIXED BIN(31,0) INIT(24); /* Max length of input*/ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ /********************************************************************/ /* Find the value of the variable */ /********************************************************************/ CALL CNMVARS(HLBPTR, /* Read the global variable... */ ’GET’, /* ...function is read */ DATA_IN, /* ...result goes here */ DATA_IN_LEN, /* ...truncate after 24-bytes */ ’GVARIABLE’, /* ...variable name is GVARIABLE */ ’CGLOBAL’); /* ...variable pool is CGLOBAL */

DATA_IN=DATA_IN+1; /* Increment Variable */ /********************************************************************/ /* Set the global variable */ /********************************************************************/ CALL CNMVARS(HLBPTR, /* Update the global variable... */ ’PUT’, /* ...function is write */ DATA_IN, /* ...data is here */ ’’, /* ...not used */ ’GVARIABLE’, /* ...variable name is GVARIABLE */ ’CGLOBAL’); /* ...variable pool is CGLOBAL */ Accessing stem variables using the PIPE command (PL/I) Accessing stem variables using the PIPE command (PL/I) /*********************************************************************/ /* Other Declarations */ /*********************************************************************/ DCL NUMVARS CHAR(4) VARYING; /* Number of variables in stem */ DCL PIPECMD CHAR(256) VARYING; /* Buffer to hold PIPE command */ DCL STEMLINE CHAR(80) VARYING; /* Store value of stem variable */ DCL VARNAME CHAR(15) VARYING; /* Name of stem variable */ /*********************************************************************/ /* Execution */ /*********************************************************************/ /*********************************************************************/ /* Build a PIPE command. */ /* The < (From Disk) stage reads data into the pipeline from */

70 Programming: PL/I and C PL/I High-Level Language Services

/* MYINFILE, a member of a dataset associated with the ddname */ /* DSIPARM. The records are treated as single-line messages. */ /* The NLOCATE stage discards comments lines which begin with */ /* either ’*’ or ’/*’. */ /* The STEM stage writes the remaining messages from the pipeline */ /* to stemmed variables named PIPELINEx. */ /*********************************************************************/ PIPECMD = ’PIPE < MYINFILE’|| ’ | NLOCATE 1.1 &*& 1.2 &/*&’|| ’ | STEM PIPELINE’; /* Build PIPE command */

CNMCOMMAND DATA(PIPECMD); /* Issue PIPE command */

/*********************************************************************/ /* Local variable PIPELINE0 contains the character representation of */ /* the total number of PIPELINEx stem variables. */ /*********************************************************************/ VARNAME = ’PIPELINE0’; /*********************************************************************/ /* Get number of stem variables and store value in NUMVARS. */ /*********************************************************************/ CNMVARPOOL FUNC(’GET’) NAME(VARNAME) POOL(’LOCAL’) DATA(NUMVARS) LENG(4); /*********************************************************************/ /* Local variable PIPELINE1 contains the first non-comment line in */ /* MYINFILE. */ /*********************************************************************/ VARNAME = ’PIPELINE1’; /*********************************************************************/ /* Get first non-comment line and store value in STEMLINE. */ /*********************************************************************/ CNMVARPOOL FUNC(’GET’) NAME(VARNAME) POOL(’LOCAL’) DATA(STEMLINE) LENG(80);

For more information about the PIPE command, refer to IBM Tivoli NetView for z/OS Programming: Pipes.

Using locks “Accessing common global variables (PL/I)” on page 70 shows how you can update common global variables. However, the example does not provide for protecting the updating of the variable named GVARIABLE by using a lock. Assess the need for protecting the updating GVARIABLE on a case-by-case basis.

“Using locks (PL/I)” on page 72 shows how to modify “Accessing common global variables (PL/I)” on page 70 to obtain a lock before attempting the update. The lock name can be the same as the global variable, or it can be different.

If you decide that it is important to synchronize the updating of a variable, you can use the following lock method, or you can run all the updates on a given task. Because only one process can occur on a task at a time, the updates are serialized. This can be any task, including the PPT.

Chapter 7. PL/I high-level language services 71 PL/I High-Level Language Services

Using locks (PL/I) DCL DATA_IN CHAR(24) VAR; /* Holds the input data */ DCL DATA_IN_LEN FIXED BIN(31,0) INIT(24); /* Max length of input */ /********************************************************************/ /* Obtain the lock to secure the accuracy of the update */ /********************************************************************/ CALL CNMLK(HLBPTR, /* Obtain the Lock ... */ ’LOCK’, /* ...function is obtain lock */ ’GVARIABLE’, /* ...name of the lock */ ’’, /* ...not used */ ’WAIT’); /* ...wait if not available */ /********************************************************************/ /* Find out the value of the variable */ /********************************************************************/ CALL CNMVARS(HLBPTR, /* Read the global variable... */ ’GET’, /* ...function is read */ DATA_IN, /* ...result goes here */ DATA_IN_LEN, /* ...truncate after 24-bytes */ ’GVARIABLE’, /* ...variable name is GVARIABLE */ ’CGLOBAL’); /* ...variable pool is CGLOBAL */

Operator input “Operator input (PL/I)” shows how to code an HLL command processor to accept operator input in single-line mode. The interface is similar to the &PAUSE function of the NetView command list language. Input is requested by the application using the WAIT FOR OPINPUT command, and retrieved by the application using the CNMGETD service routine. The operator can respond by using the GO command. See “GO command” on page 177 for more information. Operator input (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL GETBLOCK CHAR(40); /* Area for the Orig Block */ DCL GETPTR PTR; /* Pointer to the Orig Block */ DCL DATA_INCHAR(256) VAR; /* Buffer area for messages */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/

72 Programming: PL/I and C PL/I High-Level Language Services

GETPTR=ADDR(GETBLOCK); /* Address the Orig Block */

CALL CNMSMSG(HLBPTR, /* Send a message... */ ’ENTER OPERATOR INPUT DATA’, /* ...text of message */ ’MSG’, /* ...single line message */ ’OPER’, /* ...to the invoking operator */ ’’); /* ...not used */ CALL CNMCMD(HLBPTR,’ WAIT 10 SECONDS FOR OPINPUT’); /* Wait... */ IF HLBRC=CNM_OPINPUT_ON_WAIT THEN DO; /* Operator input supplied... */ CALL CNMGETD(HLBPTR, /* Get the first trapped msg... */ ’GETMSG’, /* ...function is get a msg */ DATA_IN, /* ...result goes here */ 256, /* ...max input length */ GETBLOCK, /* ...must provide a work area */ OPERQ, /* ...message is on OPINPUT QUEUE*/ 1); /* ...get the first one */ CALL CNMSMSG(HLBPTR, /* Send a message... */ ’OPERATOR INPUT IS:||DATA_IN, /* ...text of message */ ’MSG’, /* ...single line message */ ’OPER’, /* ...to the invoking operator */ ’’); /* ...not used */ END; ELSE /* No operator input supplied */ CALL CNMSMSG(HLBPTR, /* Send a message... */ ’NO OPERATOR INPUT SUPPLIED’, /* ...text of message */ ’MSG’, /* ...single line message */ ’OPER’, /* ...to the invoking operator */ ’’); /* ...not used */

VIEW Command processor “View Command processor (PL/I)” uses the full-screen VIEW command processor to create and initialize a local variable called PARM1. The VIEW command processor is started, displaying a full-screen panel. For more information, refer to the IBM Tivoli NetView for z/OS Customization Guide. View Command processor (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL DATA_INCHAR(48) VAR; /* Input buffer for results */

/********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ CNMVARPOOL FUNC(’DCL’) /* Declare to local pool... */ /* ...prior to invoking VIEW */ NAME(’PARM1’) /* ...name is Parm1 */ POOL(’LOCAL’); /* ...the pool is local */

CNMVARPOOL FUNC(’PUT’) /* Initialize PARM1... */ DATA(’the contents of parm1 go here’) /* ...data */ NAME(’PARM1’) /* ...name of local variable */ POOL(’LOCAL’); /* ...the pool is local */

/* Invoke the VIEW command. Give the task name as a unique */ /* name to go on the view stack. */

CNMCOMMAND DATA(’VIEW ’|| ORIGIN->ORIG_TASK||’ TESTHLL NOMSG NOINPUT’);

Chapter 7. PL/I high-level language services 73 PL/I High-Level Language Services

Figure 2 shows the panel definition that is started by “View Command processor (PL/I)” on page 73.

+TESTHLL %TEST THE VIEW COMMAND WITH HLL $ ======$ $ ======$ $ Example of using the VIEW command with HLL: $ $ Notes: The field below, PARM1,is defined as a variable $ by preceding the string PARM1 with an ampersand (&). $ $ $ $ $ $ $ $ $ $ INPUT======> &PARM1 $ ======%Action===>~&CUR $ $

Figure 2. Sample panel definition

Message processing “Message processing (PL/I)” lists the message attributes of a message. The invocation must be a result of an entry in the NetView automation table. This example applies to both single-line and multiline messages. Refer to IBM Tivoli NetView for z/OS Automation Guide for more information. Message processing (PL/I) DCL GETBLOCK CHAR(40); /* Area for the Orig Block */ DCL GETPTR PTR; /* Pointer to the Orig Block */ DCL INBUF CHAR(256) VAR; /* Buffer area for messages */ DCL DATA_IN CHAR(12) VAR; /* Attribute result */ DCL ATTR(12) CHAR(8) INIT( /* 12 message attributes: */ ’AREAID’ ,’DESC’ ,’JOBNAME’,’JOBNUM’,’MCSFLAG’ ,’MSGTYP’, ’REPLYID’,’ROUTCDE’,’SESSID’ ,’SMSGID’,’SYSCONID’,’SYSID’); /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ GETPTR=ADDR(GETBLOCK); /* Address the Orig Block */ CALL CNMGETD(HLBPTR, /* Get the first line of the msg */ ’GETMSG’, /* ...function is get a msg */ INBUF, /* ...result goes here */ 256, /* ...max input length */ GETBLOCK, /* ...must provide a work area */ IDATAQ, /* ...message from automation */ 1); /* ...get the first line of msg */ DO WHILE(HLBRC=CNM_GOOD /* Loop through the messages... */ HLBRC=CNM_DATA_TRUNC); /* ...ignoring truncation */ DO I=1 TO 12; /* For 12 possible attributes... */ CALL CNMGETA(HLBPTR, /* Get the Ith attribute... */ ATTR(I), /* ...Ith member of array */ DATA_IN, /* ...result goes here */ 12, /* ...at most 12 bytes */ IDATAQ); /* ...on the initial data queue */ CALL CNMSMSG(HLBPTR,ATTR(I)||’ = ’||DATA_IN,’MSG’,’OPER’,’’);

74 Programming: PL/I and C PL/I High-Level Language Services

END; CALL CNMSMSG(HLBPTR,’LINETYPE = ’||GETPTR->ORIG_BLOCK.ORIG_LINE_TYPE, ’MSG’,’OPER’,’’); CALL CNMSMSG(HLBPTR,’HDRMTYPE = ’||GETPTR->ORIG_BLOCK.ORIG_MSG_TYPE, ’MSG’,’OPER’,’’); CALL CNMSMSG(HLBPTR,’MSGID = ’||GETPTR->ORIG_BLOCK.ORIG_PROCESS, ’MSG’,’OPER’,’’); CALL CNMSMSG(HLBPTR,’MSGSTR = ’||INBUF, ’MSG’,’OPER’,’’); CALL CNMGETD(HLBPTR, /* Get next line of message... */ ’GETLINE’, /* ...function is get next line */ INBUF, /* ...result goes here */ 255, /* ...max input length */ GETBLOCK, /* ...must provide a work area */ IDATAQ, /* ...message is from automation */ 1); /* ...get the next line */ END; /* Of DO WHILE */ HLBRC=CNM_GOOD; /* Clear RC */

Command authorization checking This section describes an example of the command authorization checking capabilities provided by the NetView program. You define the operator, the operator's authority, and the restrictions on starting the command, keyword, and value.

The command gives the return code that the command authorization checking service routine returned to the operator.

The syntax for which this command checks is as follows:

PSPCCKO

►► PSPCCKO PARM x ( VAL x ) ►◄

Where: PARMx Specifies the keyword variable used to perform the authorization check. VALx Indicates the value variable used to perform the authorization check.

Before using the example in “Command authorization checking (PL/I) ” on page 77, perform the following NetView set-up as it applies to your method of command authorization checking. Command authorization checking using CMDAUTH=TABLE If you are using CMDAUTH=TABLE with TBLNAME=CMDTABLE in NetView domain CNM01 in network NETA, perform the following setup before using the sample code. In DSIPARM(CMDTABLE) Restrict access to the command, keywords, and values as well as the operators and classes that can access them.

Chapter 7. PL/I high-level language services 75 PL/I High-Level Language Services

The command PSPCCKO can be started by operators in GRP1 and GRP2. Operators in GRP1 can issue any keyword or keyword value, but operators in GRP2 cannot use the value of VAL1 with keyword PARM2 and cannot issue PARM3. PROTECT NETA.CNM01.PSPCCKO PROTECT NETA.CNM01.PSPCCKO.PARM2 PROTECT NETA.CNM01.PSPCCKO.PARM2.VAL1 PROTECT NETA.CNM01.PSPCCKO.PARM3 PROTECT NETA.CNM01.PSPCCKO.PARM3.VAL1 GROUP GRP1 OPER1,OPER2,FRANK,BILL,JENNY GROUP GRP2 OPER3,OPER4,FRED,LISA,BETH GROUP GRP3 JOE PERMIT GRP1 NETA.CNM01.PSPCCKO PERMIT GRP1 NETA.CNM01.PSPCCKO.PARM2 PERMIT GRP1 NETA.CNM01.PSPCCKO.PARM2.VAL1 PERMIT GRP1 NETA.CNM01.PSPCCKO.PARM3 PERMIT GRP1 NETA.CNM01.PSPCCKO.PARM3.VAL1 PERMIT GRP2 NETA.CNM01.PSPCCKO PERMIT GRP2 NETA.CNM01.PSPCCKO.PARM2 Command authorization checking using CMDAUTH=SAF If you are using CMDAUTH=SAF and OPERSEC=SAFDEF in the CNM01 NetView domain in the NETA network, perform the following setup before using the sample code. RACF® is used as the SAF product in this example. In RACF Restrict access to the command, keywords, and values as well as the operators and classes that can access them.

The command PSPCCKO can be started by operators in GRP1 and GRP2. Operators in GRP1 can issue any keyword or keyword value, but operators in GRP2 cannot use the value of VAL1 with keyword PARM2 and cannot issue PARM3. RDEFINE NETCMDS NETA.CNM01.PSPCCKO UACC(NONE) RDEFINE NETCMDS NETA.CNM01.PSPCCKO.PARM2 UACC(NONE) RDEFINE NETCMDS NETA.CNM01.PSPCCKO.PARM2.VAL1 UACC(NONE) RDEFINE NETCMDS NETA.CNM01.PSPCCKO.PARM3 UACC(NONE) RDEFINE NETCMDS NETA.CNM01.PSPCCKO.PARM3.VAL1 UACC(NONE) ADDGROUP GRP1 ADDGROUP GRP2 ADDGROUP GRP3 CONNECT OPER1 GROUP(GRP1) CONNECT OPER2 GROUP(GRP1) CONNECT FRANK GROUP(GRP1) CONNECT BILL GROUP(GRP1) CONNECT JENNY GROUP(GRP1) CONNECT OPER3 GROUP(GRP2) CONNECT OPER4 GROUP(GRP2) CONNECT FRED GROUP(GRP2) CONNECT LISA GROUP(GRP2) CONNECT BETH GROUP(GRP2) CONNECT JOE GROUP(GRP3) PERMIT NETA.CNM01.PSPCCKO CLASS(NETCMDS) ID(GRP1) ACCESS(READ) PERMIT NETA.CNM01.PSPCCKO.PARM2 CLASS(NETCMDS) ID(GRP1) ACCESS(READ) PERMIT NETA.CNM01.PSPCCKO.PARM2.VAL1 CLASS(NETCMDS) ID(GRP1) ACCESS(READ) PERMIT NETA.CNM01.PSPCCKO.PARM3 CLASS(NETCMDS) ID(GRP1) ACCESS(READ) PERMIT NETA.CNM01.PSPCCKO.PARM3.VAL1 CLASS(NETCMDS) ID(GRP1) ACCESS(READ) PERMIT NETA.CNM01.PSPCCKO CLASS(NETCMDS) ID(GRP2) ACCESS(READ) PERMIT NETA.CNM01.PSPCCKO.PARM2 CLASS(NETCMDS) ID(GRP2) ACCESS(READ)

76 Programming: PL/I and C PL/I High-Level Language Services

Command authorization checking sample code Command authorization checking (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL INBUF CHAR(80) VAR; /* Buffer area for messages */ DCL CMDNAMEV CHAR(8) VAR; /* Command that invoked us */ DCL KEYWORDV CHAR(8) VAR; /* Keyword of invocation */ DCL KEYVALUEV CHAR(8) VAR; /* KeyValue of invocation */ DCL CMDNAME CHAR(8); /* Command that invoked us */ DCL KEYWORD CHAR(8); /* Keyword of invocation */ DCL KEYVALUE CHAR(8); /* KeyValue of invocation */ DCL CNT FIXED BIN(31,0); /* Number of elements parsed */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ /********************************************************************/ /* Scan the keyword and the value */ /********************************************************************/ CALL CNMSCAN(HLBPTR, /* Parse the input ... */ CMDBUF, /* ...command line is the input */ /* SYNTAX OF COMMAND IS: */ /* CMDNAME KEYWORD(KEYVALUE) */ /* */ /* Scan for the: */ ’%S’|| /* ...command name */ ’%*{ }’|| /* ...skip over leading blanks */ ’%{¬(}’|| /* ...keyword up to "(" */ ’%*C’|| /* ...skip over "(" */ ’%{¬)}’, /* ...keyvalue up to ")" */ CNT, /* ...number strings parsed */ CMDNAMEV, /* ...command goes here */ KEYWORDV, /* ...keyword goes here */ KEYVALUEV); /* ...keyvalue goes in here */ CMDNAME=CMDNAMEV; /* Get fixed length value */ KEYWORD=KEYWORDV; /* Get fixed length value */ KEYVALUE=KEYVALUEV; /* Get fixed length value */ IF CNT=3 THEN /* Enough parms specified? */ CALL CNMSCOP(HLBPTR, /* Perform authorization checking*/ CMDNAME, /* ...the command */ KEYWORD, /* ...the keyword */ KEYVALUE); /* ...the value */ ELSE /* Not enough parms specified */ HLBRC=CNM_BAD_INVOCATION; /* Set rc */ /********************************************************************/ /* Inform user of the return code results... */ /********************************************************************/ SELECT; WHEN(HLBRC=CNM_GOOD) DO; /* Operator */ /* has */ /* passed */ END; /* authorization checking */ WHEN(HLBRC=CNM_KEYWORD_NA) CALL CNMSMSG(HLBPTR,’ Not authorized to use KEYWORD ’||KEYWORD, ’MSG’,’OPER’,’’); WHEN(HLBRC=CNM_VALUE_NA) CALL CNMSMSG(HLBPTR,’ Not authorized to use VALUE ’||KEYVALUE, ’MSG’,’OPER’,’’); WHEN(HLBRC=CNM_BAD_INVOCATION) CALL CNMSMSG(HLBPTR,’ Not enough parms specified’,

Chapter 7. PL/I high-level language services 77 PL/I High-Level Language Services

’MSG’,’OPER’,’’); OTHERWISE CALL CNMSMSG(HLBPTR,’ RC not recognized...’||HLBRC, ’MSG’,’OPER’,’’); END; HLBRC=CNM_GOOD; /* Clear RC */

Altering data The DSIEX02A installation exit routine changes the echoed command message (MSGTYPE=*) to be more informative by giving the time that the command was entered.

Without the exit, the output is: WHO

With the exit, the output is: Command entered was: "WHO" at 12:00:00

Altering data (PL/I) DSIEX02A: PROC(HLBPTR,CMDBUF,ORIGBLCK) OPTIONS(MAIN,REENTRANT); /********************************************************************/ /* */ ...... /* Change Activity: */ /* date,author: description of changes */ /********************************************************************/ /********************************************************************/ /* */ /* Operand Declarations */ /* */ /********************************************************************/ DCL HLBPTR PTR; /* Pointer to the HLB */ %INCLUDE DSIPLI; /* Include the HLL macros */ DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ DCL ORIGBLCK CHAR(40); /* Area for the Orig Block */ DCL ORIGIN PTR; /* Pointer to the Orig Block */ DCL ADDR BUILTIN; /* Built-in function */ ORIGIN=ADDR(ORIGBLCK); /* Address the Orig Block */ /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL GETBLOCK CHAR(40); /* Area for the Orig Block */ DCL DATAIN CHAR(255) VAR; /* Old command text */ DCL TIME CHAR(256) VAR; /* Area for time */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ GETPTR=ADDR(GETBLOCK); /* Address the Orig block */ CNMINFOC /* Retrieve the time... */ ITEM(’TIME’) /* ...variable is time of day */ DATA(TIME) /* ...the result goes here */ LENG(256); /* ...max length of 256 */ CNMGETDATA /* Peek the msg before altering */ FUNC(’PEEKLINE’) /* ...subfunction is PEEK */ QUEUE(IDATAQ) /* ...initial data queue */ DATA(DATAIN) /* ...result goes here */

78 Programming: PL/I and C PL/I High-Level Language Services

LENG(256) /* ...max length is 256 */ ORIGIN(GETBLOCK) /* ...use new Orig block */ LINE(1); /* ...check the first line */ IF GETPTR->ORIG_MSG_TYPE =’*’ THEN /* Echo’ed message? */ CNMALTDATA /* Replace the text ... */ FUNC(’REPLINE’) /* ...function is replace */ QUEUE(IDATAQ) /* ...initial data queue */ DATA(’Command entered was: "’||DATAIN||’" at ’||TIME) /* ...text of new message */ ORIGIN(GETBLOCK) /* ...use Peeked Orig block */ LINE(1); /* ...replace the first line */ HLBRC=CNM_GOOD; /* Clear RC */ END DSIEX02A;

Storage access “Storage Access (PL/I)” shows how to display the character representation of the contents of the storage that the NetView program can access. For example, after locating the address of the main vector table using DISPMOD DSIMNTEX, you can display the first 4 bytes of the DSIMVT control block. Storage Access (PL/I) DCL NUM_PARMS FIXED BIN(31); /* Number of parms passed */ DCL XADDR FIXED BIN(31); /* Hex value of source_ptr */ DCL NUM_BYTES FIXED BIN(31); /* Number of bytes to display */ DCL INPUT_BFR CHAR(4096); /* Buffer where data is copied */ DCL SOURCE_PTR PTR; /* Address to copy from */ DCL I FIXED BIN(31); /* Work counter */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ CNMSSCAN DATA(CMDBUF) /* Scan the command for: */ FORMAT(’%*S’|| /* ...skip the command */ ’%X’|| /* ...save the source address */ ’%X’) /* ...save the length */ COUNT(NUM_PARMS) /* ...number of parms scanned */ P1(XADDR) /* ...the address to display */ P2(NUM_BYTES); /* ...for this number of bytes */ SELECT; WHEN(NUM_PARMS¬=2) /* Did they give an address and ... a length? */ CNMSENDMSG /* No, give error message... */ DATA(’INVALID NUMBER OF OPERANDS’) /* ...text */ MSGTYPE(’MSG’) /* ... message */ DESTTYPE(’OPER’); /* ... to the operator */ WHEN(NUM_BYTES<=0) /* Did they give a valid length ?*/ CNMSENDMSG /* No, give error message... */ DATA(’INVALID LENGTH GIVEN’) /* ...text */ MSGTYPE(’MSG’) /* ... message */ DESTTYPE(’OPER’); /* ... to the operator */ WHEN(NUM_BYTES>=4096) /* Did they give a valid length ?*/ CNMSENDMSG /* No, give error message... */ DATA(’INVALID LENGTH GIVEN, MUST BE LESS THAN ’|| ’OR EQUAL TO FFF’) /* ...text of message */ MSGTYPE(’MSG’) /* ... message */ DESTTYPE(’OPER’); /* ... to the operator */ OTHERWISE DO; UNSPEC(SOURCE_PTR) = UNSPEC(XADDR); /* assign value into a ptr */ CNMCOPYSTR /* Copy storage */

Chapter 7. PL/I high-level language services 79 PL/I High-Level Language Services

FROM(SOURCE_PTR) /* ...from the address given */ TO(ADDR(INPUT_BFR)) /* ...to the internal buffer */ LENG(NUM_BYTES) /* ...for up to FFF bytes */ COPYTYPE(’FIXTOFIX’); /* ...data is fixed len vars */ IF HLBRC = CNM_GOOD THEN /* Good RC ? */ DO I=1 TO NUM_BYTES BY 64; /* Display storage */ CNMSENDMSG DATA(SUBSTR(INPUT_BFR,I,64)) /* ...64-byte */ MSGTYPE(’MSG’) /* ...in a message */ DESTTYPE(’OPER’); /* ...to the operator */ END; ELSE /* Bad RC -- */ CNMSENDMSG /* Send message ... */ DATA(’INVALID OR PROTECTED ADDRESS’) /* ...text */ MSGTYPE(’MSG’) /* ...in a message */ DESTTYPE(’OPER’); /* ...to the operator */ END; /* of otherwise */ END; /* of select */

Data set access “Data set access (PL/I)” contains sample code for opening (CNMMEMO), reading (CNMMEMR), and closing (CNMMEMC) NetView partitioned data sets. This example reads the CNMSTYLE member and displays the contents to the operator. Data set access (PL/I) DCL MEMBER CHAR(8); /* Member name to read */ DCL DDNAME CHAR(8); /* DDNAME to read */ DCL TOKEN FIXED BIN(31,0); /* Token used to match open to ...read and close */ DCL MRDATA CHAR(80) VAR; /* Line that is read */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ DDNAME=’DSIPARM’; MEMBER=’CNMSTYLE’; /********************************************************************/ /* OPEN THE MEMBER */ /********************************************************************/ CALL CNMMEMO(HLBPTR, /* Open the data set member ... */ TOKEN, /* ... token returned by HLL */ DDNAME, /* ... ddname of PDS */ MEMBER); /* ... member name of PDS */ IF HLBRC¬=CNM_GOOD THEN CALL CNMSMSG(HLBPTR, /* OPEN failed... */ ’OPEN FOR DATA SET FAILED RC=’||CHAR(HLBRC), ’MSG’, /* ...single line message */ ’OPER’, /* ...to the operator */ ’’); /* ...taskname ignored */ ELSE DO; /* Open was successful... */ /****************************************************************/ /* READ THE MEMBER */ /****************************************************************/ CALL CNMMEMR(HLBPTR, /* Read the first record... */ TOKEN, /* ... provide token from OPEN */ MRDATA, /* ... result goes here */ 80); /* ... read 80 bytes */ DO WHILE (HLBRC=CNM_GOOD); /* Read til EOF */ CALL CNMSMSG(HLBPTR, /* Write out last record read... */ SUBSTR(MRDATA,1,72),/* ...write first 72 bytes */ ’MSG’, /* ...single line message */ ’OPER’, /* ...to the operator */ ’’); /* ...taskname ignored */

80 Programming: PL/I and C PL/I High-Level Language Services

CALL CNMMEMR(HLBPTR, /* Read the next record... */ TOKEN, /* ... provide token from OPEN */ MRDATA, /* ... result goes here */ 80); /* ... read 80 bytes */ END; /****************************************************************/ /* CLOSE THE MEMBER */ /****************************************************************/ CALL CNMMEMC(HLBPTR, /* Close the PDS member... */ TOKEN); /* ... using the token from OPEN */ END; /* End of Open was successful... */

Communicating with devices The NetView program provides the CNMCNMI service routine for use in communicating with devices in the network through the CNMI. You can access any data that is returned using the CNMGETD service routine to retrieve records from the CNMI solicited data queue (CNMIQ).

“CNMCNMI service routine (PL/I)” uses the CNMCNMI service routine to send a request for product set ID data to a specified PU. Any data returned is sent as a message to the operator.

The syntax of the command is:

PNMVTPU

OWN ►► PNMVTPU puname ►◄ ALL

Chapter 7. PL/I high-level language services 81 PL/I High-Level Language Services

/* */ /* Vital Product Data RU definitions */ /* */ /* From the VTAM Programming Manual, a forward RU is defined below */ /* */ /* Byte Value Description */ /* 0 81 Network services, logical services */ /* 1 08 Management services */ /* 2 10 Request code */ /* 3 00 Format 0 */ /* 4 00 Ignore target names, */ /* Solicit a reply, and */ /* No CNM header contained */ /* 5 00 Reserved */ /* 6-7 000E Length of NS RU */ /* 8-15 NS RU -- NMVT -- documented in SNA Ref Sum */ /* 8-A 41038D NS Header for NMVT */ /* B-C 0000 Retired */ /* D-E 0111 PRID */ /* F 00 unsolicited NMVT, */ /* only NMVT for this PRID */ /* 10-16 One MS major vector */ /* 10-11 0006 Length field of PSID (Product Set ID) vector */ /* 12-13 8090 Code point for PSID */ /* 14-15 Length of subvector */ /* 14 02 Length of subvector */ /* 15 81 Request information on control unit only */ /* 15 83 Request information on control unit and its */ /* attached devices */ /* 16 F1 From VTAM programming, PU */ /* 17 08 Length of PU name */ /* 18 PUNAME Eight byte PUNAME, left justified */ /* 20 00 End of RU */ /********************************************************************/ DCL FORWARD_RU CHAR(100) VAR INIT( ’810810000000000E41038D00000111000006809002’X); DCL OWN CHAR(1) VAR INIT(’81’X); DCL ALL CHAR(1) VAR INIT(’83’X); DCL PUNAME_HDR CHAR(2) VAR INIT(’F108’X); DCL ENDOFRU CHAR(1) VAR INIT(’00’X); /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ RCODE=0; /* Initialize return code */ GETPTR=ADDR(GETBLOCK); /* Address the work Orig Block */

CALL CNMSCAN(HLBPTR, /* Scan the command line... */ CMDBUF, /* ...input in command line */ ’%*S0S’, /* ...skip over the command */ COUNT, /* ...number of args parsed */ PUNAMEV, /* ...puname */ OWNORALL); /* ...own or all specified */ PUNAME=PUNAMEV; /* Get fixed length PU name */

SELECT; WHEN(COUNT=1) /* Own or All not specified */ FORWARD_RU=FORWARD_RU||OWN||PUNAME_HDR||PUNAME||ENDOFRU; /* Default is OWN */ WHEN(OWNORALL=’OWN’) /* Own or All not specified */ FORWARD_RU=FORWARD_RU||OWN||PUNAME_HDR||PUNAME||ENDOFRU; /* Process OWN */ WHEN(OWNORALL=’ALL’) /* Own or All not specified */ FORWARD_RU=FORWARD_RU||ALL||PUNAME_HDR||PUNAME||ENDOFRU; OTHERWISE /* Invalid parm... tell user */ DO;

82 Programming: PL/I and C PL/I High-Level Language Services

CALL CNMSMSG(HLBPTR,’INVALID COMMAND SYNTAX’, /* wrong... */ ’MSG’,’TASK’,ORIGIN ->ORIG_TASK); /* ...syntax */ RCODE=8; /* Bad syntax */ END; END; /* Of Select */ IF RCODE = 0 THEN /* Good so far? */ DO; /* Yes, continue */ CALL CNMCNMI(HLBPTR, /* Send RU over the CNMI... */ ’SENDRPLY’, /* ...expect a reply */ FORWARD_RU, /* ...RU built above */ PUNAME, /* ...to the PUNAME specified */ 180); /* ...timeout after 3 minutes */ IF HLBRC=CNM_GOOD THEN /* Everything OK? */ DO; /* Yes, continue */ CALL CNMGETD(HLBPTR, /* Read in the first RU returned */ ’GETLINE’, /* ...a single RU */ DATAIN, /* ...into here */ 1024, /* ...truncate after 1024-bytes */ GETBLOCK, /* ...provide a new origblock */ CNMIQ, /* ...on the CNMI queue */ 1); /* ...the first RU */ DO WHILE(HLBRC=CNM_GOOD); /* End of queue reached? */ CALL CNMSMSG(HLBPTR, /* Send info to the operator... */ DATAIN, /* ...from here */ ’MSG’, /* ...issue message */ ’TASK’, /* ...to the task */ ORIGIN ->ORIG_TASK); /* ...that originated request*/ CALL CNMGETD(HLBPTR, /* Read in the next RU returned */ ’GETLINE’, /* ...a single RU */ DATAIN, /* ...into here */ 1024, /* ...truncate after 1024-bytes */ GETBLOCK, /* ...provide a new origblock */ CNMIQ, /* ...on the CNMI queue */ 1); /* ...the next RU */ END; /* of DO WHILE */ END; /* Of everything ok */ ELSE DO; /* CNMI error */ SELECT(HLBRC); WHEN(CNM_BAD_INVOCATION) /* Not invoked under a DST */ CALL CNMSMSG(HLBPTR,’Must run under a DST’, ’MSG’,’TASK’,ORIGIN ->ORIG_TASK);

WHEN(CNM_TIME_OUT) /* PU never answered request */ CALL CNMSMSG(HLBPTR,’PU never answered’, ’MSG’,’TASK’,ORIGIN ->ORIG_TASK); WHEN(CNM_NEG_RESPONSE) /* PU gave a negative response */ CALL CNMSMSG(HLBPTR,’PU gave a negative response’, ’MSG’,’TASK’,ORIGIN ->ORIG_TASK); OTHERWISE CALL CNMSMSG(HLBPTR,’CNMI request failed RC=’|| CHAR(HLBRC),’MSG’,’TASK’,ORIGIN->ORIG_TASK); END; /* Of Select */ END; /* of CNMI error */ END; /* of Good so far */ HLBRC=RCODE; /* Issue rc */

Performing I/O on a VSAM file (Keyed File Access) “Keyed File Access (PL/I)” on page 84 shows coding a NetView HLL command processor that allows I/O to a VSAM file through the CNMKIO service routine.

The command processor must run on a DST. Use either the CNMSMSG service routine (with a type of COMMAND) or the EXCMD command.

Chapter 7. PL/I high-level language services 83 PL/I High-Level Language Services

“Keyed File Access (PL/I)” creates a database with five records and the following keys and data: Key Data 01 A 02 B 03 C 04 D 05 E Keyed File Access (PL/I) DCL REC CHAR(10) VAR; /* Record that is output */ DCL INREC CHAR(10) VAR; /* Input record */ DCL KEY CHAR(2) VAR; /* Key to record */ DCL OUTDATA(5) CHAR(8) VAR INIT( /* Data */ ’A’,’B’,’C’,’D’,’E’); DCL KEYDATA(5) CHAR(2) VAR INIT( /* Keys */ ’01’,’02’,’03’,’04’,’05’); /********************************************************************/ /* Execution -- WRITE OUT 5 RECORDS... */ /* */ /* PUT DIRECT must be used for new records, and PUT UPDATE must */ /* be used for existing records. Therefore, we use GET EQUAL */ /* to determine if the record is new or not. If new, then a PUT */ /* DIRECT will follow...if not, then a PUT UPDATE follows. */ /* */ /********************************************************************/ DO I = 1 TO HBOUND(OUTDATA,1); /* For 5 records */ KEY=KEYDATA(I); /* Set key portion of record */ REC=KEY||OUTDATA(I); /* Record must have key first */ CALL CNMKIO(HLBPTR, /* Provide HLB pointer... */ ’GET_EQ’, /* ... requesting a get */ INREC, /* ... data is in inrec */ 10, /* ... 10 bytes max input */ KEY, /* ... key is in key */ ’UPDATE’); /* ... this is an update */ IF HLBRC=CNM_NOT_FOUND THEN DO; CALL CNMKIO(HLBPTR, /* Provide HLB pointer... */ ’PUT’, /* ... requesting a put */ REC, /* ... data is in rec */ 0, /* ... not used */ KEY, /* ... key is in key */ ’DIRECT’); /* ... this is not an update */ IF HLBRC¬=CNM_GOOD THEN CALL CNMSMSG(HLBPTR, /* Issue error message... */ ’CNMKEYIO PUT REQUEST FAILED, RC=’||CHAR(HLBRC), /* ... text of message */ ’MSG’, /* ... single line message */ ’TASK’, /* ... to the task */ ORIGIN->ORIG_BLOCK.ORIG_TASK); /* ...that invoked */ END; ELSE CALL CNMKIO(HLBPTR, /* Provide HLB pointer... */ ’PUT’, /* ... requesting a put */ REC, /* ... data is in rec */ 0, /* ... not used */ KEY, /* ... key is in key */ ’UPDATE’); /* ... this is an update */ IF HLBRC¬=CNM_GOOD THEN CALL CNMSMSG(HLBPTR, /* Issue error message... */ ’CNMKEYIO PUT REQUEST FAILED, RC=’||CHAR(HLBRC),

84 Programming: PL/I and C PL/I High-Level Language Services

/* ... text of message */ ’MSG’, /* ... single line message */ ’TASK’, /* ... to the task */ ORIGIN->ORIG_BLOCK.ORIG_TASK); /* ...that invoked */ END; /********************************************************************/ /* READ IN THE 5 RECORDS... */ /********************************************************************/ DO I = 1 TO HBOUND(OUTDATA,1); /* For 5 records */ KEY=KEYDATA(I); /* Set key portion of record */ CALL CNMKIO(HLBPTR, /* Provide HLB pointer... */ ’GET_EQ’, /* ... requesting a get */ INREC, /* ... data is in inrec */ 10, /* ... 10 bytes max input */ KEY, /* ... key is in key */ ’NOUPDATE’); /* ... this is not an update */ IF HLBRC¬=CNM_GOOD THEN CALL CNMSMSG(HLBPTR, /* Issue error message... */ ’CNMKEYIO GET REQUEST FAILED, RC=’||CHAR(HLBRC), /* ... text of message */ ’MSG’, /* ... single line message */ ’TASK’, /* ... to the task */ ORIGIN->ORIG_BLOCK.ORIG_TASK); /* ...that invoked */ END;

HLBRC=CNM_GOOD; /* Issue clean rc */

Coding a DST installation exit “Coding a DST installation exit (PL/I)” shows coding a NetView HLL installation exit routine that primes an empty VSAM database for a DST. If a VSAM database has not been primed (has at least one record), subsequent I/O requests fail. Coding a DST installation exit (PL/I) PPRMVDB: PROC(HLBPTR,CMDBUF,ORIGBLCK) OPTIONS(MAIN,REENTRANT); /********************************************************************/ /* */ /* Descriptive Name: High Level Language PL/I DSIXITVN Example */ /* */ ...... /* Change Activity: */ /* date,author: description of changes */ /* */ /********************************************************************/

/********************************************************************/ /* */ /* Operand Declarations */ /* */ /********************************************************************/ DCL HLBPTR PTR; /* Pointer to the HLB */ %INCLUDE DSIPLI; /* Include the HLL macros */ DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ DCL ORIGBLCK CHAR(40); /* Area for the Orig Block */ DCL ORIGIN PTR; /* Pointer to the Orig Block */ DCL ADDR BUILTIN; /* Built-in function */ ORIGIN=ADDR(ORIGBLCK); /* Address the Orig Block */ /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL KEY CHAR(2) VAR; /* 2-byte key of the record */

Chapter 7. PL/I high-level language services 85 PL/I High-Level Language Services

/********************************************************************/ /* */ /* Execution - */ /* */ /* Create the record to initialize the VSAM database. The */ /* record will have a key of 0000 and a value of "Low rec". */ /* Setting the HLBRC to USERSWAP (8) will cause the contents */ /* of CMDBUF to be swapped into the database, thereby giving */ /* it an initial value, and enabling the subsequent VSAM I/O. */ /* */ /********************************************************************/ KEY=’0000’X; /* Set key to low values */ CMDBUF=KEY||’Low rec’; /* Build the data record */ HLBRC=USERSWAP; /* Set USERSWAP rc */ END PPRMVDB;

Coding an installation exit “Coding an installation exit (PL/I)” shows coding an installation exit routine, DSIEX03, that sets a task global variable equal to the last time a command was entered on the system. If the last command was the PSNDDAT command, the task global variable is not set. The PSNDDAT command is used to receive the variable value. See “Sending data (PL/I)” on page 89. Coding an installation exit (PL/I) PSETTG: PROC(HLBPTR,CMDBUF,ORIGBLCK) OPTIONS(MAIN,REENTRANT); /********************************************************************/ /* */ ./* Descriptive Name: High Level Language PL/I DSIEX03 Example */ . /* Change Activity: */ /* date,author: description of changes */ /* */ /********************************************************************/ /********************************************************************/ /* */ /* Operand Declarations */ /* */ /********************************************************************/ DCL HLBPTR PTR; /* Pointer to the HLB */ %INCLUDE DSIPLI; /* Include the HLL macros */ DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ DCL ORIGBLCK CHAR(40); /* Area for the Orig Block */ DCL ORIGIN PTR; /* Pointer to the Orig Block */ DCL ADDR BUILTIN; /* Built-in function */ ORIGIN=ADDR(ORIGBLCK); /* Address the Orig Block */ /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL TIME CHAR(256) VAR; /* Time last command entered */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ IF INDEX(CMDBUF,’PSNDDAT’)¬=1 THEN /* Command other than PSNDDAT? */ DO; /* Yes... */ CNMINFOC /* Gather NetView information... */ ITEM(’TIME’) /* ...what time is it? */ DATA(TIME) /* ...answer goes here */ LENG(256); /* ...length of time */ CNMVARPOOL FUNC(’PUT’) /* Put answer in task global... */

86 Programming: PL/I and C PL/I High-Level Language Services

NAME(’LAST_COMMAND_TIME’) /* ...by the name of... */ POOL(’TGLOBAL’) /* ...task global pool */ DATA(TIME); /* ...information in TIME */ END; HLBRC=USERASIS; /* Clear RC */ END PSETTG;

Coding the WAIT FOR DATA function PWATDAT and PSNDDAT are standard command processors that can be started from an installation exit. The following sections describe sending messages with a type of request, waiting on the response, and parsing the results. The code in this example is the PWATDAT command.

The syntax of the command is:

PWATDAT

►► PWATDAT taskname ►◄

Figure 3. Syntax for PWATDAT

Where: taskname Specifies the task global variable set by the installation exit and retrieved by the PSNDDAT command.

Figure 4 on page 88 shows the flow of the WAIT FOR DATA function.

Chapter 7. PL/I high-level language services 87 PL/I High-Level Language Services

Requesting Data Sending Data

The requesting OST invokes PWATDAT and specifies the target OST to which to send the request.

PWATDAT uses CNMSMSG to send the request to the target OST.

Waiting for Data

The requesting OST The PSNDDAT command issues a WAIT FOR is invoked on the DATA. target OST and finds the task global variable set by DSIEX03.

CNMSMSG is invoked to send the value retrieved. The type used in the CNMSMSG is DATA.

The WAIT FOR DATA is satisfied and a message is issued.

Figure 4. Flow of the WAIT FOR DATA Function (PL/I)

Requesting data (PL/I) The declaration “Requesting data (PL/I)” shows how to request data. The example finds the last time that a command was entered on the given operator station task (OST). A task global variable, LAST_COMMAND_TIME, is set by DSIEX03. See “Coding an installation exit” on page 86.

This indefinite value is retrieved by the PSNDDAT command that is started on the target task. See “Sending data (PL/I)” on page 89. Requesting data (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */ /********************************************************************/ DCL GETBLOCK CHAR(40), /* Area for the Orig Block */ NEWMSG CHAR(256) VAR, /* Message sent from PSNDDAT */ TARGTASK CHAR(8) VAR, /* Task of inquiry */

88 Programming: PL/I and C PL/I High-Level Language Services

TARGTASKF CHAR(8); /* Task of inquiry */ DCL PARMCNT FIXED BIN(31); /* Number of parms scanned */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/ CNMSSCAN DATA(CMDBUF) /* Scan the input command... */ FORMAT(’%*S%S’) /* ...skip the command */ COUNT(PARMCNT) /* ...number of parms */ P1(TARGTASK); /* ...target task */ IF PARMCNT=1 THEN /* Was the target task entered? */ DO; /* Syntax ok... */ TARGTASKF=TARGTASK; /* Put into fixed length string */ CNMSENDMSG DATA(’PSNDDAT’) /* Invoke PSNDDAT command */ MSGTYPE(’REQUEST’) /* ...type is request */ DESTTYPE(’TASK’) /* ...on a task */ DEST(TARGTASKF); /* ...specified by input */

CNMCOMMAND DATA(’WAIT 120 SECONDS FOR DATA’);

IF HLBRC ¬= CNM_DATA_ON_WAIT THEN /* Wait successful ? */ CNMSENDMSG /* No... */ DATA(’Wait for data abnormally ended’) /*...text */ MSGTYPE(’MSG’) /* ...message */ DESTTYPE(’OPER’); /* ...to the operator */ ELSE /* Wait was successful */ DO; /* Process the results */ CNMGETDATA FUNC(’GETMSG’) /* Read in the response... */ QUEUE(DATAQ) /* ...on the data queue */ DATA(NEWMSG) /* ...read into NEWMSG variable */ LENG(256) /* ...give plenty of room */ ORIGIN(GETBLOCK); /* ...provide a different org blk*/ /* REMOVE PROCESS ID FROM THE BUFFER !!!! */ /* First 8 bytes must be removed */ NEWMSG = SUBSTR(NEWMSG,9); CNMSENDMSG /* Inform user... */ DATA(NEWMSG) /* ...message is in NEWMSG */ MSGTYPE(’MSG’) /* ...message */ DESTTYPE(’OPER’); /* ...to the operator */ END; /* of process the results */ END; /* of Syntax ok */ ELSE /* Target task not entered... */ CNMSENDMSG /* Inform user... */ DATA(’Target task required’) /* ...Syntax error */ MSGTYPE(’MSG’) /* ...message */ DESTTYPE(’OPER’); /* ...to the operator */ Sending data (PL/I) The purpose of the code in “Sending data (PL/I)” is to find the last time that a command was entered on the given task. A task global variable, LAST_COMMAND_TIME, is set by DSIEX03. See “Coding an installation exit” on page 86.

This value is retrieved by the PSNDDAT command that is started by the PWATDAT command on the target task. See “Coding the WAIT FOR DATA function” on page 87. This command processor is run when the PSNDDAT command is started at the requesting OST. Sending data (PL/I) /********************************************************************/ /* */ /* Other Declarations */ /* */

Chapter 7. PL/I high-level language services 89 PL/I High-Level Language Services

/********************************************************************/ DCL TIME CHAR(256) VAR; /* Time the last command was ...entered */ DCL MYOPID CHAR(8) VAR; /* Operator ID that we are running ...under */ /********************************************************************/ /* */ /* Execution */ /* */ /********************************************************************/

CNMINFOC /* Determine my opid... */ ITEM(’OPID’) /* ...variable is opid */ DATA(MYOPID) /* ...put result here */ LENG(8); /* ...truncate after 8 bytes */ IF MYOPID=ORIGIN->ORIG_BLOCK.ORIG_TASK THEN /* Command issued ...... directly or target task ...was same as operators task */ CNMSENDMSG /* Not allowed... */ DATA(’Invalid syntax’) /*...text of message */ MSGTYPE(’MSG’) /* ...message is a single line */ DESTTYPE(’OPER’); /* ...to a operator */ ELSE DO; CNMVARPOOL /* Retrieve last time variable */ FUNC(GET) /* ...read in the value */ NAME(’LAST_COMMAND_TIME’) /* ...of the variable */ POOL(’TGLOBAL’) /* ...in the task global pool */ DATA(TIME) /* ...into time */ LENG(256); /* ...truncate at 256 */ IF (HLBRC=CNM_GOOD) THEN /* Variable set? */ CNMSENDMSG /* Yes, continue... */ DATA(ORIGIN->ORIG_PROCESS ||/* ...must put the process ID in */ ’Last command entered at : "’|| /* ...text of message */ TIME||’"’) /* ... more text */ MSGTYPE(’DATA’) /* ...message is data */ DESTTYPE(’TASK’) /* ...to a task */ DEST(ORIGIN->ORIG_TASK); /* ...that invoked us */ ELSE CNMSENDMSG /* No, inform user... */ DATA(ORIGIN->ORIG_PROCESS || /* ...must put in process ID */ ’Must install DSIEX03 to set TIME variable OR no ’|| ’command entered yet on that task’) MSGTYPE(’DATA’) /* ...message is data */ DESTTYPE(’TASK’) /* ...to a task */ DEST(ORIGIN->ORIG_TASK); /* ...that invoked us */ END;

Automating MSUs “Automating MSUs (PL/I)” shows a routine to send an MSU directly to the automation table for evaluation. Automating MSUs (PL/I) /********************************************************************/ /* Other declarations */ /********************************************************************/ DCL MSGTOOP CHAR(80) VARYING; /* Message buffer */ DCL NMVT CHAR(200) VARYING; /* Variable that contains the RU */ DCL ORIGIN PTR;

/********************************************************************/ /* Initialization */ /********************************************************************/ ORIGIN=ADDR(ORIGBLCK); /* Address of the Origin Block */

90 Programming: PL/I and C PL/I High-Level Language Services

NMVT = ’008E41038D0000000010’X|| ’00860000’X|| ’1A00D5C5E3E5C9C5E640’X|| ’C1E4E3D6D4C1E3C5E240’X|| ’C1D3C5D9E3E2’X|| ’0893000110213111’X|| ’0B92800001B0048CD5AA63’X|| ’180516100807C940D3D6E5C5FF00’X|| ’08D5C5E3E5C9C5E6FF11’X|| ’1E96060122E233D30384DD0382AA’X|| ’0382BB0382CC0382DD048144A3038333’X|| ’219808010000000431820382AA’X|| ’0382BB0382CC08010000000237450382DD0382EE’X; /********************************************************************/ /* Drive the Automation Table with the MSU. */ /********************************************************************/ CALL CNMAUTO(HLBPTR,NMVT); MSGTOOP = ’THE RC FROM THE PL/I CNMAUTO CALL = ’ || HLBRC; /********************************************************************/ /* Respond to the operator with the return code from CNMAUTO */ /********************************************************************/ CNMSENDMSG DATA(MSGTOOP) MSGTYPE(’MSG’) DESTTYPE(’OPER ’);

HLBRC = CNM_GOOD; /* Successful completion */

Translating code points “Translating code points (PL/I)” shows how to translate a numeric code point value into its corresponding EBCDIC text. Translating code points (PL/I) /************************************************************/ /* */ /* Other Declarations */ /* */ /************************************************************/

DCL CPDATA CHAR(80) VARYING; DCL DATLEN FIXED BIN(31) INIT(80); DCL CODE FIXED BIN(31);

/************************************************************/ /* Scan the input for the Code Point to translate */ /************************************************************/

CALL CNMSCAN (HLBPTR, CMDBUF, ’%*S%D’, CODE);

/************************************************************/ /* Invoke Code Point Translation */ /************************************************************/

CALL CNMC2T(HLBPTR, CPDATA, DATLEN, ’SNAALERT’, CODE);

Chapter 7. PL/I high-level language services 91 PL/I High-Level Language Services

Registering applications with MS transport and operations management “Registering applications with MS transport and operations management (PL/I) ” shows a routine to register an application with both the MS transport and the operations management application. Registering applications with MS transport and operations management (PL/I) /******************************************************************/ /* Declare variables for the program. */ /******************************************************************/

DCL MSGTOOP CHAR(80) VARYING; /* CNMSENDMSG buffer */ DCL CMD_RETCODE FIXED BINARY(31,0); /* Return code */ DCL ANAME CHAR(8) VARYING; /* appl name entered */ DCL CNAME CHAR(8) VARYING; /* command name entered */ DCL FPCATE CHAR(8) VARYING; /* focal pt category entered */ DCL REPL CHAR(8) VARYING; /* replace value entered */ DCL RTYPE CHAR(8) VARYING; /* registration type entered */ DCL FP CHAR(8) VARYING; /* focal point value entered */ DCL NOTIFY CHAR(8) VARYING; /* notify value entered */ DCL APPLNAME CHAR(8); /* appl name used in CNMRGS */ DCL CMDNAME CHAR(8); /* command name used in CNMRGS*/ DCL FPCATVAL CHAR(8); /* focpt category used in RGS */ DCL REPLACE CHAR(8); /*replace value used in CNMRGS*/ DCL FOCPT CHAR(8); /* focal pt value used in RGS */ DCL NOTI_VAL CHAR(8); /* notify value used in CNMRGS*/ DCL REGTYPE CHAR(8); /* registration type */ DCL TOKENS FIXED BINARY(31,0); /* no of input entered */

/******************************************************************/ /* Initialization */ /******************************************************************/

APPLNAME = ’ ’; CMDNAME = ’ ’; FPCATVAL = ’ ’; REPLACE = ’ ’; REGTYPE = ’BOTH ’; FOCPT = ’NO ’; /******************************************************************/ /* Scan input command buffer and get all parameters. */ /******************************************************************/ CNMSSCAN DATA(CMDBUF) FORMAT(’%*S’ || ’%S’ || ’%S’ || ’%S’ || ’%S’ || ’%S’ || ’%S’ || ’%S’) COUNT(TOKENS) P1 (ANAME) /* Parse out the appl name */ P2 (CNAME) /* Parse out the command name */ P3 (FPCATE) /* Parse out the FP category */

92 Programming: PL/I and C PL/I High-Level Language Services

P4 (FP ) /* Parse out the Focal Pt value */ P5 (REPL) /* Parse out the REPLACE value */ P6 (NOTIFY) /* Parse out the NOTIFY value */ P7 (RTYPE ); /* Parse out the Reg. type */ /******************************************************************/ /* Make sure application name and command name are given */ /******************************************************************/

IF TOKENS < 2 THEN DO; MSGTOOP = ’APPLICATION NAME AND COMMAND NAME ARE REQUIRED’; CNMSENDMSG DATA (MSGTOOP) MSGTYPE (’MSG ’) DESTTYPE(’OPER ’); HLBRC = CNM_BAD_INVOCATION; /* registration not done */ END;

/******************************************************************/ /* Save parsed value and invoke CNMREGIST service */ /******************************************************************/ ELSE DO; APPLNAME = ANAME; /* save appl name */ CMDNAME = CNAME; /* save command name */ IF LENGTH(FPCATE) > 0 & SUBSTR(FPCATE, 1, 1) ¬= ’.’ THEN FPCATVAL = FPCATE; /* save FP category if entered */ IF LENGTH(FP) > 0 & SUBSTR(1, 1) ¬= ’.’ THEN FOCPT = FP; /* save focal pt value if enter */ IF LENGTH(REPL) > 0 & SUBSTR(REPL,1, 1) ¬= ’.’ THEN REPLACE = REPL; /* save replace value if entered*/ IF LENGTH(NOTIFY) > 0 & SUBSTR(NOTIFY, 1, 1) ¬= ’.’ THEN NOTI_VAL = NOTIFY; /* save notify value if entered */ IF LENGTH(RTYPE) > 0 & SUBSTR(RTYPE, 1, 1) ¬= ’.’ THEN REGTYPE = RTYPE; /* save reg type if entered */ /******************************************************************/ /* Need to register MS appl */ /******************************************************************/ IF (REGTYPE = ’BOTH ’) | (REGTYPE = ’MSAPPL ’) THEN DO; CNMREGIST TYPE (REGMSAPPL) APPL (APPLNAME ) COMMAND (CMDNAME) FPCATEGORY(FPCATVAL) FOCALPOINT(FOCPT) REPLACE (REPLACE) NOTIFY (NOTI_VAL); CMD_RETCODE = HLBRC; MSGTOOP = APPLNAME || ’ IS REGISTERED AS MS APPL, RETURN CODE IS ’ || CHAR(CMD_RETCODE); CNMSENDMSG DATA (MSGTOOP) MSGTYPE (’MSG ’) DESTTYPE(’OPER ’); END; /******************************************************************/ /* Need to register Ops. Mgmt. served appl */ /******************************************************************/ IF (REGTYPE = ’BOTH ’) | (REGTYPE = ’OMAPPL ’) THEN DO; CNMREGIST TYPE (REGOMSERVD) APPL (APPLNAME ) COMMAND (CMDNAME) FOCALPOINT(FOCPT) FPCATEGORY(FPCATVAL) REPLACE (REPLACE) NOTIFY (NOTI_VAL); CMD_RETCODE = HLBRC;

Chapter 7. PL/I high-level language services 93 PL/I High-Level Language Services

MSGTOOP = APPLNAME || ’ IS REGISTERED AS OPS ’ || ’MGMT SERVED APPL, RETURN CODE IS ’ || CHAR(CMD_RETCODE); CNMSENDMSG DATA (MSGTOOP) MSGTYPE (’MSG ’) DESTTYPE(’OPER ’); END; HLBRC = CNM_GOOD; /* Successful completion */ END;

Registering applications with the high-performance transport “Registering applications with the high-performance transport (PL/I)” shows how to register an application with the high-performance transport. Registering applications with the high-performance transport (PL/I) /******************************************************************/ /* Declare variables for the program. */ /******************************************************************/ DCL MSGTOOP CHAR(80) VARYING; /* CNMSENDMSG buffer */ DCL CMD_RETCODE FIXED BINARY(31,0); /* Return code */ DCL ANAME CHAR(8) VARYING; /* appl name entered */ DCL CNAME CHAR(8) VARYING; /* command name entered */ DCL LGMOD CHAR(8) VARYING; /* logmode entered */ DCL REPL CHAR(8) VARYING; /* replace value entered */ DCL RTYPE CHAR(8) VARYING; /* registration type entered */ DCL APPLNAME CHAR(8); /* appl name used */ DCL CMDNAME CHAR(8); /* command name used */ DCL LOGMOD CHAR(8); /* focpt category used */ DCL REPLACE CHAR(8); /*replace value used */ DCL REGTYPE CHAR(8); /* registration type used */ DCL TOKENS FIXED BINARY(31,0); /* no of input entered */ /******************************************************************/ /* Misc. declares - BUILT-IN functions, labels, etc. */ /******************************************************************/ DCL CHAR BUILTIN; /* Binary to char. function */ DCL LENGTH BUILTIN; DCL SUBSTR BUILTIN; /******************************************************************/ /* Initialization */ /******************************************************************/ APPLNAME = ’ ’; CMDNAME = ’ ’; LOGMOD = ’ ’; REPLACE = ’ ’; REGTYPE = ’REGAPPL ’; /******************************************************************/ /* Scan input command buffer and get all parameters. */ /******************************************************************/ CNMSSCAN DATA(CMDBUF) FORMAT(’%*S’ || ’%S’ || ’%S’ || ’%S’ || ’%S’ || ’%S’) COUNT(TOKENS) P1 (ANAME) /* Parse out the appl name */ P2 (CNAME) /* Parse out the command name */ P3 (LNAME) /* Parse out the Logmode */ P4 (REPL) /* Parse out the REPLACE value */ P5 (RTYPE ); /* Parse out the Reg. type */ /******************************************************************/ /* Make sure application name and command name are given */

94 Programming: PL/I and C PL/I High-Level Language Services

/******************************************************************/ IF TOKENS < 2 THEN DO; MSGTOOP = ’APPLICATION NAME AND COMMAND NAME ARE REQUIRED’; CNMSENDMSG DATA (MSGTOOP) MSGTYPE (’MSG ’) DESTTYPE(’OPER ’); HLBRC = CNM_BAD_INVOCATION; /* registration not done */ END; /******************************************************************/ /* Save parsed value and invoke CNMHRGS service */ /******************************************************************/ ELSE DO; APPLNAME = ANAME; /* save appl name */ CMDNAME = CNAME; /* save command name */ IF (LENGTH(LNAME) > 0 & SUBSTR(LNAME, 1, 1) ¬= ’.’) THEN LOGMOD = LNAME; /* save Logmode if entered */ IF (LENGTH(REPL) > 0 & SUBSTR(REPL,1, 1) ¬= ’.’) THEN REPLACE = REPL; /* save replace value if entered*/ IF (LENGTH(RTYPE) > 0 & SUBSTR(RTYPE, 1, 1) ¬= ’.’) THEN REGTYPE = RTYPE; /* save reg type if entered */ /******************************************************************/ /* Need to register an appl */ /******************************************************************/ IF (REGTYPE = ’REGAPPL ’) THEN DO; CNMHRGS TYPE (REGAPPL) APPL (APPLNAME ) COMMAND (CMDNAME) LOGMODE (LOGMOD) REPLACE (REPLACE) CMD_RETCODE = HLBRC; MSGTOOP = APPLNAME || ’ IS REGISTERED AS AN APPL, RETURN CODE IS ’ || CHAR(CMD_RETCODE); CNMSENDMSG DATA (MSGTOOP) MSGTYPE (’MSG ’) DESTTYPE(’OPER ’); END; HLBRC = CNM_GOOD; /* Successful completion */ END;

Sending an alert over the MS transport “Sending an alert over the MS transport (PL/I)” shows how to send a software alert over the MS transport. Sending an alert over the MS transport (PL/I) /******************************************************************/ /* Declare variables for the program. */ /******************************************************************/

DCL CMD_RETCODE FIXED BIN(31,0); /* return code from CNMSENDMU */ DCL MSGTOOP CHAR(80) VARYING; /* CNMSENDMSG buffer */ DCL ALERT_MSU CHAR(256) VARYING; /* alert to be sent */ DCL CORR_AREA CHAR(53) VARYING; /* area for correlator retn */ DCL OAPPL CHAR(8); /* origin appl - USERAPPL */ DCL DNET CHAR(8); /* dest net - NETA */ DCL DLU CHAR(8); /* dest LU - CNM01 */ DCL ALERT_NETOP CHAR(8); /* dest appl - ALERT_NETOP */

Chapter 7. PL/I high-level language services 95 PL/I High-Level Language Services

/******************************************************************/ /* Misc. declares - BUILT-IN functions, labels, etc. */ /******************************************************************/ DCL CHAR BUILTIN; /* Binary to char. function */ DCL LENGTH BUILTIN; DCL SUBSTR BUILTIN; /******************************************************************/ /* Initialization */ /******************************************************************/

CNMSENDMU DATATYPE (NONMDSMU) DATA (ALERT_MSU) CORRELAREA (CORR_AREA) ORIGAPPL (OAPPL) DESTNET (DNET) DESTLU (DLU) DESTAPPL (ALERT_NETOP) MUTYPE (REQUEST_WITHOUT_REPLY); CMD_RETCODE = HLBRC; MSGTOOP = ’RETURN CODE FROM CNMSENDMU IS ’ || CHAR(CMD_RETCODE); CNMSENDMSG DATA (MSGTOOP) MSGTYPE (’MSG ’) DESTTYPE(’OPER ’); HLBRC = CNM_GOOD; /* Successful completion*/

Sending an alert over the high-performance transport “Sending an alert over the high-performance transport (PL/I)” shows how to send a software alert over the high-performance transport. Sending an alert over the high-performance transport (PL/I) /********************************************************************/ /* NetView High-Level Language include files */ /********************************************************************/ %INCLUDE DSIPLI; /* Include the HLL macros */ /********************************************************************/ /* Parameter declarations */ /********************************************************************/ DCL HLBPTR PTR; /* Pointer to the HLB */ DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ DCL ORIGBLCK CHAR(40); /* Area for the Origin Block */

/******************************************************************/ /* Declare variables for the program. */ /******************************************************************/

96 Programming: PL/I and C PL/I High-Level Language Services

DCL DLU CHAR(8); /* dest LU - CNM01 */ DCL RMT_CMD CHAR(8); /* dest appl - RMT_CMD */ /******************************************************************/ /* Misc. declares - BUILT-IN functions, labels, etc. */ /******************************************************************/ DCL CHAR BUILTIN; /* Binary to char. function */ DCL LENGTH BUILTIN; DCL SUBSTR BUILTIN; /******************************************************************/ /* Initialization */ /******************************************************************/

ALERT_MSU = ’0046121200420000’X || ’0B92000001210100000001’X || ’1010000D110E0A0040F1F2F3F4F54040’X || ’1103030109D5C1D4C5F1404040E3E8D7F1’X || ’069310011023’X || ’0C9606011022102304813110’X; OAPPL = ’USERAPPL’; DNET = ’NETA ’; DLU = ’CNM01 ’; RMT_CMD = ’30F0F5F540404040’X; CNMHSMU DATATYPE (NONMDSMU) DATA (ALERT_MSU) CORRELAREA (CORR_AREA) ORIGAPPL (OAPPL) DESTNET (DNET) DESTLU (DLU) DESTAPPL (RMT_CMD) MUTYPE (REQUEST_WITHOUT_REPLY); CMD_RETCODE = HLBRC; MSGTOOP = ’RETURN CODE FROM CNMHSMU IS’ || CHAR(CMD_RETCODE); CNMSENDMSG DATA (MSGTOOP) MSGTYPE (’MSG ’) DESTTYPE(’OPER ’); HLBRC = CNM_GOOD; /* Successful completion */

END PHSNDMU;

Sending an MDB to NetView for processing “Sending an MDB to NetView for processing (PL/I)” shows how to send a message data block (MDB) to NetView for processing. Sending an MDB to NetView for processing (PL/I) /********************************************************************/ /* NetView High-Level Language include files */ /********************************************************************/ %INCLUDE DSIPLI; /* Include the HLL macros */ /********************************************************************/ /* Parameter declarations */ /********************************************************************/ DCL HLBPTR PTR; /* Pointer to the HLB */ DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ DCL ORIGBLCK CHAR(40); /* Area for the Origin Block */

/********************************************************************/ /* Other declarations */ /********************************************************************/ DCL MDBPTR PTR; DCL SOPTR PTR; DCL MYCORR CHAR(16); DCL MYMDB CHAR(300); DCL MYSRC CHAR(50);

Chapter 7. PL/I high-level language services 97 PL/I High-Level Language Services

DCL INFOMSG CHAR(120) VARYING; /********************************************************************/ /* Create the MDB */ /********************************************************************/ MYMDB = ’0112’X|| /* Length of whole MDB */ ’0001’X|| /* MDB Type 1 */ ’D4C7D640’X|| /* MDB Acronym */ ’00000001’X|| /* Revision code */ ’0038’X|| /* General Object length */ ’0001’X|| /* General Object type */ ’00000000’X|| /* MDBGMID (message id) */ ’C8C84BD4D44BE2E2’X|| /* Time stamp HH.MM.SS */ ’4BE3C8’X|| /* Time stamp .TH */ ’00’X|| /* Reserved */ ’E8E8E8E8C4C4C4’X|| /* Date stamp YYYYDDD */ ’00’X|| /* Reserved */ ’0000’X|| /* MDBGMFLG (message flags) */ ’0000’X|| /* Reserved */ ’00000000’X|| /* Foreground presentation attr */ ’00000000’X|| /* Background presentation attr */ ’D6D9C9C7E2D5C1D4’X|| /* Originating system name */ ’D1D6C240D5C1D4C5’X|| /* Job name */ ’0082’X|| /* Control program object length*/ ’0002’X|| /* Control program object type */ ’00000001’X|| /* Object version level */ ’D4E5E240’X|| /* Control program name */ ’C6D4C9C4C6D4C9C4’X|| /* FMID of originating system */ ’00000000000000000000000000000000’X|| /* 128 Routing codes */ ’0000’X|| /* Descriptor codes */ ’0000’X|| /* Message level */ ’0000’X|| /* Message attribute flags */ ’0000’X|| /* Message priority */ ’0000’X|| /* Reserved */ ’0012’X|| /* ASID of issuer */ ’00000000’X|| /* JOB Step TCB for issuer */ ’00000000’X|| /* Token for DOM */ ’00’X|| /* System id for DOM */ ’00’X|| /* DOM flags */ ’00’X|| /* Misc routing information */ ’00’X|| /* Reserved */ ’0000000000000000’X|| /* Originating Job ID */ ’0000000000000000’X|| /* Retrieval KEY */ ’0000000000000000’X|| /* Automation Token */ ’0000000000000000’X|| /* Command and Response Token */ ’00000000’X|| /* Console */ ’0000’X|| /* Message type flags */ ’0077’X|| /* Reply ID length */ ’0000000000000000’X|| /* Reply ID (EBCDIC) */ ’0000’X|| /* Reserved */ ’0000’X|| /* Offset to beginning of msg */ ’00000000’X|| /* Reply ID (binary) */ ’00’X|| /* Areaid */ ’00’X|| /* Reserved */ ’00000001’X|| /* Number of lines in message */ ’0000000000000000’X|| /* Originating Job name */ ’004C’X|| /* Text object length */ ’0004’X|| /* Text object type */ ’0000’X|| /* Line type flags */ ’00000000’X|| /* Presentation attributes */ ’78E3C8C9E240’X|| /* Text of message: "THIS " */ ’D4C5E2E2C1C7C540’X|| /* "MESSAGE " */ ’E6C1E240E2C5D5E340’X|| /* "WAS SENT " */ ’C6D9D6D440D7D361C940’X|| /* "FROM PL/I " */ ’E4E2C9D5C740E3C8C540’X|| /* "USING THE " */ ’D5C5E3E5C9C5E640’X|| /* "NETVIEW " */ ’C3D5D4D7D4C4C240’X|| /* "CNMPMDB " */ ’E2C5D9E5C9C3C5’X; /* "SERVICE " */

98 Programming: PL/I and C PL/I High-Level Language Services

/********************************************************************/ /* Create the Source Object */ /********************************************************************/ MYSRC = ’000B’X|| /* Source object length */ ’0005’X|| /* Source object type */ ’07D5D4E8E2E8E2’X; /* Nickname "MYSYS" */ /********************************************************************/ /* Initialize the Correlator value */ /********************************************************************/ MYCORR = ’00000000000000000000000000000000’X; /********************************************************************/ /* Set up pointers to MDB and Source Object */ /********************************************************************/ MDBPTR = ADDR(MYMDB); SOPTR = ADDR(MYSRC);

/********************************************************************/ /* Call CNMPMDB service to process the MDB */ /********************************************************************/ CALL CNMPMDB(HLBPTR,MDBPTR,SOPTR,MYCORR); /********************************************************************/ /* Send message to issuer with return code from CNMPMDB */ /********************************************************************/ INFOMSG = ’RETURN CODE FROM CNMPMDB: ’ || HLBPTR->HLBRC; CALL CNMSMSG(HLBPTR,INFOMSG,’MSG’,’OPER’,’’);

HLBPTR->HLBRC = CNM_GOOD; /* Successful completion */

END PPRSMDB;

Chapter 7. PL/I high-level language services 99 PL/I High-Level Language Services

100 Programming: PL/I and C Part 4. Writing a C program

This chapter describes how to write high-level language (HLL) command processors and installation exits in the C language. This chapter also describes the appropriate interfaces and language-dependent restrictions.

Initial parameters Every HLL program written in C must have exactly one function (main) that declares the argc and argv parameters. The first parameter, argc, is an integer value that indicates the number of pointers in the argv array. NetView does not use the argc parameter. The argv parameter is an array of pointers. In the regular C environment, each element in argv points to an argument in the command line. In the NetView environment, elements 1-3 point to the EBCDIC representation of the initial parameters (Hlbptr, Cmdbuf and Origblck) passed to the main function from the NetView program. The initial parameters must be converted to hexadecimal using sscanf. The original command line is passed to the user’s program in Cmdbuf. Chapter 9, “C high-level language services,” on page 117 contains a sample template for coding the main function and defining and converting the initial parameters. The following are descriptions of the initial parameters: Cmdbuf A varying length character field that contains the command or message that drives this program. If this program is driven as an installation exit (other than DSIEX02A), this field contains the message that drives this exit. If driven as DSIEX02A, this field contains no useful information, and you must retrieve the message from the initial data queue (IDATAQ). Hlbptr A 4-byte pointer field containing the address of the HLB control block (DSICHLB). The HLB control block is the HLL API interface block that is used to communicate between the HLL service routines and HLL programs in the NetView environment. This pointer is required on all HLL service routine invocations. The HLB control block is unique for each invocation of an HLL program. NetView automatically inserts HLBPTR for the C invocation format. Origblck A 40-byte structure that describes the origin of the request that caused the execution of this program. Origblck is mapped by DSICORIG.

C runtime options The method you use to specify z/OS XL C/C++ runtime options depends on the type of z/OS XL C/C++ support you use for your programs. The way you specify C runtime options, therefore, depends on the following: v Compiler (z/OS C/C++) v Libraries (language environment) v Preinitialization Support (Enabled or Disabled)

In addition, consider information about: v Running Non-Preinitialized, either intentionally or because of availability

v Type of runtime option, whether the option is for a general option or a storage option.

Use Table 16 as a starting point to familiarize yourself with the specific methods of specifying the runtime options for your program. The table indicates the methods to use based on the interface module that is being link-edited with a program. Following the table, each method for specifying runtime options is described in more detail.

Tip: Runtime options can also be specified by the CEEPRMxx member of PARMLIB. Table 16. Interface Modules and How to Specify z/OS XL C/C++ Runtime Options Interface Module Library and Program Type General Runtime Options Storage Options DSIEXANC z/OS Language Environment v #pragma runopts v #pragma runopts non-preinitialized DSIEXAPC z/OS Language Environment v z/OS Language Environment v PSTACK, PHEAP non-preinitialized preinitialized defaults v LEOPTS static v LEOPTS static external variable external variable DSIEXAPC z/OS Language Environment v z/OS Language Environment v PSTACK, PHEAP preinitialization-enabled preinitialized defaults

#pragma runopts Runtime options can be specified with #pragma runopts preprocessor directive for z/OS XL C/C++ compilers.

For example, for z/OS XL C/C++, include the following statements: #pragma runopts( STACK(128K,128K,ANY,FREE) HEAP(128K,128K,ANY,FREE,8,0) ) #pragma runopts( BELOWHEAP(8,0,FREE) LIBSTACK(8,0,FREE) ) #pragma runopts( INTERRUPT(OFF) NOTEST(ALL,*,* ) STORAGE(,,,0) ) #pragma runopts( TRAP(OFF) MSGQ(1) ALL31(ON) )

The runtime options for executing z/OS XL C/C++ programs in the NetView environment are illustrated in the C language coding template in Chapter 9, “C high-level language services,” on page 117.

The z/OS XL C/C++ programs must run with the TRAP(OFF) option. Running with the TRAP(ON) option causes unpredictable results if error recovery is necessary.

To achieve optimum performance, use the REPORT or RPTSTG option until accurate STACK and HEAP sizes are determined.

Refer to the runtime storage section in the z/OS library for more information. z/OS Language Environment preinitialization defaults The following C runtime options are automatically set for programs that request to run in a preinitialized environment. Except for the STACK and HEAP values, you cannot change the values. Values for pstack and pheap are taken from the values specified for PSTACK and PHEAP on the HLLENV command. v STACK(pstack,128K,ANY,FREE) v BELOWHEAP(8,0,FREE) v HEAP(pheap,128K,ANY,FREE,8,0)

104 Programming: PL/I and C C Code Interfaces and Restrictions

v LIBSTACK(8,0,FREE) v THREADHEAP(8,0,ANY,FREE) v STORAGE(,,,0) v ALL31(ON) v TRAP(OFF) v INTERRUPT(OFF) v NOTEST(ALL,*,*) v MSGQ(1)

Refer to the z/OS Language Environment library for more information about these options. PSTACK and PHEAP STACK and HEAP storage values are set using the PSTACK and PHEAP keywords of the HLLENV command. The initial values for PSTACK and PHEAP are both 131072 bytes. These values can be changed dynamically with the HLLENV command.

Example of Overriding PSTACK and PHEAP Values: The following example shows how to override the initial values for PSTACK and PHEAP for a program that requests to run in a preinitialized environment: HLLENV CHANGE,PSTACK=262144,PHEAP=524288,TYPE=IBMADC LEOPTS static external variable When your program uses the DSIEXAPC interface module and explicitly forces non-preinitialization through the combination of the HLLENV DEFAULT value and the HLLOPTS bits, you can specify the runtime options using the LEOPTS static external variable.

When you define LEOPTS in your program, the runtime options specified are used instead of the defaults described in “z/OS Language Environment preinitialization defaults” on page 104 and “PSTACK and PHEAP.”

Example of Specifying LEOPTS Values: You can override the default z/OS Language Environment preinitialization, PSTACK, and PHEAP runtime options in a z/OS XL C/C++ program as shown in the following LEOPTS declaration. #pragma variable(LEOPTS,NORENT) extern char LEOPTS??(255??) = "STACK(256K,256K,ANY,FREE) HEAP(256K,256K,ANY,FREE,8,0) TRAP(OFF) MSGQ(1)" " BELOWHEAP(8,0,FREE) LIBSTACK(8,0,FREE) THREADHEAP(8,0,ANY,FREE)" " INTERRUPT(OFF) NOTEST(ALL,*,* ) STORAGE(,,,0) ALL31(ON)" " PLITASKCOUNT(1)";

Parameters passed to HLL service routines Four types of parameters can be passed to HLL service routines. Each of the parameters, described throughout Chapter 11, “Service reference,” on page 173, falls into one of these categories: v Pointer variables v Integer variables v Fixed-length character strings v Varying length character strings

Chapter 8. Coding your C program interfaces and restrictions 105 C Code Interfaces and Restrictions

A description of each of these parameter types follows. The sections describe how you can declare, initialize, and pass each of these parameter types to the HLL service routines. This chapter also provides examples for writing HLL programs in C. These examples are not complete, they are included to emphasize how you might declare, initialize, and pass service routine parameters. For complete examples of user-written HLL programs, refer to the HLL samples shipped with NetView, or see Appendix D, “C samples,” on page 281. Pointer variables A pointer variable is a 4-byte pointer field containing an address. All HLL service routines require one pointer variable called Hlbptr. NetView calculates the value of Hlbptr and passes it to the HLL command processor or installation exit. When Hlbptr is received as an initial parameter, do not assign a value to Hlbptr. This is the only parameter of this type that you do not have to assign.

Note: You do not need to specify the Hlbptr parameter when coding HLL service routine invocations in C. Hlbptr is inserted for you before the HLL service routine is started.

If an HLL service routine is expecting an address in a pointer field, you are responsible for assigning a value to that pointer field before starting the HLL service routine. For C, use the & (address) operator when passing pointer variables to HLL service routines rather than creating a separate pointer variable for this purpose. This ensures that the pointer variable is assigned a value before starting the HLL service routine.

“Using Pointer Variables in C” shows an example of using pointer variables in C. Some of the steps are explained in more detail following the figure. Using Pointer Variables in C ▌1▐ #define VARTOVAR "VARTOVAR" /* VARTOVAR constant */ ▌2▐ Dsihlb *Hlbptr; /* HLB pointer MUST BE DEFINED */ ▌3▐ Dsivarch *srcptr; /* Pointer to source buffer */ Dsivarch *dstptr; /* Pointer to destination buffer */

int dstlen; /* Length of destination buffer */

Dsivarch srcbuf; /* Source buffer */ Dsivarch dstbuf; /* Destination buffer */

▌4▐ srcptr = &srcbuf; /* Address of source buffer */ dstptr = &dstbuf; /* Address of destination buffer */

dstlen = 255;

▌5▐ Cnmcpys(srcptr,dstptr,dstlen,VARTOVAR); /* Copy buffer */

The descriptions for the steps shown in “Using Pointer Variables in C” are: ▌2▐ Hlbptr is defined as a pointer variable. You must not assign a value to Hlbptror include it in the Cnmcpys invocation. NetView inserts Hlbptr in the parameter list for you during the compilation's preprocessor phase. ▌3▐ srcptr is defined as a pointer to a structure of type Dsivarch (varying length character string). ▌4▐ srcptr is assigned the address of the source buffer (srcbuf) to be used as a operand to Cnmcpys ▌5▐ srcptr is passed as a parameter to Cnmcpys.

106 Programming: PL/I and C C Code Interfaces and Restrictions

Using the & (address) operator in C eliminates the need to define pointer variables. Note the use of a string constant instead of the VARTOVAR constant in this example: Cnmcpys(&srcbuf,&dstbuf,dstlen,"VARTOVAR"); /* Copy buffer */ Integer variables Several of the HLL service routines require the user to pass a 4-byte integer value to be used as a length, count, queue number, and so on. “Using Integer variables in C” illustrates the use of integer variables in the HLL environment. Some of the steps are explained in more detail following the figure. Using Integer variables in C struct Vchar12 { short int size; /* Size of buffer */ char buffer [13]; /* Text buffer */ };

Dsihlb *Hlbptr /* HLB pointer MUST BE DEFINED */ Vchar12 spname; /* Subpool name */ ▌1▐ char spfunc[9]; /* Subpool function ▌2▐ int sptoken; /* Subpool token (returned) */ ▌3▐ int spleng; /* Cell size */ int sppricnt; /* Number of cells in primary */ int spseccnt; /* Number of cells in secondary */ int spclass; /* Class of storage */

▌4▐ spfunc = "ALLOC "; /* Function is ALLOCATE */ Cnmvlc(&spname,NOHEXCNV,"POOLNAME"); /* Initialize subpool name */ ▌5▐ sptoken = 0; /* Initialize subpool token */ ▌6▐ spleng = 256; /* Cell size = 256 bytes */ sppricnt = 3; /* Primary count = 3 */ spseccnt = 2; /* Secondary count = 2 */ spclass = 1; /* Class = 31 bit addressable */

▌7▐Cnmpool(spfunc,&sptoken,&spname,spleng,sppricnt,spseccnt, spclass); /* Allocate Subpool */

The descriptions for the steps shown in “Using Integer variables in C” are: ▌2▐ sptoken is defined as a 4-byte integer (int). ▌3▐ spleng is defined as a 4-byte integer (int). ▌5▐ sptoken is initialized to 0. A value is returned in sptoken upon successful completion of the Cnmpool invocation. ▌6▐ spleng is assigned a value of 256 to be used in the call to Cnmpool ▌7▐ Cnmpool is started using &sptoken and spleng as operands. The value of sptoken is returned to the user upon successful completion of the Cnmpool service.

Note: All of the integer variables are specified by name except for sptoken. sptoken is specified using the & (address) operator. In C, all operand fields that return values to the user’s program must specify a pointer to that operand field when starting an HLL service routine. Otherwise, you do not see the changes made to that variable upon successful completion of the HLL service routine. Using the & (address) operator ensures that the value is returned to the calling program. The & (address) operator is also used for spname. This is explained in detail in “Varying length character strings” on page 108.

Chapter 8. Coding your C program interfaces and restrictions 107 C Code Interfaces and Restrictions

Fixed-length character strings Most the HLL service routines require you to pass one or more fixed-length character strings as arguments.

C string constants for most of the fixed-length character strings are provided in DSICCONS. DSICCONS is optional and can be tailored to your specific needs. The following steps correlate to “Using Integer variables in C” on page 107. ▌1▐ spfunc is defined as a 9-byte character array (8 bytes + \0 null character). ▌4▐ spfunc is assigned a value of "ALLOC " to be used in the Cnmpool invocation. ▌7▐ Cnmpool is started using the spfunc parameter. spfunc can be assigned a value, defined with a preprocessor define statement (see VARTOVAR in “Using Pointer Variables in C” on page 106 step ▌1▐), or passed as a string constant as shown in the next example: Cnmpool("ALLOC ",&sptoken,&spname,spleng,sppricnt,spseccnt, spclass); /* Allocate Subpool */

C does not pad character strings with blanks. You must pad the fixed-length character strings with blanks, if necessary.

Also, all character strings must be delimited by the null character (\0) which is the end-of-string character in C. Enclosing text in double quotation marks ensures that the null character is appended to the last byte of the character string. As a result, when using a character array to represent a fixed-length character string, you must define the character array’s length to be one character greater than the length expected by the HLL service routine. Avoid using character arrays to represent fixed-length character strings whenever possible. You can use any of the alternative methods mentioned previously to ensure that the fixed-length character string is padded with blanks and delimited by the null character (\0). For further explanation, refer to the C documentation.

HLL service routines use two types of origin blocks. The first type of origin block (Origblck) is a 40-byte structure that you must declare. This is a required initial parameter that was previously described in “Initial parameters” on page 103. Do not alter this structure. See the C coding template in Chapter 9, “C high-level language services,” on page 117 for an example of how to define Origblck

The user specifies the second type of origin block (adorigin, gdorigin). The adorigin and gdorigin origin blocks must be at least 38 bytes long and must map to the first 38 bytes of the origin block structure (DSICORIG). You must define these origin blocks separately from the origin block that is required as an initial operand. Varying length character strings Several of the HLL service routines require you to pass a varying length character string as an argument. Varying length character strings are currently supported in the PL/I environment, but not in C. As a result, a structure must be defined as follows to map the internal representation of a varying length character string:

TEXT

►► LL TEXT ►◄

108 Programming: PL/I and C C Code Interfaces and Restrictions

Where: LL Is the 2-byte integer field containing the length of TEXT. TEXT Is the character string.

Dsivarch is an example of a structure that maps a varying length character string. The maximum size of the buffer portion of this particular structure is 256 bytes; 255 bytes (maximum) of text plus 1 byte for the end-of-string character (\0). Dsivarch is in DSICVARC and is included by DSIC. The structure consists of two parts: size A 2-byte (short) integer field that contains the size of the character array represented by buffer

Note: The end-of-string character (\0) is not included in this size but delimits the character array. buffer A 255-byte null-terminated character array, delimited by the end-of-string character (\0). A 256-byte field contains a 255-byte buffer plus a 1-byte end-of-string character.

You are responsible for creating structures like Dsivarch to represent varying length character strings passed to HLL service routines. You can use the size portion of the buffer to manipulate buffers that contain hexadecimal data. The presence of the null character at the end of the buffer enables you to use the buffer portion of the structure in other C functions that require the end-of-string character as a delimiter. You are responsible for ensuring that the end-of-string character delimits the buffer portion of the structure when necessary.

Note: HLL service routines that return data in varying length character strings do not delimit the data with the end-of-string character.

The NetView program provides two functions that let you manipulate varying length character strings in the C environment. Cnmvlc and Cnmnvlc calculate the value of the 2-byte size field and ensure that the buffer portion of the varying length character string is delimited by the end-of-string character (\0). Use these functions when initializing or altering the buffer portion of a varying length character string. If you alter the contents of a varying length character string without using Cnmvlc or Cnmnvlc, update the size field and ensure that the buffer is null-terminated.

Note: Cnmnvlc and Cnmvlc are specific to C support only.

“Using Varying Length Character Strings in C” shows how to use varying length character strings in C. Some steps are explained in more detail following the figure. Using Varying Length Character Strings in C struct Vchar12 { short int size; /* Size of buffer */ char buffer [13]; /* Text buffer */ };

Dsihlb *Hlbptr /* HLB pointer MUST BE DEFINED */ ▌1▐ Vchar12 spname; /* Subpool name */ char spfunc[9]; /* Subpool function int sptoken; /* Subpool token (returned) */ int spleng; /* Cell size */

Chapter 8. Coding your C program interfaces and restrictions 109 C Code Interfaces and Restrictions

int sppricnt; /* Number of cells in primary */ int spseccnt; /* Number of cells in secondary */ int spclass; /* Class of storage */

spfunc = "ALLOC "; /* Function is ALLOCATE */ ▌2▐ Cnmvlc(&spname,NOHEXCNV,"POOLNAME"); /* Initialize subpool name */ sptoken = 0; /* Initialize subpool token */ spleng = 256; /* Cell size = 256 bytes */ sppricnt = 3; /* Primary count = 3 */ spseccnt = 2; /* Secondary count = 2 */ spclass = 1; /* Class = 31 bit addressable */

▌3▐Cnmpool(spfunc,&sptoken,&spname,spleng,sppricnt,spseccnt, spclass); /* Allocate Subpool */

The descriptions for the steps shown in “Using Varying Length Character Strings in C” on page 109 are: ▌1▐ spname is defined as a varying length character string. ▌2▐ spname is assigned the value POOLNAME using the Cnmvlc function ▌3▐ Cnmpool is started with the operand &spname. When passing a structure as a operand, pass a pointer to the structure rather than the structure itself. In this example, the & (address) operator is used when passing spname to Cnmpool. If you defined a pointer variable, assigned the address of the structure to that pointer variable, and passed the pointer variable to Cnmpool, verify that you assigned the pointer variable before passing it to the HLL service routine.

CNMVLC: converting a string to a varying length character string CNMVLC enables you to convert a C string to a varying length character string to be used in the NetView HLL environment. You can choose to provide a simple null-terminated string or a format string as input. If you specify formatting, you must provide a valid argument list. CNMVLC also converts the input string to hexadecimal, if desired. This option can be helpful when you code command processors that start CNMCNMI and CNMKIO.

CNMVLC calculates the length of the converted string (not including the null terminator) and stores it in the 2-byte size field of the varying length character string structure. The null terminator is actually copied into the buffer portion of the structure even though it is not included in the size calculation. This ensures that the structure's buffer portion is null-terminated so that it can be used by other C library routines.

A pointer to the converted varying length character string structure is returned to the caller on successful completion of this routine. If an error occurs, CNMVLC returns a null pointer. See Chapter 9, “C high-level language services,” on page 117 for examples showing the use of CNMVLC.

The syntax for this function is: void *CNMVLC(void *vstring, short convert, char *istring);...

Where: convert Is a 2-byte integer field containing the value 0 or 1, indicating whether the

110 Programming: PL/I and C C Code Interfaces and Restrictions

input string is converted to hexadecimal. Constants NOHEXCNV and CNVTOHEX are defined in DSICCONS, as follows: 0 (NOHEXCNV) Do not convert input string to hexadecimal. 1 (CNVTOHEX) Convert input string to hexadecimal. istring An input string that follows the conventions specified for the format-string operand of the printf function in C.The istring variable must be null-terminated and can contain format specifications (designated by %). Provide an argument list if you want formatting. Refer to the SAA Common Programming library for more information. vstring Is a varying length character string to receive the converted string. See “Varying length character strings” on page 108 for more details.

Note: 1. If you specify conversion to hexadecimal, all of the characters in the input string must represent valid hexadecimal data. Cnmvlc returns a void pointer if it encounters a character that cannot be converted to hexadecimal. 2. A null pointer is also returned if you do not specify a valid value for convert or if the format specifications cannot be resolved. 3. Some of the HLL services routines (such as Cnmcnmi and Cnmkio) require you to move hexadecimal data into varying length character strings. This can often create a problem for the C programmer because of the probability that the null terminator (represented as hexadecimal zeros) is interspersed throughout the hexadecimal data stream. In this situation, use CNMNVLC. 4. If istring contains a format string, you must provide a vstring that can contain the entire resolved format string, irrespective of hexadecimal conversion.

CNMNVLC: converting a string to a varying length character string using length CNMNVLC enables you to convert a C string to a varying length character string to be used in the NetView HLL environment. This function is primarily used for moving hexadecimal data into varying length character strings and is particularly useful when coding HLL command processors that start CNMCNMI or CNMKIO.

The function provided by CNMNVLC is very similar to that of CNMVLC, except that you pass a length field. CNMNVLC uses the length field to determine how many characters to copy from the input string. Also, CNMNVLC does not accept format specifications or an argument list. You can choose to convert an input string to hexadecimal. If you specify hexadecimal conversion, the length operand represents the length of the input string before it is converted.

When the copy function is complete, CNMNVLC stores the value of the length operand in the structure. The null terminator is copied into the buffer portion of the structure even though it is not included in the size calculation.

Chapter 8. Coding your C program interfaces and restrictions 111 C Code Interfaces and Restrictions

A pointer to the converted varying length character string structure is returned to the caller on successful completion of this routine. If an error occurs, CNMNVLC returns a null pointer. See Chapter 9, “C high-level language services,” on page 117 for examples of CNMNVLC.

The syntax for this function is: void *CNMNVLC(void *vstring, short convert, int length, char *istring);

Where: convert Is a 2-byte integer field containing the value 0 or 1, indicating whether to convert the input string to hexadecimal. Constants NOHEXCNV and CNVTOHEX are defined in DSICCONS as follows: 0 (NOHEXCNV) Do not convert input string to hexadecimal. 1 (CNVTOHEX) Convert input string to hexadecimal. istring Is an input string. If hexadecimal conversion is required, all of the characters in the input string must represent valid hexadecimal data. length Is a 4-byte integer field specifying the number of bytes to copy from the input string. If hexadecimal conversion is required, length is the length of the input string before it is converted. length must be greater than zero. vstring Is a varying length character string to receive the converted string. See “Varying length character strings” on page 108 for more details.

Note: 1. Cnmnvlc returns a void pointer if it encounters a character that cannot be converted to hexadecimal. 2. A null pointer is also returned if you do not specify a valid value for convert or length.

Control blocks and include files A number of control blocks and include files are required to start an HLL program written in C in the NetView environment. DSIC, which includes the rest of the files, is the main file necessary to compile HLL programs written in C. Optional include files are provided to assist you in coding and maintaining HLL programs. You can tailor DSIC, DSICCNM and DSICCONS to your needs.

Note: Tailoring files can lead to better performance in many cases. This is helpful in performance-sensitive environments such as installation exits.

The following include files are listed in Appendix C, “C language control blocks and include files,” on page 279: DSIC (Required) Must be included for all HLL programs written in C. DSIC includes all of the external HLL control blocks and include files needed to compile and run C programs in the NetView environment. See the C coding template in Chapter 9, “C high-level language services,” on page 117 for usage.

112 Programming: PL/I and C C Code Interfaces and Restrictions

DSICCONS (Optional) Defines constants that are helpful when coding HLL programs in C. DSICVARC (Required) Specifies C mapping of a varying length character string. DSICHLB (Required) Specifies C mapping of the NetView HLB control block. DSICORIG (Required) Specifies C mapping of the origin block of the request that caused the execution of the program currently running. DSICPRM (Required) Specifies C mapping of the NetView Bridge parameter control block. DSICCALL (Required) Specifies C definitions for HLL service routines. DSICCNM (Optional) Defines HLL return code constants for C.

C input/output considerations C provides several input and output routines that allow you to transmit data between main storage and auxiliary storage of a computer. C programs using such file input/output capabilities can run in the NetView environment. However, there are some important things to consider when doing file I/O in C.

Each file referenced from your C program correlates to a physical data set in auxiliary storage. You can specify the file name or a data definition name (ddname) when opening a file using fopen. If you specify a ddname, you must ensure that the appropriate data set is allocated before attempting to open the file. You can allocate under TSO or by using the NetView ALLOCATE command described in the NetView online help. NetView also provides a FREE command to deallocate a data set.

If the data set is allocated from TSO, you must also add a corresponding DD statement to the NetView startup procedure. The data definition name (ddname) in the DD statement must match the ddname specified in the call to the fopen library routine. The DD statement specifies a physical data set name (dsname) and gives its characteristics as shown in this example: //OUTFILE DD DSN=MYPROG.OUTFILE, ...

A DD statement is not necessary if the data set is allocated using the NetView ALLOCATE command.

This example shows the use of file I/O in an HLL program written in C. The check for a null pointer is added to protect against a failure in fopen. This check is suggested when opening a file for I/O. Example of File I/O in an HLL Program Written in C Language FILE *Outfd; /* Define file */ . . . /********************************************************************/

Chapter 8. Coding your C program interfaces and restrictions 113 C Code Interfaces and Restrictions

/* Check for error opening file for I/O. If fopen error occurs, */ /* issue an error message and exit program. */ /********************************************************************/ if ((Outfd = fopen("dd:OUTFILE","w")) == NULL) { Cnmvlc(&msgbuf,NOHEXCNV,"ERROR OPENING DATA FILE."); Cnmsmsg(&msgbuf,MSG,SYSOP,NULLCHAR); Hlbptr->Hlbrc = CNM_GOOD; exit(); } . . . fprintf(Outfd, ... /* Write to output file */ fclose(Outfd); /* Close output file */

If you choose to write to a common output file from two or more C programs, the programs must coordinate access to the common file. You can do this by using NetView’s CNMLK service routine, if desired. If access is not coordinated, you can get a system ABEND 213.

Take care when attempting to share open files between two or more HLL programs. Sharing of open files must be coordinated between the sharing programs.

Note: PL/I and C cannot share an open file. However, a C program can read a file created by PL/I.

Certain C routines (such as getchar and putchar) are designed to perform functions on stdin and stdout. By default, stdin and stdout are directed to the terminal. These defaults are not valid and cause undetermined results if used in the NetView environment. You can perform terminal I/O using WAIT FOR OPINPUT and CNMSMSG as described in Chapter 11, “Service reference,” on page 173.

Refer to the z/OS C/C++ library and the z/OS Language Environment library for more information about files and C language I/O.

C runtime considerations Most runtime errors detected in the C environment are handled by passing a return code or a null pointer back to the caller. Runtime errors that are detected by the operating system generate an interrupt signal that normally can be handled by coding a signal function in your program. However, because C language programs must run with the NOSTAE and NOSPIE or TRAP(OFF) options in a production NetView environment, the operating system is unable to generate such interrupts.

While debugging a C language program in a test NetView environment, you can use the STAE and SPIE or TRAP(ON) options until runtime problems are resolved. Runtime errors that are not detected by the operating system cause a diagnostic message to be written to stderr.

Refer to the z/OS C/C++ library and the z/OS Language Environment library for more information about files and C language I/O.

114 Programming: PL/I and C C Code Interfaces and Restrictions

Considerations for HLL command processors You must code a CMDDEF statement in CNMCMD for each HLL command processor that you write. The CMDDEF type depends on the functions that your command processor performs. Keep in mind that some of the HLL services are useful only when they are run under a DST.

The CMDDEF statement is described in the IBM Tivoli NetView for z/OS Administration Reference.

There is no support for HLL command processors running as immediate commands (TYPE=I) or being pushed (with the macro DSIPUSH) as ABEND, LOGOFF, or RESUME routines.

Return codes Upon completion of an HLL service routine, the completion code from that service routine is stored in the return code field (Hlbrc) of the HLB control block. Check this field after each HLL service routine invocation. Also, use this field when passing return codes between HLL programs.

A return type of void is specified for each of the HLL service routines defined in DSICCALL. This indicates that the HLL service routines do not return values to you. You can check the completion code only by evaluating the return code field (Hlbrc) in the HLB.

For a complete list of HLL API return codes, see DSICCNM in Appendix C. See Chapter 11, “Service reference,” on page 173 for a list of return codes that apply to each HLL service routine.

In C, you can achieve normal termination by assigning a value to Hlbrc and issuing a return() statement as follows: Hlbptr->Hlbrc = CNM_GOOD; /* Successful completion */ return(); /* Return to caller */

Restrictions for HLL programs written in C language C functions not supported in the NetView environment are: system Cnmcmd - suggested HLL alternative

You cannot use the following functions without redirecting stdin, stdout, and stderr as follows: getchar Cnmgetd - suggested HLL alternative getenv Cnminfi, Cnminfc, Origblck, Cnmvars - suggested HLL alternatives gets Cnmgetd - suggested HLL alternative printf Cnmsmsg - suggested HLL alternative putchar Cnmsmsg - suggested HLL alternative puts Cnmsmsg - suggested HLL alternative scanf Use Cnmgetd to fetch data and sscanf to parse data perror Check return code and use Cnmsmsg

Chapter 8. Coding your C program interfaces and restrictions 115 C Code Interfaces and Restrictions

ferror To put out message

Special Considerations: 1. The C signal function does not work for errors detected by the operating system. 2. You cannot use Cnmsmsg to display wide character strings. If you want to process wide character strings, redirect stdout and use the printf function.

Restrictions for C programs running in a preinitialized environment Other restrictions for C programs that run in a preinitialized environment include: v Exit() statements are not valid. v Invocations of assembler routines that contain an SVC LINK command are not valid. v The z/OS UNIX System Services functions (including z/OS UNIX C socket functions) are not valid.

116 Programming: PL/I and C Chapter 9. C high-level language services

This chapter provides an example-oriented description of commands and services provided by the NetView program in support of the C language. Refer to the IBM Tivoli NetView for z/OS Command Reference and Chapter 11, “Service reference,” on page 173 for more information.

C sample template You can use the following coding template sample when you are coding HLL programs in C. You can use this template, with your enhancements, to use NetView functions and commands. Use the additional examples in this section with this template. You can find fully functional samples of NetView command procedures written in C in Appendix D, “C samples,” on page 281. Coding template for HLL programs in C /********************************************************************/ /* */ /* 5697-B82 (C) COPYRIGHT IBM CORPORATION 1989, 2011 */ /* ALL RIGHTS RESERVED. */ /* */ /* IEBCOPY SELECT MEMBER=((CNMS4201,CTMPPLT,R)) */ /* */ /* (Explanations included in parentheses should be deleted) */ /* (after the pertinent information has been filled in. ) */ /* */ /* Descriptive Name: High-Level Language C Template */ /* (This is the more descriptive name or title of the module.) */ /* */ /* Function: */ /* Template for writing HLL modules in C. */ /* (This is the description of what the module does.) */ /* (It may be paragraph or pseudocode form. ) */ /* */ /* Dependencies: */ /* (List conditions that must be met in order for this) */ /* (module to perform. An example of this might be a ) */ /* (key data area that must already have been built. ) */ /* */ /* Restrictions: */ /* (List any limitations this module may have.) */ /* */ /* Language: C */ /* */ /* Input: */ /* 1) A pointer to a 4-byte field containing the address of */ /* the HLB control block. */ /* 2) A varying length character string containing the */ /* command or message which invoked this program. */ /* If this program was invoked as a command processor, */ /* this will be a command string. */ /* If this program was invoked as a installation exit */ /* (other than DSIEX02A), this will be a message string. */ /* When driven as DSIEX02A- */ /* this string will be empty and the message must */ /* be retrieved from the Initial Data Queue (IDATAQ). */ /* 3) A 40-byte structure which describes the origin of the */ /* request that caused execution of this program. */ /* */

/* Output: */ /* (Describe any output from this module.) */ /* */ /* Return Codes: returned in Hlbrc */ /* For Command Processors: */ /* 0 = normal exit */ /* -5 = cancelled */ /* (List any other return codes meaningful to this module.) */ /* For User Exits: */ /* 0 = USERASIS (Leave the contents of the message buffer */ /* unchanged) */ /* 4 = USERDROP (Drop the message buffer) */ /* 8 = USERSWAP (Change the contents of the message buffer) */ /* */ /* External Module References: */ /* (List modules that are called by this module.) */ /* */ /* Change Activity: */ /* date,author: description of changes */ /* (Keep a log of the changes made to this module for) */ /* (future reference. ) */ /********************************************************************/ #pragma runopts( STACK(128K,128K,ANY,FREE) HEAP(128K,128K,ANY,FREE,8,0) ) #pragma runopts( BELOWHEAP(8,0,FREE) LIBSTACK(8,0,FREE) ) #pragma runopts( INTERRUPT(OFF) NOTEST(ALL,*,* ) STORAGE(,,,0) ) #pragma runopts( TRAP(OFF) MSGQ(1) ALL31(ON) ) /********************************************************************/ /* Standard include files /********************************************************************/ #include /* Standard I/O header */ #include /* String functions */ #include /* Standard definitions */ #include /* Standard library */ #include /* Standard args */ /********************************************************************/ /* NetView High-Level Language include files */ /********************************************************************/ #include "dsic.h" /* Include HLL macros */ /********************************************************************/ /* External data definitions */ /********************************************************************/ Dsihlb *Hlbptr; /* Pointer to the HLB */ Dsivarch *Cmdbuf; /* Pointer to command buffer */ Dsiorig *Origblck; /* Pointer to Origin block */

/******************************************************************/ /* Convert parameter pointers from character to hex addresses */ /******************************************************************/ sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck);

/******************************************************************/ /* Initialization */ /******************************************************************/

/******************************************************************/ /* Execution */ /******************************************************************/ Hlbptr->Hlbrc = CNM_GOOD; /* Successful completion */ }

118 Programming: PL/I and C C High-Level Language Services

Varying length character strings Chapter 8, “Coding your C program interfaces and restrictions,” on page 103 reviewed the use of varying length characters strings with HLL command procedures. Cnmvlc and Cnmnvlc are provided for working with varying length character strings. Cnmvlc is useful when copying null-terminated text into a varying length character string and building RUs for the CNMI. Cnmnvlc is useful when dealing with data that has nulls in it and data that is not null-terminated.

In several of the samples and examples in this document, varying length character strings are defined as type Dsivarch, a pointer to a structure defining a 256-byte varying length character string. This is only for convenience. It is more efficient to use a varying length character string with a buffer size closer to that of your data.

The following examples show how to use Cnmvlc and Cnmnvlc, and how to define varying length character strings with different buffer sizes. CNMVLC CNMVLC is used to copy a C character string into a varying length character string.

This example copies the text “Hello World” into a varying length character string for use with CNMSMSG. &msg is defined as a varying length character string. /* put message in varying length */ /* character string... */ Cnmvlc(&msg, /* ...varying len char strng */ NOHEXCNV, /* ...do not convert to hex */ "Hello World"); /* ...message */ /* display message... */ Cnmsmsg(&msg, /* ...message text */ MSG, /* ...type is message */ OPER, /* ...send message to oper */ NULLCHAR); /* ...not used */

CNMVLC returns a pointer to the varying length character string into which data is being copied. Therefore, it can be embedded directly into calls to HLL service routines. Here is an example of a call to CNMVLC embedded in a call to the CNMSMSG service routine: Cnmsmsg(Cnmvlc(&msg,NOHEXCNV,"Hello World"),MSG,OPER,NULLCHAR);

The next example copies an RU into a varying length character string and converts it to hexadecimal. ru is defined as a varying length character string and puname is a C character string containing the name of the PU where the RU is to be sent. /* put RU in varying length */ /* character string... */ Cnmvlc(&ru, /* ...varying length char strng */ CNVTOHEX, /* ...convert to hex */ "810810000000000E41038D0000011100000680900281F108D7E4D5C1D4C500"); /* ...the RU */

/* Send RU over the CNMI... */ Cnmcnmi(SENDRPLY, /* ...expect a reply */ &ru, /* ...RU built above */ puname.buffer, /* ...to the PU name specified */ 180); /* ...timeout after 3 minutes */

Chapter 9. C high-level language services 119 C High-Level Language Services

Here is an example of using a format string with CNMVLC. It shows the text “Day 1 of five” copied into a varying length character string. num is defined as an integer with a value of 1 and string is defined as a character string with a value of “five”. /* put message in varying length */ /* character string... */ Cnmvlc(&msg, /* ...varying len char strng */ NOHEXCNV, /* ...do not convert to hex */ "Day %d of %s", /* ...format string */ num, /*...substitute for %d */ string); /* ...substitute for %s */ /* display message... */ Cnmsmsg(&msg, /* ...message text */ MSG, /* ...type is message */ OPER, /* ...send message to oper */ NULLCHAR); /* ...not used */ CNMNVLC CNMNVLC is used to copy C character strings containing null data into varying length character strings.

Here an RU returned by the CNMI is copied into another varying length character string. data is defined as a varying length character string. getblock is defined as a structure of type ORIGBLCK, and msg is defined as a varying length character string.

Note: The RU in the next example can contain null data.

CNMNVLC copies for the length specified regardless of the presence of nulls. /* Read in the first RU returned */ Cnmgetd(GETLINE, /* ...a single RU */ &data, /* ...inti here */ 1024, /* ...truncate after 1024 bytes */ &getblock, /* ...provide a new origin block */ CNMIQ, /* ...on the CNMI queue (5) */ 1); /* ...the first RU */ /* copy varying length character */ /* string to another varying */ /* length character string... */ Cnmnvlc(&msg, /* ...dest varying len char strng*/ NOHEXCNV, /* ...do not convert to hex */ data.size, /* ...numbers of chars to move */ data.buffer); /* ...RU to copy */ Defining varying length character strings Sometimes, you must create varying length character strings other than Dsivarch. This example copies the text “Hello World” into a user-defined varying length character string: typedef struct /* create your own varying length*/ { /* character string... */ short size; /* ...2 byte size field */ char buffer??(12??); /* ...12 byte buffer */ } myvlc; /* ...data type */

main() { myvlc msg; /* msg is a varying length */ /* character string of type myvlc*/

/* copy Hello World into user */

120 Programming: PL/I and C C High-Level Language Services

Cnmvlc(&msg,NOHEXCNV,"Hello World"); /* defined varying length */ /* character string */ Cnmsmsg(&msg,MSG,OPER,NULLCHAR); /* send message to operator */ }

Sometimes you must pass a command buffer larger than 256 characters to a C program. In these cases, must change the declaration for Cmdbuf provided in the C template. The next example accepts a command buffer larger than 256 characters and sends it to the authorized receiver. typedef struct /* create your own varying length*/ { /* character string... */ short size; /* ...2 byte size field */ char buffer??(300??); /* ...300 byte buffer */ } myvlc; /* ...data type */

myvlc *Cmdbuf; /* Cmdbuf is a varying length */ /* character string of type myvlc*/ main(int argc, char *argv??(??)) /* receive parameter list from...*/ { /* ...NetView */ sscanf(argv??(2??),"%x",&Cmdbuf); /* Convert Cmdbuf ptr to hex */ Cnmsmsg(Cmdbuf,MSG,AUTHRCV,NULLCHAR); /* display message */ }

Data queue management NetView uses several data and message queues to work with HLL service routines. Information retrieved from these queues through the CNMGETD function can be manipulated to enhance your network manageability. These queues are defined for data and message management:

Queue Queue Name Number Function TRAPQ 1 Message queue. Contains trapped messages. See “TRAP command” on page 182. OPERQ 2 Operator input queue. See “GO command” on page 177 and “QUEUE command” on page 178. DATAQ 3 Data queue. Contains data sent from another HLL command processor or installation exit routine. See “CNMSMSG (CNMSENDMSG): Send Message or Command” on page 251. IDATAQ 4 Initial data queue. Contains the full message or MSU that starts the HLL command processor through NetView automation. It also contains messages that drive DSIEX02A and DSIEX17. This is also the queue where an application command processor receives an MDS-MU from the NetView high-performance transport, the MS transport, or operations management for an unsolicited request or asynchronous reply. For invocations from pipes, the IDATAQ contains the data flowing into the HLL command processor. CNMIQ 5 CNMI solicited data queue. Contains RUs solicited through the CNMI service routine. Chained RUs are treated like multiline messages. See “CNMCNMI (CNMI): CNMI access under a DST” on page 189. MDSMUQ 6 MDS-MU data queue. Contains MUs received as synchronous replies. The MDS-MUs are received from operations management, the MS transport, and the high-performance transport. Refer to IBM Tivoli NetView for z/OS Application Programmer's Guide for more information.

Chapter 9. C high-level language services 121 C High-Level Language Services

The examples in the following sections show how the preceding queues are used with HLL command procedures.

Sending messages “Sending messages (C)” shows how to send messages. Sending messages (C) /*********************************************************************/ /* Internal data definitions */ /*********************************************************************/

Dsivarch msgbuf; /* var len char strng for messages */

/*********************************************************************/ /* Send a multiline message to user. */ /*********************************************************************/ Cnmvlc(&msgbuf,0,"LINE 1 OF 3"); Cnmsmsg(&msgbuf,MSG_C,OPER,NULLCHAR); Cnmvlc(&msgbuf,0,"Line 2 of 3"); Cnmsmsg(&msgbuf,MSG_D,OPER,NULLCHAR); Cnmvlc(&msgbuf,0,"Line 3 of 3"); Cnmsmsg(&msgbuf,MSG_F,OPER,NULLCHAR);

/*********************************************************************/ /* Send a multiline message to a task. */ /*********************************************************************/ Cnmvlc(&msgbuf,0,"Line 1 of 3"); Cnmsmsg(&msgbuf,MSG_C,TASK,"OPER1 "); Cnmvlc(&msgbuf,0,"Line 2 of 3"); Cnmsmsg(&msgbuf,MSG_D,TASK,"OPER1 "); Cnmvlc(&msgbuf,0,"LINE 3 OF 3"); Cnmsmsg(&msgbuf,MSG_F,TASK,"OPER1 "); /*********************************************************************/ /* Send a message to the system console (only 1-liners). */ /*********************************************************************/ Cnmvlc(&msgbuf,0,"HELLO SYSOP"); Cnmsmsg(&msgbuf,MSG,SYSOP,NULLCHAR);

/*********************************************************************/ /* Send a message to the authorized receiver. */ /*********************************************************************/ Cnmvlc(&msgbuf,0,"HELLO AUTHRCV"); Cnmsmsg(&msgbuf,MSG,AUTHRCV,NULLCHAR); /*********************************************************************/ /* Send a message to the log. */ /*********************************************************************/ Cnmvlc(&msgbuf,0,"This should only be in the log"); Cnmsmsg(&msgbuf,MSG,NETVLOG,NULLCHAR);

/*********************************************************************/ /* Send to the sequential log */ /*********************************************************************/ Cnmvlc(&msgbuf,0,"Test message"); Cnmsmsg(&msgbuf,MSG,SEQLOG,"SQLOGTSK"); /*********************************************************************/ /* Send to a group */ /*********************************************************************/ Cnmvlc(&msgbuf,0,"Hello group"); Cnmsmsg(&msgbuf,MSG,OPCLASS,"+GROUP1 ");

122 Programming: PL/I and C C High-Level Language Services

Starting synchronous commands “Starting synchronous commands” shows an HLL command processor starting another command. The command can be another HLL command, a command list, a VTAM command, or a NetView command. Starting synchronous commands /******************************************************************/ /* Internal data definitions */ /******************************************************************/

Dsivarch command, /* varying len char strng for cmds */ message; /* varying len char strng for msgs */

/******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/

/*copy vtam command d net,appls into varying length character */ /*string using cnmvlc */

Cnmvlc(&command, /* varying length character string */ 0, /* do not convert to hex */ "D NET,APPLS"); /* command to copy into varying */ /* length character string */

/*issue the command */

Cnmcmd(&command); if (Hlbptr->Hlbrc != CNM_GOOD) /* always check rc from Cnmcmd */ { /* if bad return code from Cnmcmd */ /* place message in varying length */ Cnmvlc(&message, /* character string... */ 0, /* ...do not convert to hex */ "Command not scheduled successfully"); /* ...message */ /* issue message... */ Cnmsmsg(&message, /* ...message text */ MSG, /* ...type is message */ OPER, /* ...send to invoking operator */ NULLCHAR); /* ...not used */ }

Sending commands The following example shows a command being sent to run on another task. The command to be run on the other task can be another HLL command, a command list, a VTAM command, or a NetView command.

You can use this process to start commands under DSTs, other OSTs, or the PPT. /******************************************************************/ /* Internal data definitions */ /******************************************************************/

char oper1??(9??) = "OPER1 "; /* 8 char task name for Cnmsmsg */ Dsivarch logoff, /* used to store logoff command */ msgbuf; /* var len char strng for messages */

/******************************************************************/ /* */ /* Execution */ /* */

Chapter 9. C high-level language services 123 C High-Level Language Services

/******************************************************************/ /* copy command into varying */ /* length character string... */ Cnmvlc(&logoff, /* ...varying length string */ 0, /* ...do not convert to hex */ "LOGOFF"); /* ...command to be copied */

/* send the command... */ Cnmsmsg(&logoff, /* ...text of the command to run */ COMMAND, /* ...this is a command */ TASK, /* ...run it on a task */ oper1); /* ...task name is oper1 */ if (Hlbptr->Hlbrc == CNM_GOOD) /* inform user of success */ { /* copy message into varying */ /* length character string... */ Cnmvlc(&msgbuf, /* ...varying length string */ 0, /* ...do not convert to hex */ "OPER1 Logoff scheduled successfully"); /* ...message */

/* issue message... */ Cnmsmsg(&msgbuf, /* ...text of message */ MSG, /* ...this is a message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ } else { /* inform user task not active */ if (Hlbptr->Hlbrc == CNM_TASK_INACTIVE) { /* copy message into varying */ /* length character string... */ Cnmvlc(&msgbuf, /* ...varying length string */ 0, /* ...do not convert to hex */ "OPER1 Not Active");/* ...message */

/* issue message... */ Cnmsmsg(&msgbuf, /* ...text of message */ MSG, /* ...this is a message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ } else { /* inform user bad rc */ /* copy message into varying */ /* length character string... */ Cnmvlc(&msgbuf, /* ...varying length string */ 0, /* ...do not convert to hex */ "Unexpected rc from Cnmsmsg"); /* ...message */

/* issue the message... */ Cnmsmsg(&msgbuf, /* ...text of message */ MSG, /* ...this is a message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ } } Hlbptr->Hlbrc = CNM_GOOD; /* clear rc */

124 Programming: PL/I and C C High-Level Language Services

Waiting and trapping “Waiting and trapping using the TRAP and WAIT command (C)” uses the TRAP and WAIT commands to issue a command, trap the output, and respond depending on the output that is encountered. “Waiting and trapping Using the PIPE command (C)” on page 127 provide similar function using the PIPE command. Both examples activate the given LU and issue an appropriate message. Example of using the TRAP and WAIT commands (C) The syntax for the command shown in “Waiting and trapping using the TRAP and WAIT command (C)” follows:

CACTLU

►► CACTLU luname ►◄

Where: luname Is the name of the LU to be activated. Waiting and trapping using the TRAP and WAIT command (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsiorig origptr; /* work block for Cnmgetd */ char *token, /* used to parse command buffer */ nodename??(9??); /* LU to activate */ Dsivarch command, /* varying len char strng for cmds */ msgbuf; /* varying len char strng for msgs */

/******************************************************************/ /* retrieve node name from command buffer */ /******************************************************************/

token = strtok((char *) &(Cmdbuf->buffer)," "); /* parse command*/ token = strtok(NULL," "); /* buffer for LU name */ strcpy(nodename,token);

if (strlen(token) > 8) /* node name invalid */ token = NULL; if (token != NULL) /* if nodename specified */ { /* copy command into varying length */ /* character string... */ Cnmvlc(&command, /* ...varying length string */ 0, /* ...do not convert to hex */ "TRAP AND SUPPRESS ONLY MESSAGES IST*"); /* ...command */

Cnmcmd(&command); /* issue command to trap VTAM messages*/ /****************************************************************/ /* build vtam command to activate node */ /****************************************************************/

/* copy command into varying length */ /* character string... */ Cnmvlc(&command, /* ...varying length string */ 0, /* ...do not convert to hex */ "V NET,ACT,ID=%s",nodename); /* ...command */ Cnmcmd(&command); /* issue command to activate node */

Chapter 9. C high-level language services 125 C High-Level Language Services

/* put command to wait for 10 sec in */ /* varying length character string...*/ Cnmvlc(&command, /* ...varying length string */ 0, /* ...do not convert to hex */ "WAIT 10 SECONDS FOR MESSAGES"); /* ...command */

Cnmcmd(&command); /* issue command to wait for 10secs */ /* get first trapped message... */ Cnmgetd(GETMSG, /* ...function is get a message */ &msgbuf, /* ...result goes here */ 255, /* ...max input length */ &origptr, /* ...must provide a work area */ TRAPQ, /* ...message is trapped */ 1); /* ...get the first one */ /******************************************************************/ /* */ /* Loop through messages until IST093I is found or until no more */ /* messages are left */ /* */ /******************************************************************/ /* put wait continue command in */ /* varying length character string... */ Cnmvlc(&command, /* ...varying length string */ 0, /* ...do not convert to hex */ "WAIT CONTINUE"); /* ...command */ while((strncmp(origptr.Orig_process,"IST093I",7) != 0) && (Hlbptr->Hlbrc == CNM_GOOD)) { Cnmcmd(&command); /* issue wait continue */ /* get next trapped message... */ Cnmgetd(GETMSG, /* ...function is get a message */ &msgbuf, /* ...result goes here */ 255, /* ...max input length */ &origptr, /* ...must provide a work area */ TRAPQ, /* ...message is trapped */ 1); /* ...get the first one */ } if (Hlbptr->Hlbrc == CNM_GOOD) /* did we find IST093I? */ { /* inform user activation worked */ /**************************************************************/ /* build message to inform user activation worked */ /**************************************************************/

/* copy message into varying length */ /* character string... */ Cnmvlc(&msgbuf, /* ...varying length string */ 0, /* ...do not convert to hex */ "RESOURCE %s NOW ACTIVE",nodename); /* ...message */ /* issue message... */ Cnmsmsg(&msgbuf, /* ...message to issue */ MSG, /* ...type is message */ OPER, /* ...issue to operator */ NULLCHAR); /* ...unused */ } else { /* IST093I not found, must be error */ /* copy message into varying length */ /* character string... */ Cnmvlc(&msgbuf, /* ...varying length string */ 0, /* ...do not convert to hex */ "ERROR - ACTIVATION UNSUCCESSFUL"); /* ...message */ /* ...message */ /* issue message... */ Cnmsmsg(&msgbuf, /* ...message to issue */ MSG, /* ...type is message */

126 Programming: PL/I and C C High-Level Language Services

OPER, /* ...issue to operator */ NULLCHAR); /* ...unused */ } } else /* nodename not specified */ { /* inform user he needs more args */

/* copy message into varying length */ /* character string... */ Cnmvlc(&msgbuf, /* ...varying length string */ 0, /* ...do not convert to hex */ "ERROR - INVALID NODENAME"); /* ...message */ /* ...message */ /* issue the message... */ Cnmsmsg(&msgbuf, /* ...message to issue */ MSG, /* ...type is message */ OPER, /* ...issue to operator */ NULLCHAR); /* ...unused */ } Example of using the PIPE command (C) The syntax for the command shown in “Waiting and trapping Using the PIPE command (C)” follows:

CACTPIP

►► CACTPIP luname ►◄

Where: luname Is the name of the LU to be activated. Waiting and trapping Using the PIPE command (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsiorig origptr; /* Work block for Cnmgetd */ char *result, /* Used to parse command buffer */ *token, /* Used to parse command buffer */ nodename??(9??); /* LU to activate */ Dsivarch command, /* Varying len char strng for cmds */ varnm, /* Varying len char strng for varnm*/ msgbuf; /* Varying len char strng for msgs */ /******************************************************************/ /* Retrieve node name from command buffer */ /******************************************************************/

token = strtok((char *) &(Cmdbuf->buffer)," "); /* parse command */ token = strtok(NULL," "); /* Buffer for LU name */ strcpy(nodename,token); if (token != NULL) /* If nodename specified */ { /****************************************************************/ /* Build PIPE command to issue user activation */ /****************************************************************/ /* Copy variable name into varying */ Cnmvlc(&varnm, /* length character string */ 0, /* ...do not convert to hex */ "VNETRESULT"); /* ...name of variable */ Cnmvars(DCL, /* Declare a variable ... */ "", /* ...not needed */

Chapter 9. C high-level language services 127 C High-Level Language Services

0, /* ...not needed */ &varnm, /* ...specifies variable name */ LOCAL); /* ...local variable pool */ /****************************************************************/ /* Build the PIPE command. */ /* The VTAM stage issues the VARY command. */ /* The CORRWAIT stage waits 10 seconds for each message to */ /* return to the pipeline. */ /* The TOSTRING stage selects messages to remain in the */ /* pipeline up to and including one having ’IST093I’ */ /* in columns 1-7. */ /* The TAKE stage selects the last message in the pipeline, */ /* discarding all others. */ /* The VAR stage writes the message to the variable specified. */ /****************************************************************/ /* Copy command into varying */ Cnmvlc(&command, /* length string */ 0, /* ...do not convert to hex */ "PIPE VTAM V NET,ACT,ID=%s%s",nodename, " | CORRWAIT 10" " | TOSTRING FIRST 1.7 /IST093I/" " | TAKE LAST 1" " | VAR VNETRESULT"); Cnmcmd(&command); /* Issue PIPE command */

Cnmvars(GET, /* Read the variable ... */ &msgbuf, /* ...result goes here */ 256, /* ...max input length */ &varnm, /* ...specifies variable name */ LOCAL); /* ...local variable pool */

result = strstr(msgbuf.buffer,"IST093I"); if (result != NULL) /* Did we find IST093I? */ { /* Inform user activation worked */

/**************************************************************/ /* Build message to inform user activation worked */ /**************************************************************/

/* Copy message into varying length*/ /* character string... */ Cnmvlc(&msgbuf, /* ...varying length string */ 0, /* ...do not convert to hex */ "RESOURCE %s NOW ACTIVE",nodename); /* ...message text */

/* Issue message... */ Cnmsmsg(&msgbuf, /* ...message to issue */ MSG, /* ...type is message */ OPER, /* ...issue to operator */ NULLCHAR); /* ...unused */ } else { /* IST093I not found, must be error*/ /* Copy message into varying length*/ /* character string... */ Cnmvlc(&msgbuf, /* ...varying length string */ 0, /* ...do not convert to hex */ "ERROR - ACTIVATION UNSUCCESSFUL"); /* ...message text */

/* Issue message... */ Cnmsmsg(&msgbuf, /* ...message to issue */ MSG, /* ...type is message */ OPER, /* ...issue to operator */ NULLCHAR); /* ...unused */ } }

128 Programming: PL/I and C C High-Level Language Services

else /* Nodename not specified */ { /* Inform user he needs more args */

/* Copy message into varying length*/ /* character string... */ Cnmvlc(&msgbuf, /* ...varying length string */ 0, /* ...do not convert to hex */ "ERROR - NODENAME NOT SPECIFIED"); /* ...message text */

/* Issue the message... */ Cnmsmsg(&msgbuf, /* ...message to issue */ MSG, /* ...type is message */ OPER, /* ...issue to operator */ NULLCHAR); /* ...unused */ }

For more information about the PIPE command, refer to IBM Tivoli NetView for z/OS Programming: Pipes.

Retrieving information “Retrieving information (C)” shows how an HLL command processor or installation exit routine can retrieve information from the NetView program. HLL command processors and installation exit routines can access this information.

See “CNMINFC (CNMINFOC): Query NetView Character Information” on page 218 and “CNMINFI (CNMINFOI): Query NetView Integer Information” on page 221 for a list of the values supported. Retrieving information (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsivarch cdata, /* store data returned by Cnminfc */ msgbuf; /* var len char strng for messages */ int idata; /* store data returned by Cnminfi */

/******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/ /* retrieve date and time... */ Cnminfc("DATETIME", /* ...specify the variable */ &cdata, /* ...result goes here */ 18); /* ...at most eight bytes */

cdata.buffer??(cdata.size??) = ’\0’; /* terminate data with null */ /*****************************************************************/ /* build message to display results */ /*****************************************************************/

/* put message in varying length */ /* character string... */ Cnmvlc(&msgbuf, /* varying length string... */ 0, /* do not convert to hex... */ "DATE/TIME IS: %s",cdata.buffer); /* ...message */

/* display results... */ Cnmsmsg(&msgbuf, /* ...text of message */ MSG, /* ...is a massage */ OPER, /* ...to invoking operator */ NULLCHAR); /* ...not used */

Chapter 9. C high-level language services 129 C High-Level Language Services

/* retrieve the number of colors */ /* that the terminal supports... */ Cnminfi("COLORS ", /* ...specify the variable */ &idata); /* ...result goes here */ /*****************************************************************/ /* build message to display results */ /*****************************************************************/

/* put message in varying length */ /* character string... */ Cnmvlc(&msgbuf, /* ...varying length string */ 0, /* ...do not convert to hex */ "NUMBER OF COLORS SUPPORTED ARE: %d",idata); /* ...message*/

/* display results... */ Cnmsmsg(&msgbuf, /* ...message text */ MSG, /* ...is a message */ OPER, /* ...to the invoking operator */ NULLCHAR); /* ...not used */

Command list variable access “Command list variable access (C)” shows the updating of common global variables. This example declares, initializes, and alters a variable, GVARIABLE. Task global variables are updated and read the same way. The only difference is that the TGLOBAL pool name is specified instead of CGLOBAL.

“Command list variable access (C)” on page 131 shows how to retrieve values from a stem variable after issuing a PIPE command with the STEM stage command. Accessing common global variables (C) Command list variable access (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsivarch datain, /* store data returned by Cnmvars */ variable; /* store variable name for Cnmvars */ int length = 24, /* max len of data returned by Cnmvars */ x; /* used to increment value returned*/ /* ...by cnmvars */ /******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/ /******************************************************************/ /* Initialize the variable */ /******************************************************************/ /* copy initial value into varying */ /* length character string... */ Cnmvlc(&datain, /* ...varying length string */ 0, /* ...do not convert to hex */ "Initial value"); /* ...initial value */

130 Programming: PL/I and C C High-Level Language Services

length, /* ...length not used */ &variable, /* ...variable name */ "CGLOBAL "); /* ...variable pool is cglobal */ /******************************************************************/ /* Find out the value of the variable */ /******************************************************************/ /* read the global variable... */ Cnmvars(GET, /* ...function is read */ &datain, /* ...data goes here */ length, /* ...truncate after 24 bytes */ &variable, /* ...variable name */ CGLOBAL); /* ...variable pool is cglobal */ /* show operator value... */ Cnmsmsg(&datain, /* ...data obtained from varpool */ MSG, /* ...type is message */ OPER, /* ...send message to operator */ NULLCHAR); /* ...not used */

/* put new in varying length */ Cnmvlc(&datain, /* character string... */ 0, /* ...do not convert to hex */ "New value"); /* ...new value */ /******************************************************************/ /* set the global variable */ /******************************************************************/ /* update the global variable... */ Cnmvars(PUT, /* ...function is write */ &datain, /* ...data is here */ length, /* ...datalen is not used */ &variable, /* ...variable name */ CGLOBAL); /* ...variable pool is CGLOBAL */

/******************************************************************/ /* verify variable has been changed */ /******************************************************************/ /* read the global variable ... */ Cnmvars(GET, /* ...function is read */ &datain, /* ...data goes here */ length, /* ...truncate after 24 bytes */ &variable, /* ...variable name */ CGLOBAL); /* ...variable pool is CGLOBAL */ /* show value to operator ... */ Cnmsmsg(&datain, /* ...data to be displayed */ MSG, /* ...type is message */ OPER, /* ...send message to operator */ NULLCHAR); /* ...not used */ Accessing stem variables using the PIPE command (C) Command list variable access (C) /*********************************************************************/ /* External data definitions */ /*********************************************************************/ struct Vchar4 { /* Varying character 4 string */ short int size; char buffer ??(5??); };

struct Vchar15 { /* Varying character 15 string */ short int size; char buffer ??(16??); };

struct Vchar80 { /* Varying character 80 string */ short int size; char buffer ??(81??);

Chapter 9. C high-level language services 131 C High-Level Language Services

};

Dsivarch pipecmd; /* Buffer to hold PIPE command */ /*********************************************************************/ /* Internal data definitions */ /*********************************************************************/ struct Vchar4 numvars; /* Number of variables in stem */ struct Vchar15 varname; /* Name of stem variable */ struct Vchar80 stemline; /* Store value of stem variable */

/*********************************************************************/ /* Execution */ /*********************************************************************/ /*********************************************************************/ /* Build a PIPE command. */ /* The < (From Disk) stage reads data into the pipeline from */ /* MYINFILE, a member of a dataset associated with the ddname */ /* DSIPARM. The records are treated as single-line messages. */ /* The NLOCATE stage discards comments lines which begin with */ /* either ’*’ or ’/*’. */ /* The STEM stage writes the remaining messages from the pipeline */ /* to stemmed variables named PIPELINEx. */ /*********************************************************************/ Cnmvlc (&pipecmd,0, "PIPE < MYINFILE" " | NLOCATE 1.1 &*& 1.2 &/*&" " | STEM PIPELINE"); /* Build PIPE command */ Cnmcmd(&pipecmd); /* Issue PIPE command */ /*********************************************************************/ /* Local variable PIPELINE0 contains the character representation of */ /* the total number of PIPELINEx stem variables. */ /*********************************************************************/ Cnmvlc (&varname, 0, "PIPELINE0"); /*********************************************************************/ /* Get number of stem variables and store value in NUMVARS. */ /*********************************************************************/ Cnmvars(GET, &numvars, 4, &varname, LOCAL); /*********************************************************************/ /* Local variable PIPELINE1 contains the first non-comment line in */ /* MYINFILE. */ /*********************************************************************/ Cnmvlc (&varname, 0, "PIPELINE1");

/*********************************************************************/ /* Get first non-comment line and store value in STEMLINE. */ /*********************************************************************/ Cnmvars(GET, &stemline, 80, &varname, LOCAL);

stemline.buffer??(81??) = ’\0’; /* Ensure string delimiter */

For more information about the PIPE command, refer to IBM Tivoli NetView for z/OS Programming: Pipes.

132 Programming: PL/I and C C High-Level Language Services

Using locks “Command list variable access (C)” on page 130 shows the updating of common global variables, but it does not show you how to protect the updating of the GVARIABLE variable by using a lock. The need for protecting the updating must be assessed on a case-by-case basis. “Example of using locks (C)” is a modified version of how to obtain a lock before attempting the update.

The lock name can be the same as the global variable, or it can be different.

If you decide that it is important to synchronize the updating of a variable, see “Example of using locks (C),” or you can run all the updates on a given task. Because only one process can occur on a task at a time, the updates are serialized. The task used can be any task, including the PPT. Example of using locks (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsivarch datain, /* store data returned by cnmvars */ variable, /* store variable name for Cnmvars */ msg; /* var len char strng for messages */ int length = 24, /* max len of data from Cnmvars */ x; /* used to increment value returned*/ /* ...by Cnmvars */ /******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/ /******************************************************************/ /* Initialize the variable */ /******************************************************************/ /* copy initial value into varying */ /* length character string... */ Cnmvlc(&datain, /* ...varying length string */ 0, /* ...do not convert to hex */ "Initial value"); /* ...initial value */

/* copy variable name into varying */ /* length character string... */ Cnmvlc(&variable, /* ...varying length string */ 0, /* ...do not convert to hex */ "GVARIABLE"); /* ...variable name */ /******************************************************************/ /* Obtain the lock to secure the accuracy of the update */ /******************************************************************/ Cnmlk(LOCK, /* obtain the lock... */ &variable, /* ...function is obtain lock */ " ", /* ...not used */ WAIT); /* ...wait if not available */

if (Hlbptr->Hlbrc == CNM_GOOD) { Cnmsmsg(Cnmvlc(&msg,0,"got lock"),MSG,OPER,NULLCHAR);

/* put an initial value in variable*/ Cnmvars(PUT, /* ...function is write */ &datain, /* ...data is here */ length, /* ...length not used */ &variable, /* ...variable name */ "CGLOBAL "); /* ...variable pool is cglobal */

Chapter 9. C high-level language services 133 C High-Level Language Services

/******************************************************************/ /* Find out the value of the variable */ /******************************************************************/ /* read the global variable... */ Cnmvars(GET, /* ...function is read */ &datain, /* ...data goes here */ length, /* ...truncate after 24 bytes */ &variable, /* ...variable name */ CGLOBAL); /* ...variable pool is cglobal */ /* show operator value... */ Cnmsmsg(&datain, /* ...data obtained from varpool */ MSG, /* ...type is message */ OPER, /* ...send message to operator */ NULLCHAR); /* ...not used */

/* put new value in varying length */ Cnmvlc(&datain, /* character string... */ 0, /* ...do not convert to hex */ "New Value"); /* ...new value */

/******************************************************************/ /* set the global variable */ /******************************************************************/ /* update the global variable... */ Cnmvars(PUT, /* ...function is write */ &datain, /* ...data is here */ length, /* ...datalen is not used */ &variable, /* ...variable name */ CGLOBAL); /* ...variable pool is CGLOBAL */ /******************************************************************/ /* verify variable has been changed */ /******************************************************************/ /* read the global variable ... */ Cnmvars(GET, /* ...function is read */ &datain, /* ...data goes here */ length, /* ...truncate after 24 bytes */ &variable, /* ...variable name */ CGLOBAL); /* ...variable pool is CGLOBAL */ /* show value to operator ... */ Cnmsmsg(&datain, /* ...data to be displayed */ MSG, /* ...type is message */ OPER, /* ...send message to operator */ NULLCHAR); /* ...not used */

/******************************************************************/ /* Release the lock to let other tasks update GVARIABLE */ /******************************************************************/ Cnmlk(UNLOCK, /* obtain the lock... */ &variable, /* ...function is obtain lock */ " ", /* ...not used */ " "); /* ...not used */ if (Hlbptr->Hlbrc == 0) } else { Cnmsmsg(Cnmvlc(&msg,0,"lock not gotten"),MSG,OPER,NULLCHAR); }

Operator input “Operator input (C)” on page 135 shows how to code an HLL command processor to accept operator input in single-line mode. The interface is similar to the &PAUSE function of the NetView command list language. Input is requested by the application using the WAIT FOR OPINPUT command, and retrieved by the

134 Programming: PL/I and C C High-Level Language Services application using the CNMGETD service routine. The operator can respond using the GO command. See “GO command” on page 177 for more information. Operator input (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsivarch msgbuf, /* var len char strng for messages */ command, /* var len char strng for cmds */ inbuf; /* store data returned by Cnmgetd */

/******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/ /* copy message into varying */ Cnmvlc(&msgbuf, /* length message string... */ 0, /* ... do not convert to hex */ "Enter operator input data"); /* ... message */ /* send a message... */ Cnmsmsg(&msgbuf, /* ...text of message */ MSG, /* ...single line message */ OPER, /* ...to the invoking oper */ NULLCHAR); /* ...not used */ /* copy command to varying */ Cnmvlc(&command, /* length character string...*/ 0, /* ...do not convert to hex */ "WAIT 30 SECONDS FOR OPINPUT"); /* ...command */ /* issue command to wait for */ Cnmcmd(&command); /* 30 seconds... */ /* get first trapped msg... */ if (Hlbptr->Hlbrc == CNM_OPINPUT_ON_WAIT) { /* Operator input supplied...*/ Cnmgetd(GETMSG, /* ...function is get message*/ &inbuf, /* ...result goes here */ 255, /* ...max input length */ Origblck, /* ...must provide work area */ 2, /* ...msg is on OPINPUT queue*/ 1); /* ...get the first one */

inbuf.buffer??(inbuf.size??) = ’\0’; /* copy opinput into varying */ Cnmvlc(&msgbuf, /* length character string...*/ 0, /* ...do not convert to hex */ "OPERATOR INPUT IS: %s",inbuf.buffer); /* ...message */ /* send a message... */ Cnmsmsg(&msgbuf, /* ...text of message */ MSG, /* ...single line message */ OPER, /* ...to the invoking oper */ NULLCHAR); /* ...not used */ } else { /* No operator input supplied*/ /* copy message into varying */ Cnmvlc(&msgbuf, /* length character string...*/ 0, /* ...do not convert to hex */ "NO OPERATOR INPUT SUPPLIED"); /* ... message */ /* send a message... */ Cnmsmsg(&msgbuf, /* ...text of message */ MSG, /* ...single line message */ OPER, /* ...to the invoking oper */ NULLCHAR); /* ...not used */ }

Chapter 9. C high-level language services 135 C High-Level Language Services

VIEW command processor “Using the full-screen view (C)” is an example of using the full-screen VIEW command processor. The example creates and initializes the local variable called parm1. The VIEW command processor is started and displays a full-screen panel. For more information, refer to the IBM Tivoli NetView for z/OS Customization Guide. Using the full-screen view (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsivarch variable, /* store variable name for Cnmvars */ data, /* store returned data from Cnmvars*/ command; /* varying len char strng for cmds */

Cnmvars(DCL, /* declare variable to local pool...*/ &data, /* ...not used */ 48, /* ...not used */ &variable, /* ...name is parm1 */ LOCAL); /* ...the pool is local */ /* copy initialization data to */ Cnmvlc(&data, /* varying length character strng.. */ 0, /* ...do not convert to hex */ "the contents of parm1 go here"); /* ...the data */

Cnmvars(PUT, /* initialize parm1... */ &data, /* ...result goes here */ 48, /* ...max length is 48 bytes */ &variable, /* ...name of variable is parm1 */ LOCAL); /* ...the pool is local */

/******************************************************************/ /* Issue the view command. Give the task name as a unique name */ /* to go on the View stack. */ /******************************************************************/ /* copy command to varying length */ Cnmvlc(&command, /* character string... */ 0, /* ...do not convert to hex */ "VIEW %.8s TESTHLL INPUT",Origblck->Orig_task); /* cmd*/

Cnmcmd(&command); /* issue the command */

Figure 5 on page 137 shows the panel definition that is started by this example:

136 Programming: PL/I and C C High-Level Language Services

Figure 5. Sample Full-Screen View

Message processing “Message processing (C)” lists the message attributes of a message. The invocation must be a result of an entry in the NetView automation table. This example functions for both single-line and multiline messages. Refer to the IBM Tivoli NetView for z/OS Automation Guide for more information. Message processing (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsiorig getblock; /* orig block for Cnmgetd */ Dsivarch inbuf, /* returned data from Cnmgetd */ datain, /* returned data from Cnmgeta */ message, /* var len char strng for messages */ temp; /* temp var len char strng used... */ /* ...to build messages */ int i; /* counter */ char *attr??(12??) = { /* array of message attributes... */ "AREAID ", /* ...to be obtained by Cnmgeta */ "DESC ", "JOBNAME ", "JOBNUM ", "MCSFLAG ", "MSGTYP ", "REPLYID ", "ROUTCDE", "SESSID ", "SMSGID ", "SYSCONID", "SYSID "}; /******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/ Cnmgetd(GETMSG, /* ...function is get a message */ &inbuf, /* ...result goes here */

Chapter 9. C high-level language services 137 C High-Level Language Services

255, /* ...max input length */ &getblock, /* ...must provide a work area */ IDATAQ, /* ...message on automation queue */ 1); /* ...get the next line */ while((Hlbptr->Hlbrc==CNM_GOOD) ¦¦ (Hlbptr->Hlbrc==CNM_DATA_TRUNC)) { /* do while no probs... */ /* ...ignoring truncation */ for(i=0;i<=11;i++) /* for 12 possible attributes... */ { /* get the ith attribute... */ Cnmgeta(attr??(i??), /* ...ith member of the array */ &datain, /* ...result goes here */ 12, /* ...at most 12 bytes */ IDATAQ); /* ...on initial data queue */ /* put result of above cnmgeta in */ Cnmnvlc(&temp, /* varying length char string... */ 0, /* ...do not convert to hex */ datain.size, /* ...size of result */ datain.buffer); /* ...result to be copied */ /* build msg to display results in */ Cnmvlc(&message, /* varying length char string... */ 0, /* ...do not convert to hex */ "%s = %s",attr??(i??),temp.buffer); /* ...message */ /* print that message... */ Cnmsmsg(&message, /* ...message text */ MSG, /* ...single line message */ OPER, /* ...to invoking operator */ NULLCHAR); /* ...not used */ } Cnmvlc(&message,0,"LINETYPE = %c",getblock.Orig_line_type); Cnmsmsg(&message,MSG,OPER,NULLCHAR); Cnmvlc(&message,0,"HDRMTYPE = %c",getblock.Orig_msg_type); Cnmsmsg(&message,MSG,OPER,NULLCHAR); Cnmvlc(&message,0,"MSGID = %.8s",getblock.Orig_process); /* orig fields not NULL.. */ /* ...terminated */ Cnmsmsg(&message,MSG,OPER,NULLCHAR); inbuf.buffer??(inbuf.size??) = ’\0’; /* append NULL to end of */ /* ...data retrieved by Cnmgetd */

Cnmvlc(&message,0,"MSGSTR = %s",inbuf.buffer); Cnmsmsg(&message,MSG,OPER,NULLCHAR);

/* get first trapped message... */ Cnmgetd(GETLINE, /* ...function is get a message */ &inbuf, /* ...result goes here */ 255, /* ...max input length */ &getblock, /* ...must provide a work area */ IDATAQ, /* ...message is from automation */ 1); /* ...get the next line */ } Hlbptr->Hlbrc == CNM_GOOD;

Command authorization checking This section describes an example of the command authorization checking capabilities provided by the NetView program. Define the operator, the operator's authority, and the restrictions on starting the command, keyword, and value.

The command gives the return code that the command authorization checking service routine returned to the operator.

This command checks for this syntax:

138 Programming: PL/I and C C High-Level Language Services

CSCOPCK

►► CSCOPCK PARM x ( VAL x ) ►◄

Where: PARMx Specifies the keyword variable used to perform authorization checking. VALx Indicates the value variable used to perform authorization checking.

Before using the example in “Command Authorization Checking (C)” on page 140, perform up the following NetView set-up, depending upon the method chosen for command authorization checking: Command authorization checking using CMDAUTH=TABLE If you are using CMDAUTH=TABLE with TBLNAME=CMDTABLE in NetView domain CNM01 in network NETA, perform the following set-up before using the sample code in “Command Authorization Checking (C)” on page 140. In DSIPARM(CMDTABLE) Restrict access to the command, keywords, and values as well as the operators and classes that can access them.

The command CSCOPCK can be run by operators in GRP1 and GRP2. Operators in GRP1 can issue any keyword or keyword value, but operators in GRP2 cannot use the value of VAL1 with keyword PARM2 and cannot issue PARM3 at all. PROTECT NETA.CNM01.CSCOPCK PROTECT NETA.CNM01.CSCOPCK.PARM2 PROTECT NETA.CNM01.CSCOPCK.PARM2.VAL1 PROTECT NETA.CNM01.CSCOPCK.PARM3 PROTECT NETA.CNM01.CSCOPCK.PARM3.VAL1 GROUP GRP1 OPER1,OPER2,FRANK,BILL,JENNY GROUP GRP2 OPER3,OPER4,FRED,LISA,BETH GROUP GRP3 JOE PERMIT GRP1 NETA.CNM01.CSCOPCK PERMIT GRP1 NETA.CNM01.CSCOPCK.PARM2 PERMIT GRP1 NETA.CNM01.CSCOPCK.PARM2.VAL1 PERMIT GRP1 NETA.CNM01.CSCOPCK.PARM3 PERMIT GRP1 NETA.CNM01.CSCOPCK.PARM3.VAL1 PERMIT GRP2 NETA.CNM01.CSCOPCK PERMIT GRP2 NETA.CNM01.CSCOPCK.PARM2 Command authorization checking Using CMDAUTH=SAF If you are using CMDAUTH=SAF and OPERSEC=SAFDEF in NetView domain CNM01 in network NETA, perform the following set-up before using the sample code in “Command Authorization Checking (C)” on page 140. RACF is used as the SAF product in this example. In RACF Restrict access to the command, keywords, and values as well as the operators and classes that can access them.

Chapter 9. C high-level language services 139 C High-Level Language Services

RDEFINE NETCMDS NETA.CNM01.CSCOPCK UACC(NONE) RDEFINE NETCMDS NETA.CNM01.CSCOPCK.PARM2 UACC(NONE) RDEFINE NETCMDS NETA.CNM01.CSCOPCK.PARM2.VAL1 UACC(NONE) RDEFINE NETCMDS NETA.CNM01.CSCOPCK.PARM3 UACC(NONE) RDEFINE NETCMDS NETA.CNM01.CSCOPCK.PARM3.VAL1 UACC(NONE) ADDGROUP GRP1 ADDGROUP GRP2 ADDGROUP GRP3 CONNECT OPER1 GROUP(GRP1) CONNECT OPER2 GROUP(GRP1) CONNECT FRANK GROUP(GRP1) CONNECT BILL GROUP(GRP1) CONNECT JENNY GROUP(GRP1) CONNECT OPER3 GROUP(GRP2) CONNECT OPER4 GROUP(GRP2) CONNECT FRED GROUP(GRP2) CONNECT LISA GROUP(GRP2) CONNECT BETH GROUP(GRP2) CONNECT JOE GROUP(GRP3) PERMIT NETA.CNM01.CSCOPCK CLASS(NETCMDS) ID(GRP1) ACCESS(READ) PERMIT NETA.CNM01.CSCOPCK.PARM2 CLASS(NETCMDS) ID(GRP1) ACCESS(READ) PERMIT NETA.CNM01.CSCOPCK.PARM2.VAL1 CLASS(NETCMDS) ID(GRP1) ACCESS(READ) PERMIT NETA.CNM01.CSCOPCK.PARM3 CLASS(NETCMDS) ID(GRP1) ACCESS(READ) PERMIT NETA.CNM01.CSCOPCK.PARM3.VAL1 CLASS(NETCMDS) ID(GRP1) ACCESS(READ) PERMIT NETA.CNM01.CSCOPCK CLASS(NETCMDS) ID(GRP2) ACCESS(READ) PERMIT NETA.CNM01.CSCOPCK.PARM2 CLASS(NETCMDS) ID(GRP2) ACCESS(READ) Command authorization checking sample code Command Authorization Checking (C) /*******************************************************************/ /* Internal data definitions */ /*******************************************************************/ Dsivarch msgbuf; /* Buffer area for messages */ char *cn; /* Ptr to cmd that invoked us */ char *kw; /* Ptr to keyword of invocation */ char *kv; /* Ptr to keyvalue of invocation*/ char *token; /* Ptr to keyvalue of invocation*/ char cmdname??(9??) = " ";/* Command that invoked us */ char keyword??(9??) = " ";/* Keyword of invocation */ char keyvalue??(9??)= " ";/* Keyvalue of invocation */ int len; /* Length */ /*******************************************************************/ /* */ /* Execution */ /* */ /*******************************************************************/ /*******************************************************************/ /* Scan the keyword and the value */ /*******************************************************************/ /* Syntax of command is: */ /* CMDNAME KEYWORD(KEYVALUE) */ /* Parse the command buffer for: */ token = strtok((char *) &(Cmdbuf->buffer)," "); /* ...COMMAND */ if (token != NULL) { len = strlen(token); /* Get length of command name */ strcpy(cmdname,token); /* Save command name */ if (len < 8) /* Pad with blanks? */ strncat(cmdname," ",8 - len); } token = strtok(NULL,"("); /* ...keyword */ if (token != NULL) { len = strlen(token); /* Get length of keyword */ strcpy(keyword,token); /* Save keyword */ if (len < 8) /* Pad with blanks? */

140 Programming: PL/I and C C High-Level Language Services

strncat(keyword," ",8 - len); } token = strtok(NULL,")"); /* ...value */ if (token != NULL) { len = strlen(token); /* Get length of keyvalue */ strcpy(keyvalue,token); /* Save keyvalue */ if (len < 8) /* Pad with blanks? */ strncat(keyvalue," ",8 - len); } if (token != NULL) /* enough parms? */ /* Perform authorization checking */ Cnmscop(cmdname, /* ...the command */ keyword, /* ...the keyword */ keyvalue); /* ...the value */ else /* not enough parms specified */ Hlbptr->Hlbrc = CNM_BAD_INVOCATION; /* set bad rc */ /*******************************************************************/ /* Inform user of the return code results... */ /*******************************************************************/ if (Hlbptr->Hlbrc == CNM_BAD_INVOCATION) { Cnmvlc(&msgbuf,0,"Not enough parms specified"); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); } else if (Hlbptr->Hlbrc == CNM_GOOD) { Cnmvlc(&msgbuf,0,"Operator has passed authorization checking"); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); } else if (Hlbptr->Hlbrc == CNM_KEYWORD_NA) { Cnmvlc(&msgbuf,0,"Not authorized to use KEYWORD %s", keyword); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); } else if (Hlbptr->Hlbrc == CNM_VALUE_NA) { Cnmvlc(&msgbuf,0,"Not authorized to use value %s", keyvalue); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); } else { Cnmvlc(&msgbuf,0,"RC not recognized...%d",Hlbptr->Hlbrc); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); } Hlbptr->Hlbrc == CNM_GOOD; /* clear return code */

Altering data The DSIEX02A installation exit routine, shown in “Altering data (C)” on page 142, changes the echoed command message (MSGTYPE=*) to be more informative by giving the time that the command was entered.

Without the installation exit, if you enter the WHO command, the output is in the following format: WHO

With the exit, the output is in the following format: Command entered was: "WHO" at 12:00:00

Chapter 9. C high-level language services 141 C High-Level Language Services

Altering data (C) /********************************************************************/ /* */ /* Descriptive Name: High Level Language C Dsiex02a Example */ ...... /* Change Activity: */ /* date,author: description of changes */ /********************************************************************/ #pragma runopts (NOEXECOPS,NOSTAE,NOSPIE,ISASIZE(4K),ISAINC(4K)) /********************************************************************/ /* Standard include files*/ /********************************************************************/ #include /* Standard library */ #include /* Standard args */

/********************************************************************/ /* NetView high level language include files */ /********************************************************************/ #include "dsic.h" /* Include HLL macros */

/********************************************************************/ /* External data definitions */ /********************************************************************/ Dsihlb *Hlbptr; /* Pointer to the HLB */ Dsivarch *Cmdbuf; /* Pointer to command buffer */ Dsiorig *Origblck; /* Pointer to Origin block */ main(int argc, char *argv??(??)) { /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsiorig getblock; /* Area for the Origin Block */ Dsivarch datain; /* Old command text */ Dsivarch time; /* Area for time */ Dsivarch msgbuf; /* message buffer */ /******************************************************************/ /* Convert operand pointers from character to hex addresses */ /******************************************************************/ sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck); /******************************************************************/ /* Initialization */ /******************************************************************/

/******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/ /* Retrieve the time... */ Cnminfc ("TIME ", /* ...variable is time of day */ &time, /* ...the result goes here */ 255); /* ...max length of 255 */ /* Peek the msg before altering */ Cnmgetd(PEEKLINE, /* ...subfunction is peek */ &datain, /* ...result goes here */ 255, /* ...max length is 255 */ &getblock, /* ...use new Origin block */ IDATAQ, /* ...initial data queue (4) */ 1); /* ...check the first line */ datain.buffer??(datain.size??) = ’\0’; /* put null at end of data*/ /* Echo’ed message? */ if (getblock.Orig_msg_type == ’*’) {

142 Programming: PL/I and C C High-Level Language Services

Cnmvlc(&msgbuf,0,"Command entered was: %s at %.8s",datain.buffer, time.buffer); /* Replace the text... */ Cnmaltd(REPLINE, /* ...subfunction is replace */ &msgbuf, /* ...text of new message */ &getblock, /* ...used peeked Origin block */ IDATAQ, /* ...initial data queue */ 1); /* ...replace the first line */ } Hlbptr->Hlbrc = CNM_GOOD; /* clear rc */ }

Storage access “Displaying contents of storage (C)” shows how to display the character representation of the contents of the storage that the NetView program can access. For example, after locating the address of the main vector table using DISPMOD DSIMNTEX, you can display the first 4 bytes of the DSIMVT control block. Displaying contents of storage (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ int numparms; /* Number of parms scanned */ int *xaddr; /* Hex value of srce_ptr */ int numbytes; /* Number of bytes to display */ char *inbufr_p; char inputbfr??(4097??) = " "; /* Buffer where data is copied */ char *srceptr; /* Address to copy from */ int i,x; /* Work counter */ Dsivarch msgbuf; /* Buffer for Cnmsmsg */

/******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/ inbufr_p = inputbfr; numbytes = 0; numparms = sscanf((char *) &(Cmdbuf->buffer), /* parse cmd buffer */ "%*s%x%x", /* Format string */ &xaddr, /* The address to display */ &numbytes); /* For this number of bytes */ if (numparms != 2) /* Address and length given ? */ { Cnmvlc(&msgbuf,0,"Invalid number of operands"); Cnmsmsg(&msgbuf, /* No, display error message... */ MSG, /* ...message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ Hlbptr->Hlbrc = 1; /* set return code */ return; /* Terminate processing */ } if (numbytes <= 0) /* A valid length given? */ { Cnmvlc(&msgbuf,0,"Invalid length given"); Cnmsmsg(&msgbuf, /* No, display error message... */ MSG, /* ...message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ Hlbptr->Hlbrc = 1; /* set return code */ return; /* Terminate processing */ } if (numbytes >= 4096) /* A valid length given? */

Chapter 9. C high-level language services 143 C High-Level Language Services

{ Cnmvlc(&msgbuf,0,"Invalid length given, must be less than FFF"); Cnmsmsg(&msgbuf, /* No, display error message... */ MSG, /* ...message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ Hlbptr->Hlbrc = 1; /* set return code */ return; /* Terminate processing */ } if (xaddr != NULL) /* If valid address then... */ { /* Copy storage... */ Cnmcpys(&xaddr, /* ...from the address given */ &inbufr_p, /* ...to the internal buffer */ numbytes, /* ...for up to FFF bytes */ FIXTOFIX); /* ...data is fixed length type */

if (Hlbptr->Hlbrc == CNM_GOOD) /* Good rc? */ { for(i=1; i <= (x=ceil(numbytes/64.0)*64); i = i + 64) { if (((numbytes - i) + 1) >= 64) { memmove(msgbuf.buffer,inputbfr+(i-1),64); msgbuf.size = 64; } else { memmove(msgbuf.buffer,inputbfr+(i-1),numbytes % 64); msgbuf.size = numbytes % 64; } Cnmsmsg(&msgbuf, /* Display 64 bytes of storage...*/ MSG, /* ...message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ } } else /* Else bad return code */ { Cnmvlc(&msgbuf,0,"Invalid or protected address"); Cnmsmsg(&msgbuf, /* Send error message... */ MSG, /* ...message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ } }

Data set access “Data set access (C)” contains sample code for opening (CNMMEMO), reading (CNMMEMR), and closing (CNMMEMC) NetView partitioned data sets. This example reads the CNMSTYLE member and displays the contents to the operator. Data set access (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ int token; /* Token used to match open to */ /* ...read and close */ Dsivarch msgbuf; /* Line that is read */

/******************************************************************/ /* Open the member */ /******************************************************************/ /* Open the data set member... */

144 Programming: PL/I and C C High-Level Language Services

Cnmmemo(&token, /* ...token returned by Cnmmemo */ "DSIPARM ", /* ...ddname of PDS */ "CNMSTYLE"); /* ...member name of PDS */ if (Hlbptr->Hlbrc != CNM_GOOD) { Cnmvlc(&msgbuf, /* Put error message in msgbuf... */ 0, /* ...do not convert to hex */ "OPEN FOR DATASET FAILED RC= %d",Hlbptr->Hlbrc); /* msg */ /* Send message... */ Cnmsmsg(&msgbuf, /* ...member in DDNAME not found */ MSG, /* ...single line message */ OPER, /* ...to the operator */ NULLCHAR); /* ...taskname ignored */ } else { /******************************************************************/ /* Read the member */ /******************************************************************/ /* Read the first record... */ Cnmmemr(token, /* ...provide token from OPEN */ &msgbuf, /* ...result goes here */ 80); /* ...read 80 bytes */

while (Hlbptr->Hlbrc == CNM_GOOD) /* Read until EOF */ { msgbuf.size = 72; /* only write 72 bytes of record */ /* Write out last record read... */ Cnmsmsg(&msgbuf, /* ...write first 72 bytes */ MSG, /* ...single line message */ OPER, /* ...to the operator */ NULLCHAR); /* ...taskname ignored */ /* Read the next record... */ Cnmmemr(token, /* ...provide token from OPEN */ &msgbuf, /* ...result goes here */ 80); /* ...read 80 bytes */ } /******************************************************************/ /* Close the member */ /******************************************************************/ /* Close the PDS member... */ Cnmmemc(token); /* ...provide token from OPEN */ }

Communicating with devices The NetView program provides the CNMCNMI service routine for use in communicating with devices in the network through the CNMI. Any returned data can be accessed using the Cnmgetd service routine to retrieve records from the CNMI solicited data queue (CNMIQ).

“CNMCNMI (C)” on page 146 uses the Cnmcnmi service routine to send a product set ID data request to a specified PU. Any data returned is sent as a message to the operator.

The command syntax is:

Chapter 9. C high-level language services 145 C High-Level Language Services

CCNMI

OWN ►► CCNMI puname ►◄ ALL

Where: ALL Specifies that vital product data is to be retrieved for the PU and its attached ports. OWN Specifies that vital product data is to be retrieved for the PU only. This keyword is the default. puname Is the name of the PU from which the vital product data is retrieved. This parameter is required. CNMCNMI (C) /********************************************************************/ /* External data definitions */ /********************************************************************/ typedef struct { short size; char buffer??(1025??); } Bigvlc; main(int argc, char *argv??(??)) { /******************************************************************/ /* Internal data definitions */ /******************************************************************/ int rcode; /* Return code */ int count; /* Count of scanned args */ Dsivarch puname; /* puname varying length */ Dsivarch msgbuf; /* Message buffer */ Dsiorig getblock; /* Area for the work orig block */ Bigvlc datain; /* Buffer for the RU */ char ownorall??(4??); /* Own or all placeholder */ Dsivarch fwdru; /* Forward RU */ Dsivarch ru; /* RU data */ Dsivarch own; /* 81 if own specified */ Dsivarch all; /* 83 if all specified */ Dsivarch puhdr; /* puname header */ Dsivarch endofru; /* end of RU */ char *ptr; /* ptr used to build fwdru */ /********************************************************************/ /* */ /* Vital Product Data RU definitions */ /* */ /* From the VTAM Programming Manual, a forward RU is defined below */ /* */ /* Byte Value Description */ /* 0 81 Network services, logical services */ /* 1 08 Management services */ /* 2 10 Request code */ /* 3 00 Format 0 */ /* 4 00 Ignore target names, */ /* Solicit a reply, and */ /* No CNM header contained */ /* 5 00 Reserved */

146 Programming: PL/I and C C High-Level Language Services

/* 6-7 000E Length of NS RU */ /* 8-15 NS RU -- NMVT -- documented in SNA Ref Sum */ /* 8-A 41038D NS Header for NMVT */ /* B-C 0000 Retired */ /* D-E 0111 PRID */ /* F 00 unsolicited NMVT, */ /* only NMVT for this PRID */ /* 10-16 One MS major vector */ /* 10-11 0006 Length field of PSID (Product Set ID) vector */ /* 12-13 8090 Code point for PSID */ /* 14-15 Length of subvector */ /* 14 02 Length of subvector */ /* 15 81 Request information on control unit only */ /* 15 83 Request information on control unit and its */ /* attached devices */ /* 16 F1 From VTAM programming, PU */ /* 17 08 Length of PU name */ /* 18 PUNAME Eight byte PUNAME, left justified */ /* 20 00 End of RU */ /********************************************************************/

/******************************************************************/ /* Initialization */ /******************************************************************/ Cnmvlc(&ru,1,"810810000000000E41038D00000111000006809002"); Cnmvlc(&own,1,"81"); Cnmvlc(&all,1,"83"); Cnmvlc(&puhdr,1,"F108"); Cnmvlc(&endofru,1,"00"); rcode = 0; /******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/ ptr = (char *) &fwdru.buffer; count = sscanf((char *) &(Cmdbuf->buffer),"%*s%s%s", puname.buffer,ownorall); puname.size = strlen(puname.buffer); if (puname.size < 8) /* Pad with blanks if needed */ strncat(puname.buffer," ",8 - puname.size); if ((count == 1) ¦¦ (strncmp(ownorall,"OWN",3) == 0)) { memmove(ptr,ru.buffer,ru.size); ptr=ptr+ru.size; memmove(ptr,own.buffer,own.size); ptr=ptr+own.size; memmove(ptr,puhdr.buffer,puhdr.size); ptr=ptr+puhdr.size; memmove(ptr,puname.buffer,puname.size); ptr=ptr+puname.size; memmove(ptr,endofru.buffer,endofru.size); fwdru.size = ru.size+own.size+puhdr.size+puname.size+endofru.size; } else if (strncmp(ownorall,"ALL",3) == 0) /* ALL specified */ { memmove(ptr,ru.buffer,ru.size); ptr=ptr+ru.size; memmove(ptr,all.buffer,all.size); ptr=ptr+all.size; memmove(ptr,puhdr.buffer,puhdr.size); ptr=ptr+puhdr.size; memmove(ptr,puname.buffer,puname.size); ptr=ptr+puname.size; memmove(ptr,endofru.buffer,endofru.size); fwdru.size = ru.size+all.size+puhdr.size+puname.size+endofru.size;

Chapter 9. C high-level language services 147 C High-Level Language Services

} else /* Else invalid parm inform user */ { Cnmvlc(&msgbuf,0,"Invalid command syntax"); Cnmsmsg(&msgbuf,MSG,TASK,Origblck->Orig_task); rcode = 8; } if (rcode == 0) { /* Good so far? */ /* Send RU over the CNMI... */ Cnmcnmi(SENDRPLY, /* ...expect a reply */ &fwdru, /* ...RU built above */ puname.buffer, /* ...to the PU name specified */ 180); /* ...timeout after 3 minutes */ if (Hlbptr->Hlbrc == CNM_GOOD)/* Everything ok? */ { /* Yes, continue */ /* Read in the first RU returned */ Cnmgetd(GETLINE, /* ...a single RU */ &datain, /* ...inti here */ 1024, /* ...truncate after 1024 bytes */ &getblock, /* ...provide a new origin block */ CNMIQ, /* ...on the CNMI queue (5) */ 1); /* ...the first RU */ while (Hlbptr->Hlbrc == 0) /* End of queue reached? */ { /* Send info to the operator... */ Cnmsmsg(&datain, /* ...from here */ MSG, /* ...issue message */ TASK, /* ...to the task */ Origblck->Orig_task); /* ...that originated request */ /* Read in the next RU returned */ Cnmgetd(GETLINE, /* ...a single RU */ &datain, /* ...inti here */ 1024, /* ...truncate after 1024 bytes */ &getblock, /* ...provide a new origin block */ CNMIQ, /* ...on the CNMI queue (5) */ 1); /* ...the first RU */ } } else /* CNMI error */ { /* Not invoked under a DST */ if (Hlbptr->Hlbrc == CNM_BAD_INVOCATION) Cnmvlc(&msgbuf, /* Buffer for message text */ 0, /* Do not convert to hex */ "Must run under a DST"); /* Error message */ else /* PU never answered request */ if (Hlbptr->Hlbrc == CNM_TIME_OUT) Cnmvlc(&msgbuf, /* Buffer for message text */ 0, /* Do not convert to hex */ "PU never answered"); /* Error message */ else /* PU gave a negative response */ if (Hlbptr->Hlbrc == CNM_NEG_RESPONSE) Cnmvlc(&msgbuf, /* Buffer for message text */ 0, /* Do not convert to hex */ "PU gave negative response"); else /* Cnmi failure */ Cnmvlc(&msgbuf, /* Buffer for message text */ 0, /* Do not convert to hex */ "CNMI request failed rc = %d", Hlbptr->Hlbrc); /* Rc from CNMI routine */

Cnmsmsg(&msgbuf, /* Send error message to user... */ MSG, /* ...single line message */

148 Programming: PL/I and C C High-Level Language Services

TASK, /* ...dest. type task */ Origblck->Orig_task); /* ...dest. ID origin task */

} /* End of CNMI error */ } /* End of Good so far */ Hlbptr->Hlbrc = rcode; /* Issue rc */

Performing I/O on a VSAM File (Keyed File Access) The following code for a NetView HLL command processor allows input or output (I/O) to a VSAM file through the Cnmkio service routine.

The command processor must run on a DST. Use either the Cnmsmsg service routine (with a type of COMMAND), or the EXCMD command.

“VSAM Keyed File Access (C)” creates a database with five records and these keys and data: Key Data 01 A 02 B 03 C 04 D 05 E VSAM Keyed File Access (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsivarch rec; /* store output data for Cnmkio */ Dsivarch inrec; /* store data returned by Cnmkio */ Dsivarch key; /* store key for Cnmkio */ Dsivarch msg; /* store messages to be displayed*/ char outdata??(6??) = "ABCDE"; /* output data */ char keydata??(11??) = "0102030405"; /* data for building keys */ char *keyptr; /* pointer to key data */ char *outptr; /* pointer to output data */ int i; /* counter */

/******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/ /******************************************************************/ /* WRITE OUT 5 RECORDS... */ /* */ /* PUT DIRECT must be used for new records, and PUT UPDATE */ /* must be used for old records. Therefore, we will use GET */ /* EQual to determine if the record is new or not. If new, */ /* then a PUT DIRECT will follow...if not, then a put update */ /* follows. */ /* */ /******************************************************************/ keyptr = keydata; outptr = outdata; for (i = 0; i <= 4; i++) /* For 5 records */ { memmove(key.buffer,keyptr,2);/* Set key portion of record */ key.size = 2; /* Set size of key buffer */

Chapter 9. C high-level language services 149 C High-Level Language Services

keyptr = keyptr+2; /* Get next key in table */ memmove(rec.buffer,key.buffer,2); /* Record must have key 1st */ memmove(rec.buffer+2,outptr,1);/* attach data to key */ rec.size = 3; /* Set size of record */ outptr = outptr+1; /* Set pointer to record */

/* Call KEYIO... */ Cnmkio(GET_EQ, /* ...requesting a get */ &inrec, /* ...data goes in here */ 10, /* ...10 bytes max input */ &key, /* ...key is in key */ UPDATE); /* ...this is an update */ if (Hlbptr->Hlbrc == CNM_NOT_FOUND) /* Call KEYIO... */ Cnmkio(PUT, /* ...requesting a put */ &rec, /* ...data goes in here */ 0, /* ...not used */ &key, /* ...key is in key */ DIRECT); /* ...this is an update */ else /* Call KEYIO... */ Cnmkio(PUT, /* ...requesting a put */ &rec, /* ...data goes in here */ 0, /* ...not used */ &key, /* ...key is in key */ UPDATE); /* ...this is an update */

if (Hlbptr->Hlbrc != CNM_GOOD) { /* if put failed */ /* put message in varying length */ Cnmvlc(&msg, /* character string... */ 0, /* do not convert to hex */ "Cnmkeyio PUT request failed with RC: %d",Hlbptr->Hlbrc); /* put out error message... */

Cnmsmsg(&msg, /* ...message text */ MSG, /* ...type is message */ OPER, /* ...send to issuing operator */ NULLCHAR); /* ...not used */ } } /******************************************************************/ /* Read in the 5 records... */ /******************************************************************/ keyptr = keydata; for (i = 0; i <= 4; i++) /* For 5 records */ { memmove(key.buffer,keyptr,2); /* Set key portion of record */ key.size = 2; keyptr = keyptr+2; /* Call KEYIO... */ Cnmkio(GET_EQ, /* ...requesting a put */ &inrec, /* ...data goes in here */ 10, /* ...not used */ &key, /* ...key is in key */ NOUPDATE); /* ...this is an not update */

inrec.buffer??(inrec.size??) = ’\0’; /* add NULL to end of */ /* ...data */ Cnmvlc(&msg,0,"Key: %.2s Record: %s",key.buffer,inrec.buffer); Cnmsmsg(&msg,MSG,SYSOP,NULLCHAR);/* display key and record */ } Hlbptr->Hlbrc = CNM_GOOD; /* Issue clean rc */

150 Programming: PL/I and C C High-Level Language Services

Coding a DST installation exit “Coding a DST installation exit (C)” shows coding a NetView HLL installation exit routine that primes an empty VSAM database for a data services task (DST). If a VSAM database is not primed (has at least one record), subsequent input and output (I/O) requests fail. Coding a DST installation exit (C) /********************************************************************/ /* */ /* Descriptive Name: High Level Language C XITVN Example */ ...... /* Change Activity: */ /* date,author: description of changes */ /********************************************************************/ #pragma runopts( STACK(128K,128K,ANY,FREE) HEAP(128K,128K,ANY,FREE,8,0) ) #pragma runopts( BELOWHEAP(8,0,FREE) LIBSTACK(8,0,FREE) ) #pragma runopts( INTERRUPT(OFF) NOTEST(ALL,*,* ) STORAGE(,,,0) ) #pragma runopts( TRAP(OFF) MSGQ(1) ALL31(ON) ) /********************************************************************/ /* Standard include files */ /********************************************************************/ #include /* String functions */ #include /* String functions */ #include /* String functions */ /********************************************************************/ /* NetView high level language include files */ /********************************************************************/ #include "dsic.h" /* Include HLL macros */ /********************************************************************/ /* External data definitions */ /********************************************************************/ Dsihlb *Hlbptr; /* Pointer to the HLB */ Dsivarch *Cmdbuf; /* Pointer to command buffer */ Dsiorig *Origblck; /* Pointer to Origin block */

main(int argc, char *argv??(??)) { /******************************************************************/ /* Internal data definitions */ /******************************************************************/ /******************************************************************/ /* Convert operand pointers from character to hex addresses */ /******************************************************************/ sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck); /******************************************************************/ /* Initialization */ /******************************************************************/

memmove((&(Cmdbuf->buffer??(0??))+2), /* Set rest of key... */ "low rec",7); /* ...move in 7 bytes */

Chapter 9. C high-level language services 151 C High-Level Language Services

Cmdbuf->size = 9; /* set new Cmdbuf size */

Hlbptr->Hlbrc = USERSWAP; /* Set USERSWAP rc */ }

Coding an installation exit “Coding installation exit (C)” shows coding an installation exit routine, DSIEX03, that sets a task global variable equal to the last time a command was entered on the system. If the last command was the CSNDDAT command, the task global variable is not set. The CSNDDAT command (see “Sending data” on page 156) receives the variable value. Coding installation exit (C) /********************************************************************/ /* */ /* Descriptive Name: High Level Language PL/I DSIEX03 Example */ ...... /* Change Activity: */ /* date,author: description of changes */ /* */ /********************************************************************/ #pragma runopts( STACK(128K,128K,ANY,FREE) HEAP(128K,128K,ANY,FREE,8,0) ) #pragma runopts( BELOWHEAP(8,0,FREE) LIBSTACK(8,0,FREE) ) #pragma runopts( INTERRUPT(OFF) NOTEST(ALL,*,* ) STORAGE(,,,0) ) #pragma runopts( TRAP(OFF) MSGQ(1) ALL31(ON) ) /********************************************************************/ /* Standard include files */ /********************************************************************/ #include /* Standard library */ #include /* Standard args */ /********************************************************************/ /* NetView high level language include files */ /********************************************************************/ #include "dsic.h" /* Include HLL macros */ /********************************************************************/ /* External data definitions */ /********************************************************************/ Dsihlb *Hlbptr; /* Pointer to the HLB */ Dsivarch *Cmdbuf; /* Pointer to command buffer */ Dsiorig *Origblck; /* Pointer to Origin block */

Dsivarch time; /* Time last command entered */ Dsivarch cvname; /* Name of variable for Cnmvars */ main(int argc, char *argv??(??)) { /******************************************************************/ /* Internal data definitions */ /******************************************************************/ /******************************************************************/ /* Convert operand pointers from character to hex addresses */ /******************************************************************/ sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck);

152 Programming: PL/I and C C High-Level Language Services

/* */ /******************************************************************/ /* Command other than CSNDDAT? */ if (strstr(Cmdbuf->buffer,"CSNDDAT") == NULL) { /* Yes... */ Cnminfc("TIME ", /* ...what time is it? */ &time, /* ...answer goes here */ 255); /* ...length of time */

Cnmvlc(&cvname, /* Set name of variable... */ 0, /* ...do not convert to hex */ "LAST_COMMAND_TIME"); /* ...name of variable */ Cnmvars(PUT, /* Put answer in task global... */ &time, /* ...information in TIME */ 0, /* ...length of time */ &cvname, /* ...by the name of */ TGLOBAL); /* ...task global pool */ } Hlbptr->Hlbrc = USERASIS; /* clear rc */ }

Coding the WAIT FOR DATA function CWATDAT and CSNDDAT are standard command processors that can be started from an installation exit. The following sections describe sending messages with a type of request, waiting on the response, and parsing the results. The code in this example is the CWATDAT command.

The command syntax:

CWATDAT

►► CWATDAT taskname ►◄

Where: taskname Specifies the task global variable set by the installation exit and retrieved by the CSNDDAT command.

The flow of the WAIT for data function is shown in Figure 6 on page 154.

Chapter 9. C high-level language services 153 C High-Level Language Services

Requesting Data Sending Data

The requesting OST invokes CWATDAT and specifies the target OST to which to send the request.

CWATDAT uses CNMSMSG to send the request to the target OST.

Waiting for Data

The requesting OST The CSNDDAT command issues a WAIT FOR is invoked on the DATA. target OST and finds the task global variable set by DSIEX03.

CNMSMSG is invoked to send the value retrieved. The type used in the CNMSMSG is DATA.

The WAIT FOR DATA is satisfied and a message is issued.

Figure 6. Flow of the WAIT FOR DATA Function

Requesting data “Requesting Data (C)” describes the initiating command processor that sends a message containing a request, waits on the response, and parses the results.

It also shows how to find the last time that a command was entered on the given OST. A task global variable, LAST_COMMAND_TIME, is set by DSIEX03 (see “Coding an installation exit” on page 152), and this value is retrieved by the CSNDDAT command that is started on the target task (see “Sending data” on page 156). Requesting Data (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsiorig getblock; /* Area for the Orig Block */ Dsivarch time; /* Time last command entered */ char targtask??(9??); /* Task of inquiry */ int len; /* length of targtask */

154 Programming: PL/I and C C High-Level Language Services

Dsivarch msgbuf; /* Message buffer */ char *token; /* used to parse command */ /******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/

token = strtok((char *) &(Cmdbuf->buffer)," "); /* parse command */ token = strtok(NULL," "); /* buffer for target task name */

if (strlen(token) > 8) /* node name invalid */ token = NULL;

strcpy(targtask,token);

len = strlen(targtask); strncat(targtask," ",8 - len); if (token != NULL) /* Was target task entered? */ { /* Syntax ok... */ if (strncmp(targtask,(char *) &(Origblck->Orig_task), strlen(targtask)) == 0) { /* is operator who issued CWATDAT being queried?*/ /* put error message in a varying */ Cnmvlc(&msgbuf, /* length character string... */ 0, /* ...do not convert to hex */ "Target task cannot be task invoking CWATDAT");

/* display the message... */ Cnmsmsg(&msgbuf, /* ...the message text */ MSG, /* ...type is message */ OPER, /* ...send to invoking operator */ NULLCHAR); /* ...not used */ } else { Cnmvlc(&msgbuf, /* Put command in msgbuf */ 0, /* ...do not convert to hex */ "CSNDDAT"); /* ...command */ Cnmsmsg(&msgbuf, /* Invoke CSNDDAT command */ REQUEST, /* ...type is request */ TASK, /* ...on a task */ targtask); /* ...specified by input command */ Cnmvlc(&msgbuf, /* Put WAIT command in msgbuf */ 0, /* ...do not convert to hex */ "WAIT 120 SECONDS FOR DATA"); Cnmcmd(&msgbuf); /* Invoke WAIT command */ if (Hlbptr->Hlbrc != CNM_DATA_ON_WAIT) /* Wait successful? */ { /* No... */ Cnmvlc(&msgbuf, /* Put error message in msgbuf */ 0, /* ...do not convert to hex */ "Wait for data abnormally ended");

Cnmsmsg(&msgbuf, /* Send error message... */ MSG, /* ...type is message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ } else /* Wait was successful */ { /* Process the results */ Cnmgetd(GETMSG, /* Read in the response */ &time, /* ...read into time variable */ 256, /* ...give plenty of room */ &getblock, /* ...provide own origin block */ DATAQ, /* ...on the data queue (3) */ 0); /* ...index not used */

Chapter 9. C high-level language services 155 C High-Level Language Services

/*******************************************************************/ /* Remove process and task ID from the buffer !!!! */ /* First 8 bytes and the last 8 bytes */ /*******************************************************************/ strncpy(msgbuf.buffer,time.buffer+8,time.size-8); msgbuf.size = time.size - 8; Cnmsmsg(&msgbuf, /* Inform user... */ MSG, /* ...type is message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ } } } else /* Target task not entered */ { Cnmvlc(&msgbuf, /* Put error message in msgbuf */ 0, /* ...do not convert to hex */ "Invalid Target Task");

Cnmsmsg(&msgbuf, /* Inform user of syntax error */ MSG, /* ...type is message */ OPER, /* ...to the operator */ NULLCHAR); /* ...not used */ } Sending data “Sending data (C)” is to find the last time that a command was entered on the given task. A task global variable, LAST_COMMAND_TIME, is set by DSIEX03 (see “Coding an installation exit” on page 152). This value is retrieved by the CSNDDAT command that is started by the CWATDAT command (see “Coding the WAIT FOR DATA function” on page 153) on the target task. This command processor is run when the CSNDDAT command is started. Sending data (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsivarch time, /* Date the last command was */ /* ...was entered */ msgbuf, /* Buffer for Cnmsmsg */ cvname, /* Buffer for name of variable */ myopid; /* operator ID we are running */ /* ...under */ /******************************************************************/ /* */ /* Execution */ /* */ /******************************************************************/ /* determine my opid */ Cnminfc("OPID ", /* ...variable is opid */ &myopid, /* ...put result here */ 8); /* ...truncate after 8 bytes */ if (strncmp((char *) &(myopid.buffer),(char *) &(Origblck->Orig_task), myopid.size) == 0) { /* CSNDDAT invoked directly? */ /* put error message in a varying*/ Cnmvlc(&msgbuf, /* length character string... */ 0, /* ...do not convert to hex */ "Cannot issue CSNDDAT directly"); /* CSNDDAT command... */ /* ...issued directly */ /* display the message... */ Cnmsmsg(&msgbuf, /* ...the message text */ MSG, /* ...type is message */ OPER, /* ...send to invoking operator */

156 Programming: PL/I and C C High-Level Language Services

NULLCHAR); /* ...not used */ } else { Cnmvlc(&cvname, /* Set variable name */ 0, /* ...do not convert to hex */ "LAST_COMMAND_TIME"); /* ...variable name */ /* Retrieve last time variable */ Cnmvars(GET, /* ...read in the value */ &time, /* ...into time */ 256, /* ...truncate at 256 */ &cvname, /* ...of the variable */ TGLOBAL); /* ...in the task global pool */ if (Hlbptr->Hlbrc == CNM_GOOD) /* Variable set? */ { /* Yes, continue... */ Cnmvlc(&msgbuf, /* Put data in msgbuf... */ 0, /* ...do not convert to hex */ "%.8sLast command entered at: %.8s",/* ...must precede*/ Origblck->Orig_process, /* data with origin process id*/ time.buffer); /* ...put in time */ /* Send data back to requestor */ Cnmsmsg(&msgbuf, /* ...text of message */ DATA, /* ...message is data */ TASK, /* ...to a task */ Origblck->Orig_task); /* ...that invoked this */ } else /* No inform user... */ { Cnmvlc(&msgbuf, /* Put error message in msgbuf */ 0, /* ...do not convert to hex */ "%.8sMust install DSIEX03 to set time variable", Origblck->Orig_process); /* Send message to requestor */ Cnmsmsg(&msgbuf, /* ...text of error message */ DATA, /* ...message is data */ TASK, /* ...to a task */ Origblck->Orig_task); /* ...that invoked this */ } }

Automating Management Services Units (MSUs) “Automating MSUs (C)” is an example of how to send an MSU directly to the automation table for evaluation. Automating MSUs (C) /******************************************************************/ /* Internal data definitions */ /******************************************************************/ int rcode; Dsivarch ru; Dsivarch msgbuf; /******************************************************************/ /* Convert parameter pointers from character to hex addresses */ /******************************************************************/ sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck); /******************************************************************/ /* Initialization */ /******************************************************************/ Hlbptr->Hlbrc = CNM_GOOD; /* Successful completion */ Cnmvlc(&ru,1,"008E41038D0000000010" "00860000" "1A00D5C5E3E5C9C5E640"

Chapter 9. C high-level language services 157 C High-Level Language Services

"C1E4E3D6D4C1E3C5E240" "C1D3C5D9E3E2" "0893000110213111" "0B92800001B0048CD5AA63" "180516100807C940D3D6E5C5FF00" "08D5C5E3E5C9C5E6FF11" "1E96060122E233D30384DD0382AA" "0382BB0382CC0382DD048144A3038333" "219808010000000431820382AA" "0382BB0382CC08010000000237450382DD0382EE"); /****************************************************************/ /* Drive the Automation Table with the MSU. */ /****************************************************************/ Cnmauto(&ru); /****************************************************************/ /* Respond to the operator with the return code from CNMAUTO */ /****************************************************************/ Cnmvlc(&msgbuf,0,"THE RC FROM THE C CNMAUTO INVOC = %d", Hlbptr->Hlbrc); Cnmsmsg(&msgbuf,MSG,OPER,0);

rcode = 0; Hlbptr->Hlbrc = rcode; /* Successful completion */

Translating code points “Translating code points (C)” is an example of how to translate a numeric code point value into its corresponding EBCDIC text. Translating code points (C) /******************************************************************/ /* INTERNAL DATA DEFINITIONS */ /******************************************************************/ int code; Dsivarch trdata; /* A Character Varying for Cnmc2t */ /******************************************************************/ /* CONVERT PARAMETER POINTERS FROM CHARACTER TO HEX ADDRESSES */ /******************************************************************/ sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck); Cnmscan(&Cmdbuf,"%*S%D",code);

Cnmc2t(&trdata,256,"SNAALERT",code);

Hlbptr->Hlbrc = CNM_GOOD;

Registering applications with MS transport and operations management “How to register an application (C)” is an example of how to register an application with both the MS transport and the operations management application. How to register an application (C) /******************************************************************** ** external data definitions ********************************************************************/ Dsihlb *Hlbptr; /* pointer to the HLB */ Dsivarch *Cmdbuf; /* pointer to command buffer */ Dsiorig *Origblck; /* pointer to origin block */

158 Programming: PL/I and C C High-Level Language Services

main(int argc, char *argv??(??)) { /****************************************************************** ** internal data definitions ******************************************************************/ Dsivarch msgbuf; /* convert parameter pointers from character to hex addresses */

sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck); Cnmrgs(REGMSAPPL, /* Registering an MS application */ "MSAPPL1 ", /* whose name is MSAPPL1 */ "RECVCMD ", /* the registered command proc. */ "OPS_MGMT", /* interested in fpcat OPS_MGMT */ "NO ", /* not a focal point application */ "YES ", /* replace MSAPPL1 if it exists */ "NONE ", /* don’t send session outage info*/ "PRI_LOW "); /* priority for incoming request */ Cnmvlc(&msgbuf,0,"Return code from Cnmrgs = %i",Hlbptr->Hlbrc); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR);

Hlbptr->Hlbrc = CNM_GOOD; /* set good rc and exit */ }

Registering applications with the high-performance transport “Registering an application with high-performance transport (C)” shows how to register an application with the high-performance transport. Registering an application with high-performance transport (C) /******************************************************************** ** external data definitions ********************************************************************/ Dsihlb *Hlbptr; /* pointer to the HLB */ Dsivarch *Cmdbuf; /* pointer to command buffer */ Dsiorig *Origblck; /* pointer to origin block */ main(int argc, char *argv??(??)) { /****************************************************************** ** internal data definitions ******************************************************************/ Dsivarch msgbuf;

/* convert parameter pointers from character to hex addresses */

sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck); Cnmhrgs(REGAPPL, /* Registering an HP application */ "HPAPPL1 ", /* whose name is HPAPPL1 */ "RECVCMD ", /* the registered command proc. */ "#INTER ", /* #INTER logmode used for sends */ "YES ", /* replace HPAPPL1 if it exists */ "NONE ", /* don’t send session outage info*/ "PRI_LOW "); /* priority for incoming request */ Cnmvlc(&msgbuf,0,"Return code from Cnmhrgs = %i",Hlbptr->Hlbrc); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR);

Hlbptr->Hlbrc = CNM_GOOD; /* set good rc and exit */ }

Chapter 9. C high-level language services 159 C High-Level Language Services

Sending an alert over the MS transport “Sending an Alert over the high-performance Transport (C)” is an example of how to send a software alert over the MS transport. Sending an Alert over the high-performance Transport (C) /******************************************************************/ /* INTERNAL DATA DEFINITIONS */ /******************************************************************/ Dsivarch msgbuf, alert, supplied_correlator, /* if we want to build MV x’1549’*/ correlator_area; /* if we want NetView to build it*/ /******************************************************************/ /* CONVERT PARAMETER POINTERS FROM CHARACTER TO HEX ADDRESSES */ /******************************************************************/ sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck); /* First, convert the hex data into a varying length char string. */ /* The alert is in the following format: */ /* MV 0000 Alert MV */ /* SV 92 - Generic Alert */ /* SV 10 - Product ID (12345) */ /* SV 03 - Hierarchy (NAME1,TYP1) */ /* SV 93 - Probable Causes */ /* SV 96 - Recommended Actions */ Cnmvlc(&alert,CNVTOHEX,"0046121200420000\ 0B92000001210100000001\ 1010000D110E0A0040F1F2F3F4F54040\ 1103030109D5C1D4C5F1404040E3E8D7F1\ 069310011023\ 0C9606011022102304813110"); /* if the conversion is successful, call Cnmsmu to send the alert */

if (Hlbptr->Hlbrc==CNM_GOOD) {

supplied_correlator.size=0; /* null supplied correlator */ Cnmsmu(NONMDSMU, /* let NetView build x’1311’ */ &alert, /* MV x’1212’ */ &supplied_correlator, /* this was null-ed out above */ &correlator_area, /* let NetView build x’1549’ */ 0, /* default time-out value */ "NO ", /* not a synchronous send */ " ", /* REPLYCMD */ "USERAPPL", /* Assumes USERAPPL is registered*/ "NETA ", /* netid=NETA */ "CNM99 ", /* destination nau=CNM99 */ alert, /* sending to x’23F0F3F1’ */ REQUEST_WITHOUT_REPLY, /* request without reply expected*/ "PRI_LOW "); /* priority for incoming request */ /* if the send fails, send a message to the operator */

if (Hlbptr->Hlbrc != CNM_GOOD) { Cnmvlc(&msgbuf,NOHEXCNV,"Cnmsmu failure, rc = %i", Hlbptr->Hlbrc); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); } /* if the conversion fails, send a message to the operator */

} else { Cnmvlc(&msgbuf,NOHEXCNV,"Cnmvlc failure, rc = %i", Hlbptr->Hlbrc);

160 Programming: PL/I and C C High-Level Language Services

Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); } Hlbptr->Hlbrc = CNM_GOOD; /* set a good rc and exit */ }

Sending data over the high-performance transport “Sending data over the high-performance transport (C)” is an example of how to send a software alert over the high-performance transport. Sending data over the high-performance transport (C) /******************************************************************/ /* INTERNAL DATA DEFINITIONS */ /******************************************************************/ Dsivarch msgbuf, alert, supplied_correlator, /* if we want to build MV x’1549’*/ correlator_area; /* if we want NetView to build it*/ /******************************************************************/ /* CONVERT PARAMETER POINTERS FROM CHARACTER TO HEX ADDRESSES */ /******************************************************************/ sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck); /* First, convert the hex data into a varying length char string. */ /* The alert is in the following format: */ /* MV 0000 Alert MV */ /* SV 92 - Generic Alert */ /* SV 10 - Product ID (12345) */ /* SV 03 - Hierarchy (NAME1,TYP1) */ /* SV 93 - Probable Causes */ /* SV 96 - Recommended Actions */ Cnmvlc(&alert,CNVTOHEX,"0046121200420000\ 0B92000001210100000001\ 1010000D110E0A0040F1F2F3F4F54040\ 1103030109D5C1D4C5F1404040E3E8D7F1\ 069310011023\ 0C9606011022102304813110"); /* if the conversion is successful, call Cnmhsmu to send the alert*/

if (Hlbptr->Hlbrc==CNM_GOOD) {

supplied_correlator.size=0; /* null supplied correlator */ Cnmhsmu(NONMDSMU, /* let NetView build x’1311’ */ &alert, /* MV x’1212’ */ &supplied_correlator, /* this was null-ed out above */ &correlator_area, /* let NetView build x’1549’ */ 0, /* default time-out value */ "NO ", /* not a synchronous send */ " ", /* REPLYCMD */ "USERAPPL", /* Assumes USERAPPL is registered*/ "NETA ", /* netid=NETA */ "CNM01 ", /* destination nau=CNM01 */ "DESTAPPL", /* sending to user-defined appl */ REQUEST_WITHOUT_REPLY, /*request without reply expect ed*/ "PRI_LOW "); /* priority for incoming request */ /* if the send fails, send a message to the operator */ if (Hlbptr->Hlbrc != CNM_GOOD) { Cnmvlc(&msgbuf,NOHEXCNV,"Cnmhsmu failure, rc = %i", Hlbptr->Hlbrc); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); } /* if the conversion fails, send a message to the operator */ } else { Cnmvlc(&msgbuf,NOHEXCNV,"Cnmvlc failure, rc = %i",

Chapter 9. C high-level language services 161 C High-Level Language Services

Hlbptr->Hlbrc); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); }

Hlbptr->Hlbrc = CNM_GOOD; /* set a good rc and exit */ }

Sending an MDB to NetView for processing The following example shows how to send an MDB to NetView for processing. Sending an MDB to NetView #pragma runopts( STACK(128K,128K,ANY,FREE) HEAP(128K,128K,ANY,FREE,8,0) ) #pragma runopts( BELOWHEAP(8,0,FREE) LIBSTACK(8,0,FREE) ) #pragma runopts( INTERRUPT(OFF) NOTEST(ALL,*,* ) STORAGE(,,,0) ) #pragma runopts( TRAP(OFF) MSGQ(1) ALL31(ON) )

/********************************************************************/ /* Header/Standard Include Files */ /********************************************************************/ #include /* Standard I/O header */ #include /* String functions */ #include /* Standard Definitions */ #include /* Standard Library */ #include /* Standard Args */ /********************************************************************/ /* Include the High-Level Language include files */ /********************************************************************/ #include "dsic.h" /* Include HLL macros */ /********************************************************************/ /* Parameters */ /********************************************************************/ Dsihlb *Hlbptr; /* Pointer to the HLB */ Dsivarch *Cmdbuf; /* Pointer to command buffer */ Dsiorig *Origblck; /* Area for the Origin Block */

/******************************************************************/ /* Internal data structures */ /******************************************************************/ typedef struct { /* Character varying type */ short int size; /* Length of buffer */ char buffer??(300??); /* Varying length buffer */ } Myvarch; /******************************************************************/ /* Internal data definitions */ /******************************************************************/ Dsivarch msgbuf, so, *soptr;

Myvarch mdb, *mdbptr; char mycorr??(16??); main(int argc, char *argv??(??)) { /****************************************************************/ /* Convert parameter pointers from character to hex addresses */ /****************************************************************/ sscanf(argv??(1??),"%x",&Hlbptr); sscanf(argv??(2??),"%x",&Cmdbuf); sscanf(argv??(3??),"%x",&Origblck);

/****************************************************************/ /* Create the MDB */ /* */

162 Programming: PL/I and C C High-Level Language Services

/* The CNMVLC service provides 2 functions in this call: */ /* */ /* 1. Converts the MDB data to hexadecimal. */ /* 2. Calculates and appends the MDB length to the */ /* beginning of the MDB. */ /* */ /****************************************************************/ Cnmvlc(&mdb,CNVTOHEX,"0001" /* MDB Type 1 */ "D4C7D640" /* MDB Acronym */ "00000001" /* Revision code */ "0038" /* General Object length */ "0001" /* General Object type */ "00000000" /* MDBGMID (message id) */ "C8C84BD4D44BE2E2" /* Time stamp HH.MM.SS */ "4BE3C8" /* Time stamp .TH */ "00" /* Reserved */ "E8E8E8E8C4C4C4" /* Date stamp YYYYDDD */ "00" /* Reserved */ "0000" /* MDBGMFLG (message flags) */ "0000" /* Reserved */ "00000000" /* Foreground presentation attr */ "00000000" /* Background presentation attr */ "D6D9C9C7E2D5C1D4" /* Originating system name */ "D1D6C240D5C1D4C5" /* Job name */ "0082" /* Control program object length*/ "0002" /* Control program object type */ "00000001" /* Object version level */ "D4E5E240" /* Control program name */ "C6D4C9C4C6D4C9C4" /* FMID of originating system */ "00000000000000000000000000000000" /* 128 Routing codes */ "0000" /* Descriptor codes */ "0000" /* Message level */ "0000" /* Message attribute flags */ "0000" /* Message priority */ "0000" /* Reserved */ "0012" /* ASID of issuer */ "00000000" /* JOB Step TCB for issuer */ "00000000" /* Token for DOM */ "00" /* System id for DOM */ "00" /* DOM flags */ "00" /* Misc routing information */ "00" /* Reserved */ "0000000000000000" /* Originating Job ID */ "0000000000000000" /* Retrieval KEY */ "0000000000000000" /* Automation Token */ "0000000000000000" /* Command and Response Token */ "00000000" /* Console */ "0000" /* Message type flags */ "0077" /* Reply ID length */ "0000000000000000" /* Reply ID (EBCDIC) */ "0000" /* Reserved */ "0000" /* Offset to beginning of msg */ "00000000" /* Reply ID (binary) */ "00" /* Areaid */ "00" /* Reserved */ "00000001" /* Number of lines in message */ "0000000000000000" /* Originating Job name */ "0049" /* Text object length */ "0004" /* Text object type */ "00000000" /* Presentation attributes */ "78E3C8C9E240" /* Text of message: "THIS " */ "D4C5E2E2C1C7C540" /* "MESSAGE " */ "E6C1E240E2C5D5E340" /* "WAS SENT " */ "C6D9D6D440C340" /* "FROM C " */ "E4E2C9D5C740E3C8C540" /* "USING THE " */ "D5C5E3E5C9C5E640" /* "NETVIEW " */ "C3D5D4D7D4C4C240" /* "CNMPMDB " */

Chapter 9. C high-level language services 163 C High-Level Language Services

"E2C5D9E5C9C3C5" /* "SERVICE" */ "0000"); /* 2 extra bytes so that length */ /* calculated includes length */ /* of the length field */

/****************************************************************/ /* Create the Source Object */ /****************************************************************/ Cnmvlc(&so,CNVTOHEX,"0005" /* Source object type */ "07D5D4E8E2E8E2" /* Nickname "MYSYS" */ "0000"); /* 2 extra bytes so that length */ /* calculated includes length */ /* of the length field */

/****************************************************************/ /* Initialize the correlator */ /****************************************************************/ *mycorr = *mycorr ??’ *mycorr; /* Exclusive OR */ /****************************************************************/ /* Set up pointers to MDB and Source Object */ /****************************************************************/ mdbptr = &mdb; soptr = &so;

/****************************************************************/ /* Call CNMPMDB */ /****************************************************************/ Cnmpmdb(&mdbptr,&soptr,mycorr);

/****************************************************************/ /* Respond to the operator with the return code from CNMPMDB */ /****************************************************************/ Cnmvlc(&msgbuf,0,"RETURN CODE FROM CNMPMDB: %i",Hlbptr->Hlbrc); Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR);

Hlbptr->Hlbrc = CNM_GOOD; /* Successful completion */ }

164 Programming: PL/I and C Part 5. HLL debugging and service routine reference

Before reading this chapter, compile and link edit your HLL module.

This chapter describes the NetView remote interactive debugger (RID) and how you can use it to do the following tasks: v Debug HLL programs v Validate entry and exit parameters to HLL service routines v Display storage at various predetermined debug points in the code.

Using RID to monitor a task You can use the NetView interactive debugging facility to monitor and debug HLL modules while they are running. You must determine a monitoring task and a target task to debug HLL modules effectively. The monitoring task must be an OST. From the monitoring OST, issue the RID commands that control the HLL module running under the target task. The target task can be an OST, a PPT, an NNT, or a DST.

RID begins to monitor the target task immediately after the RID command is issued from the monitoring task. If RID is started in STEP mode, the monitoring task controls the HLL module running under the target task. The monitoring task continues to control the HLL modules running under the target task until RID is started with the RUN or END option.

The most common use of the debugger is the default option, which displays operands upon entry to (HAPIENTR) and exit from (HAPIEXIT) HLL service routines.

RID command This syntax shows the RID command as it is issued from the monitoring or debugging task.

RID

,STEP , MODNAME = * , OPTION = * ►► RID TASK = opid ►◄ ,CONTINUE , MODNAME = name , OPTION = * ,END HAPIENTR ,RUN HAPIEXIT

Where: CONTINUE The CONTINUE option is used to resume running of a task that was stopped by the STEP option of RID. You can specify new debug point match criteria with the CONTINUE option. The CONTINUE keyword is provided for readability only. You can resume the task by reissuing the RID command with its original operands.

END The END option causes debugging of a task to cease and allows other operators to start RID for the target task. If the target task is stopped and RID is started with the END option, the HLL program running under the target task is resumed. MODNAME Is the name of the module being monitored by RID. If you specify *, RID monitors all HLL programs running under the target task. * is the default. OPTION Specifies the type of debug point. * All debug points are displayed. HAPIENTR Entry to an HLL API service routine. HAPIEXIT Exit from an HLL API service routine. RUN The RUN option is similar to the STEP option, except that the target task continues to run after issuing the messages at the debug points. The RUN option causes a task stopped in the STEP mode to resume. STEP Specifies that the target task is stopped whenever control is given to a debug point that matches the criteria indicated by the MODNAME or OPTION operand. Messages providing data captured at the debug point are displayed at the operator station that started RID to monitor the target task. STEP is the default. TASK Is the name of the task being monitored by RID. The target task can be an OST, PPT, NNT, or DST. PPT can be used as a synonym for the PPT task (xxxxxPPT) where xxxxx is the domain ID in the local NetView program.

Usage: 1. Only one NetView operator at a time can monitor a NetView task using RID. 2. Do not use RID to monitor or debug HLL command processors running under the PPT. Running RID against the PPT suspends the PPT, because undesirable results can occur if timer-sensitive functions (such as AT or EVERY) are being performed. 3. The default value (*) for MODNAME and OPTION is used until you specify a value. When you specify a value for MODNAME, that value is used on all successive RID invocations unless explicitly overridden. MODNAME and OPTION are reset to the default values when RID is started with the END option.

Return Codes

Return Code Name Value Description CNM_GOOD 0 Everything OK CNM_NOT_FOUND 20 Task not found CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro. CNM_BAD_OPTION 128 Incorrect option

168 Programming: PL/I and C Testing and Debugging

Return Code Name Value Description CNM_BAD_TASKNAME 164 Task name too long CNM_BAD_MODNAME 168 Module name too long CNM_BAD_COMBO 176 Incorrect combination of options CNM_TVB_INUSE 180 TVB in use CNM_RID_INUSE 184 RID in use CNM_RID_SELF 188 Debug task and target task cannot be the same. CNM_BAD_PUSH + X 4000 + X Nonzero return code X from DSIPUSH macro. CNM_BAD_SNTXS + Y 17000 + Y Nonzero return code Y. See values for Y below.

Values for Y

Value Description 4 Incorrect syntax.

Refer to the IBM Tivoli NetView for z/OS Programming: Assembler manual for more information.

RID scenario This section describes how to use RID to monitor or debug an HLL module. For this example, the HLL program has already been compiled and link-edited. The process for debugging HLL modules is similar for programs written in PL/I and C. However, there are some differences in the RID messages that are displayed. For this example, YOURPGM is the name of the HLL command processor that is monitored while running under target task OPER1. OPER2 is the monitoring or debugging task.

To start RID, issue the following command from OPER2: RID TASK=OPER1

Figure 7 shows the system response. RID defaults to STEP mode operation. The YOURPGM program is stopped at each debug point.

OPER2 - CNM01 CNM986I RID FUNCTION ’STEP’ COMPLETED FOR TASK OPER1

???

Figure 7. System response to RID invocation

From OPER1, enter the name of the HLL program to debug: YOURPGM

Figure 8 on page 170 shows the panel displayed on the console of OPER2. This is the entry panel (HAPIENTR) for your PL/I program (ID=PLIENTRY). The ID for

Chapter 10. Testing and debugging 169 Testing and Debugging

the entry panel for a C program is CENTRY.

OPER2 ’ CNM01 ▌1▐ CNM987I TASK OPER1 MOD YOURPGM TYPE HAPIENTR ID PLIENTRY SEQ 1 ▌2▐ CNM988I MVT 00007D88 TVB 00027BF0 TIB 00067338 TRB 0258B9D0 R13 0265EBB8 HLBPTR H 4 0258BA48 0258BA92 BUFFER S 7 0258BDF6 YOURPGM ORIGBLCK C 42 0258BA60 * CNM01 OPER1 * ISASIZ U 4 0258B9EC 4000 HEAPSIZ U 4 0258BA00 512 PLIOPTS H 4 0258BA38 55680000 ------▌3▐ ▌4▐ ▌5▐ ▌6▐ ▌7▐

???

Figure 8. PL/I Entry Screen for YOURPGM

The numbered boxes in Figure 8 are described as: ▌1▐ Message CNM987I displays: ID Unique identifier for the debug point being displayed MOD Name of the module being monitored by RID SEQ The sequence number of this RID panel TASK Name of the target task being monitored by RID TYPE Type of debug point currently being displayed ▌2▐ Message CNM988I displays the addresses of the main vector table (MVT), task vector block (TVB), task information block (TIB), transaction block (TRB), and the contents of register 13, which points to your save area. MVT, TVB, and TIB are described in IBM Tivoli NetView for z/OS Programming: Assembler. The transaction block is used only by IBM Software Support. ▌3▐ HLBPTR, BUFFER, ORIGBLCK are the initial parameters passed to your command processor from the NetView program. ISASIZ, HEAPSIZ, and PLIOPTS are the default PL/I runtime values unless you have overridden these values in your HLL program. ▌4▐ Describes how each of the variables in ▌3▐ is declared: A Address C Character D Dump H Hex I Integer S String U Unsigned

170 Programming: PL/I and C Testing and Debugging

▌5▐ Lengths of the variables in ▌3▐ that are expected by the HLL service routines. ▌6▐ Addresses in storage where the values for the variables in ▌3▐ are stored. ▌7▐ Values associated with each of the variables in ▌3▐.

Continue to the next debugging point by entering the following command from OPER2: RID TASK=OPER1,CONTINUE

Because you did not specify OPTION, RID displays panels upon entrance to (HAPIENTR) and exit from (HAPIEXIT) all HLL service routines started from the HLL program being debugged. In Figure 9, RID is displaying the parameters on entry to (HAPIENTR) the CNMSMSG service routine. The parameters for each HLL service routines are explained in Chapter 11, “Service reference,” on page 173.

OPER2

CNM987I TASK OPER1 MOD YOURPGM TYPE HAPIENTR ID SENDMSGE SEQ 2 N CNM988I MVT 00007D88 TVB 00027BF0 TIB 00067338 TRB 0258BAE6 R13 0258BC18 S SMTEXT S 25 000697CE HELLO SMMSGTYP C 8 000697EC MSG SMDESTYP C 8 000697F4 OPER SMDESTID C 8 800697FC ------

???

Figure 9. Entry Screen for CNMSMSG

Continue to the next debugging point by entering the following command from OPER2: RID TASK=OPER1

You do not need to issue the RID command with the CONTINUE option when you want a task to resume. CONTINUE is used for readability. Figure 10 displays the parameters on exit from the CNMSMSG service routine. RETCODE is added and is the value of HLBRC (Hlbrc for C programs) on exit from an HLL service routine.

OPER2

CNM987I TASK OPER1 MOD YOURPGM TYPE HAPIEXIT ID SENDMSGX SEQ 3 N CNM988I MVT 00007D88 TVB 00027BF0 TIB 00067338 TRB 0258BAE6 R13 0258BC18 S SMTEXT S 25 000697CE HELLO SMMSGTYP C 8 000697EC MSG SMDESTYP C 8 000697F4 OPER SMDESTID C 8 800697FC RETCODE I 4 0258BCB4 +0 ------???

Figure 10. Exit Screen for CNMSMSG

Continue to the next debugging point by entering the following command from OPER2: RID TASK=OPER1

Chapter 10. Testing and debugging 171 Testing and Debugging

The final RID panel displayed in Figure 11 is a PL/I exit panel that corresponds to the PLIENTRY panel in Figure 9 on page 171. Notice that TYPE= HAPIEXIT and ID=PLIEXIT. For a C program, the ID is CEXIT. the RETCODE is added, but ISASIZ, HEAPSIZ, and PLIOPTS are no longer displayed.

OPER2

CNM987I TASK OPER1 MOD YOURPGM TYPE HAPIEXIT ID PLIEXIT SEQ 4 N CNM988I MVT 00007D88 TVB 00027BF0 TIB 00067338 TRB 0258B9D0 R13 0265EBB8 S HLBPTR H 4 0258BA48 0258BA92 BUFFER S 7 0258BDF6 YOURPGM ORIGBLCK C 42 0258BA60 * CNM01 OPER1 * RETCODE I 4 0265EB4C +0 ------

???

Figure 11. PL/I Exit Screen for YOURPGM

172 Programming: PL/I and C Chapter 11. Service reference

This chapter describes the HLL commands and service routines, and their associated operands.

Composite return codes Most of the NetView commands, command lists, and HLL service routines generate return codes upon completion. There are two types of return codes: simple and composite. A simple return code is a constant value that requires no computation. A composite return code is a calculated value that consists of a known (constant) value and one or more unknown values.

The return code section at the end of each HLL command and service routine provides a chart of the following: v The return code represented in terms of constants and unknown values (if applicable) v The return code represented in terms of resolved constants and unknown values (if applicable) v A description of why the return code was issued

Several of the descriptions refer you to a NetView macro. Each of these macros is referenced in the IBM Tivoli NetView for z/OS Programming: Assembler book.

Do the following to resolve the unknown values of a composite return code: 1. Start with this equation: HLBRC = Composite return code equation 2. Resolve all known values. The first and most obvious known value is that of HLBRC. All other known values are represented as constants in DSIPCNM (see Appendix A, “PL/I Control Blocks and Include Files,” on page 269) and DSICCNM (see Appendix C, “C language control blocks and include files,” on page 279). In the case where there is more than one unknown value to resolve (X and Y), the remaining calculated value is split into a major and minor return code.

The following examples show how to calculate unknown values of a composite return code.

Example 1

Upon completion of a call to CNMNAMS, HLBRC=4004. A return code value in the 4000 range implies that the composite return code equation is CNM_BAD_PUSH + X. (See “CNMNAMS (CNMNAMESTR): Named Storage” on page 234.)

The known values are resolved as follows: HLBRC = CNM_BAD_PUSH + X 4004 = 4000 + X 4004 - 4000 = X 4 = X

The unknown value X is equal to 4. The CNMNAMS return code indicates that the return code was generated by the DSIPUSH macro. The DSIPUSH macro, detailed

in the IBM Tivoli NetView for z/OS Programming: Assembler book, indicates that the return code is caused by insufficient storage.

Example 2

Upon completion of a call to CNMCMD, HLBRC=-3108. A return code value in the -3000 range implies that the composite return code equation is X - CNM_BAD_EXCMS. (See “CNMCMD (CNMCOMMAND): Invoke NetView commands” on page 187.)

The known values are resolved as follows: HLBRC = X - CNM_BAD_EXCMS -3108 = X - 3000 -3108 + 3000 = X -108 = X

The unknown value of X is equal to -108. The CNMCMD return code indicates that the return code was generated by the DSICES macro. Refer to the description of this macro in IBM Tivoli NetView for z/OS Programming: Assembler.

The value of -108 in the previous example implies that X = SWBEXCNF - Y. The known values are resolved as follows: -108 = SWBEXCNF - Y -108 = -100 - Y -108 + 100 = -Y -(-108+100) = Y 8 = Y

The unknown value Y is equal to 8. This DSICES return code designates that an immediate command was located and that the address is returned.

Example 3

Upon completion of a call to CNMCNMI, HLBRC=21600. A return code value greater than 20000 for CNMCNMI implies that the composite return code equation is CNM_BAD_ZCSMS + (X * 100) + Y.

The known values are resolved as follows: HLBRC = CNM_BAD_ZCSMS + (X * 100 ) + Y 21600 = 20000 + (X * 100) + Y 21600 - 20000 = (X * 100 ) + Y 1600 = (X * 100) + Y

=> 1600 / 100 MAJOR_RC is the quotient => 16 MINOR_RC is the remainder => 0

The unknown values X and Y are equal to 16 and 0 respectively. The CNMCNMI return code indicates that the return code was generated by the DSIZCSMS macro. The DSIZCSMS macro in IBM Tivoli NetView for z/OS Programming: Assembler indicates that the return code is present because the call to CNMCNMI was not sent from a DST.

These return codes can also be seen in the initial return code value, 21600: 16 00 => 16 = MAJOR_RC 00 = MINOR_RC

Example 4

174 Programming: PL/I and C Service Reference

Upon completion of a call to the CNMCNMI service routine, HLBRC=20408. A return code value in the 20000 range implies that the composite return code equation is CNM_BAD_ZCSMS + (X * 100) + Y.

The known values are resolved as follows: HLBRC = CNM_BAD_ZCSMS + (X * 100 ) + Y 20408 = 20000 + (X * 100) + Y 20408 - 20000 = (X * 100 ) + Y 408 = (X * 100) + Y

=> 408 / 100 MAJOR_RC is the quotient => 4 MINOR_RC is the remainder => 8

These return codes can also be seen in the initial return code value, 20408: 4 08 => 4 = MAJOR_RC 8 = MINOR_RC

The unknown values X and Y are equal to 4 and 8 respectively. The CNMCNMI return code indicates that the return code was actually generated by the DSIZCSMS macro. The DSIZCSMS macro return code (refer to IBM Tivoli NetView for z/OS Programming: Assembler) indicates that the function cannot be performed because the DSRB control block is not valid.

Example 5

Upon completion of a call to CNMKIO, HLBRC=28692. Only two composite return codes are issued from CNMKIO. Because the return code value is not in the 2000 range, the value of 28692 implies that the composite return code equation is (CNM_BAD_ZVSMS + X) * 256 + Y or (100 + X) * 256 + Y

This equation is difficult to resolve without knowing either X or Y. Use these equations to determine the major and minor return codes: MAJOR_RC = (HLBRC / 256) - 100 = (28692 / 256) - 100 (keep only the quotient) = 112 - 100 = 12

MINOR_RC = HLBRC - ((CNM_BAD_ZVSMS + MAJOR_RC) * 256) = 28692 - ((100 + 12) * 256) = 28692 - (112 * 256) = 28692 - 28672 = 20

The return code section of CNMKIO indicates that the return code was actually generated by the DSIZVSMS macro. This code indicates that the VSAM function was not complete because the request was not valid or because an I/O scheduling error occurred. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information.

Command reference The commands described in the next sections are useful when executing HLL command processors. The GO, QUEUE, and RESET commands are operator commands. You can issue them from the operator console or from an HLL command processor through CNMCMD. The GLOBALV, TRAP, and WAIT commands must be issued from within an HLL command processor using CNMCMD.

Chapter 11. Service reference 175 Service Reference

Note: Refer to the IBM Tivoli NetView for z/OS Command Reference or the NetView online help for more information about these commands. GLOBALV command The GLOBALV command lets you define and manipulate task global and common global variables. In addition, you can save these variables to a VSAM database, restore them from the database, or purge them from the database. Task global variables are accessible only to the NetView task under which they were created. Common global variables are accessible to any NetView task.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_BAD_INVOCATION 4 Not called from HLL. CNM_NO_STORAGE 24 No storage available. CNM_BAD_FUNC 52 Action is not valid. CNM_BAD_LENGTH 88 Variable name is too long. CNM_BAD_COMMAND 144 No action or variables specified. CNM_BAD_POOL 156 A variable that the dictionary specified. CNM_NO_DATA 268 No specified variables found in VSAM database for RESTORE request. CNM_BAD_TASK 292 GLOBALV not called from OST, NNT, or PPT. CNM_USER_ENDED 304 Reset request from user. CNM_DST_ENDED 308 The DST ended with an error. CNM_BAD_CHAR 540 A character that is not valid in the variable name. CNM_BAD_COUNT 544 Odd count in double-byte character set (DBCS) shift-in and shift-out character. CNM_BAD_MQS + X 1000 + X Nonzero return code X from DSIMQS. CNM_BAD_PUSH + X 4000 + X Nonzero return code X from DSIPUSH. CNM_BAD_KVS + X 11000 + X Nonzero return code X from DSIKVS. CNM_BAD_LCS + X 13000 + X Nonzero return code X from DSILCS. CNM_BAD_CDS + Z 14000 + Z Nonzero return code Z. See values for Z below. CNM_BAD_PAS + X 16000 + X Nonzero return code X from DSIPAS. CNM_BAD_PRS + X 25000 + X Nonzero return code X from DSIPRS. Nonzero return code from DSIZVSMS. X is the (CNM_BAD_ZVSMS + X) (100 + X) major return code and Y is the minor return * 256 + Y * 256 + Y code.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler or the z/OS VSAM library for more information.

Values for Z

Value for Z Description 4 Variable name that is not valid. Asterisk used in DEFx, GETx, or PUTx. 12 Insufficient storage. 20 Value length limit exceeded.

176 Programming: PL/I and C GLOBALV command

Value for Z Description 28 No command procedure related to action. 32 Data truncated.

Refer to the IBM Tivoli NetView for z/OS Command Reference or the NetView online help for more information about the GLOBALV command. GO command Use the GO command to resume running a command procedure in a pause or wait state. You can also use the GO command to pass values to a command procedure in a pause state.

When you enter a GO command to resume running a command procedure that is in a pause or wait state, a CNM_GO_ON_WAIT return code is generated for these situations: v The event specified on the WAIT command is MESSAGES (with or without a time specified). v The event specified on the WAIT command is DATA (with or without a time specified). v A time is specified on the WAIT command with no specified events.

A return code of CNM_OPINPUT_ON_WAIT is generated if one of the events specified on the WAIT command is OPINPUT. You can enter GO alone or with operator input. See “WAIT command” on page 182 for more information about satisfying a wait.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_NO_STORAGE 24 Nonzero return code from the DSIGET macro. CNM_BAD_MQS + X 1000 + X Nonzero return code (X) from the DSIMQS macro. CNM_BAD_LCS + X 13000 + X Nonzero return code (X) from the DSILCS macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information.

Refer to the IBM Tivoli NetView for z/OS Command Reference or the NetView online help for more information about the GO command. PIPE command The PIPE command is a powerful and flexible command that lets you issue commands and manipulate messages in a pipeline. Many of the functions available in the HLL environment as commands and service routines are also available through the PIPE stage commands.

The PIPE command creates a message processing environment that lets you issue a command and wait for that command's response messages (either synchronous or asynchronous). PIPE ensures that only messages correlated to the command are received and processed in the pipeline. You can use the PIPE command to process

Chapter 11. Service reference 177 PIPE command

commands that generate correlated responses instead of using the WAIT and TRAP commands. The command and message correlation provided through the PIPE command is a major advantage over the WAIT command. See “Waiting and trapping using the PIPE command (PL/I)” on page 68 and “Waiting and trapping Using the PIPE command (C)” on page 127 for examples of using PIPE in an HLL program.

For a description of the advantages of using the PIPE command instead of the WAIT command, refer to IBM Tivoli NetView for z/OS Programming: Pipes.

The PIPE command also provides support for stem variables in the NetView HLL environment. See “Accessing stem variables using the PIPE command (PL/I)” on page 70 and “Command list variable access (C)” on page 131 for an example of how to access local variables that have been stored in stem variables by the PIPE command.

The PIPE stage command, < (From Disk), provides similar function to the HLL service routines CNMMEMO, CNMMEMR and CNMMEMC. The PIPE stage commands, CONSOLE and LOGTO, provide function that is available through the CNMSMSG service routine. The PIPE command with these stages can be used in place of the associated HLL service routine in these cases. However, RID support is available only when the HLL service routine is used.

Note: 1. The PIPE command cannot be issued from an HLL installation exit routine or from an HLL command procedure running under a DST. Refer to IBM Tivoli NetView for z/OS Programming: Pipes for a complete description of the PIPE command. 2. To obtain information about the PIPE command and stage commands, use the online HELP facility: v To display information about the PIPE command, enter: HELP PIPE v To display information about a specific stage command, enter: HELP PIPE stage_command QUEUE command The QUEUE command adds a text message to the operator input queue (OPERQ) of an HLL command processor or installation exit routine running with the HLL_QUEUED_INPUT bit of HLLOPTS turned on.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_NO_STORAGE 24 Nonzero return code from the DSIGET macro. CNM_BAD_MQS + X 1000 + X Nonzero return code (X) from the DSIMQS macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. Refer to the IBM Tivoli NetView for z/OS Command Reference or the NetView online help for more information about the QUEUE command.

178 Programming: PL/I and C RESET command

RESET command High-level language support gives you the option of specifying whether a command procedure is cancelable. The reset flag is set on only when RESET, LOGOFF, or CLOSE IMMED are being issued. See “HLL runtime options” on page 38 for more information.

If a command procedure can be cancelled, it behaves according to the rules specified under the RESET command in the NetView online help The description for RESET NORMAL states that a command stops at its next breakpoint whenever RESET NORMAL is issued. A breakpoint occurs in an HLL command procedure whenever an HLL service routine is started.

If a cancelable command procedure is reset with RESET NORMAL, the command procedure ends with a -5 return code and ends its caller if the caller is also cancelable.

If the command procedure cannot be cancelled, it is reset only when RESET IMMED and RESET DUMP are issued.

Whenever RESET is issued, NetView turns on a reset flag that remains on until the command procedure returns control to NetView or uses the CNMINFI service routine to check RESETREQ.

If RESET NORMAL is issued while a non-cancelable command procedure is running, the reset flag remains on until the noncancelable command procedure either calls or returns to a cancelable command procedure.

A non-cancelable command procedure can check to see if an operator has attempted to reset it by using the RESETREQ function of the CNMINFI service routine. To cancel itself, a command procedure must return to NetView with a -5 return code. This cancels the command procedure that had this return code and all cancelable callers to this command procedure. Cancelable callers include command lists that call a cancelled command procedure, and cancelable command procedures that directly invoke a cancelled command procedure.

Checking the reset flag sets the flag off. As a result, the command procedure that checks the flag must reset the flag. You cannot pass on this responsibility to a higher level through the use of the reset flag. (You can set a user-defined flag for this purpose, but doing so is not recommended.)

Examples

In this example, cancelable command procedure X calls cancelable command procedure Y, which calls cancelable command procedure Z. RESET NORMAL is entered while command procedure Z is running.

Chapter 11. Service reference 179 RESET command

Procedure Procedure Procedure X Y Z

(can be (can be (can be cancelled) (RC=-5)cancelled) (RC=-5) cancelled)

(reset) (reset) (RESET NORMAL entered)

Figure 12. Example of command procedure cancellation (1)

As a result of entering RESET NORMAL, Z is reset. Z returns a -5 return code to Y, which causes Y to be reset. Y returns a -5 return code to X, and X is reset.

Keep in mind that the HLL command procedures must invoke the CNMINFI service routines for the reset bit to be checked. Y and X continue executing if they do not invoke any more HLL service routines.

Here cancelable command procedure X calls non-cancelable command procedure Y, which calls cancelable command procedure Z. RESET is entered when command procedure Z is running.

Procedure Procedure Procedure X Y Z

(can be (cannot be (can be cancelled) cancelled) (RC=-5) cancelled)

(not reset) (not reset) (RESET NORMAL entered)

Figure 13. Example of command procedure cancellation (2)

As a result of entering RESET NORMAL, Z is reset. Y receives a -5 return code from the call to Z. Y is not automatically reset by NetView. It can, if it chooses, check the return code and cancel itself, but this is the responsibility of Y. Even though X is cancelable, it is not cancelled because Y is at a lower execution level, and Y is not reset.

In this example, non-cancelable command procedure X calls non-cancelable command procedure Y. Non-cancelable command procedure Y returns control to non-cancelable command procedure X. Non-cancelable command procedure X then calls cancelable command procedure Z. RESET is entered just as X begins execution.

180 Programming: PL/I and C RESET command

Procedure Procedure X Y

(cannot (cannot be cancelled) be cancelled)

(not reset)

Procedure Z

(can be (RC=-5) cancelled)

(RESET entered) (reset)

Figure 14. Example of command procedure cancellation (3)

Even though RESET NORMAL is external, X is not cancelled because it is defined as non-cancelable. X calls Y. Y is not cancelled because Y is defined as non-cancelable. Y returns control to X, and then X calls Z. Z is reset and returns control to X with a -5 return code.

Note: 1. In the example referred to by Figure 14, command procedure X can check the reset flag using the HLL service routine CNMINFI. In this case, the reset flag is turned off and Z is not reset. 2. Create command procedures that can be cancelled when possible. The HLL support option that cannot be cancelled is provided so that you can code command procedures to perform cleanup (such as free storage) before the procedure is cancelled. 3. When an HLL command procedure is cancelled, the cleanup that is done is equivalent to that which is done by the STOP statement in PL/I and the EXIT statement in C.

When cleanup is necessary see the following example:

Procedure Procedure X Y

(cannot be (can be cancelled) (RC=-5) cancelled)

(not reset) (RESET entered)

Figure 15. Example of command procedure cancellation (4)

In this example, if RESET is issued while Y is executing, Y is terminated and X performs the cleanup.

Chapter 11. Service reference 181 TRAP command

TRAP command Use the TRAP command to specify message trapping criteria for HLL and REXX command procedures. When the TRAP command is issued, all subsequent messages that match the conditions that are defined by the trapping criteria are added to the message queue (TRAPQ).

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_BAD_INVOCATION 4 TRAP was not issued from an HLL or REXX command procedure. CNM_BAD_SYNTAX 12 Syntax error. When DSI028I is issued, check domainid.token syntax. When DSI604I is issued, check the format of the TRAP command according to the operand specified. CNM_BAD_COMMAND 144 TRAP was not issued from a command procedure running under an OST or NNT. CNM_BAD_MRBLD + X 18000 + X Nonzero return code X. See values for X below.

Values for X

Return Code Value Value for X Description 18000 + X 8 Request for storage has failed.

Refer to the IBM Tivoli NetView for z/OS Command Reference or the NetView online help for more information about the TRAP command. WAIT command When issued from a command procedure, the WAIT command temporarily suspends processing of that command procedure until a specified event occurs. For an HLL command procedure, the event can be one or more messages, operator input, data, a certain period of time, or any combination of these four. The first occurrence of one of these events satisfies the wait and processing is resumed.

Return Codes:

Return Code Name Value Description CNM_BAD_INVOCATION 4 WAIT was not issued from an HLL or REXX command procedure. CNM_TOO_MANY 8 Too many operands. CNM_BAD_SYNTAX 12 Syntax error. CNM_BAD_COMMAND 144 WAIT was not issued from a command procedure running under an OST or NNT. CNM_NO_TRAP 152 WAIT was issued but TRAP was not issued. Issue a valid TRAP before issuing WAIT for messages.

182 Programming: PL/I and C WAIT command

Return Code Name Value Description CNM_NO_PREV_WAIT 248 No previous WAIT; WAIT CONTINUE is not valid. CNM_STRG_FAILURE 616 DSIGET failure in a service routine. Note: The following return codes are issued when a wait is satisfied. They are generated in place of a 0 return code to inform the operator which event satisfied the wait. CNM_TIME_OUT_WAIT 224 WAIT timed out. CNM_GO_ON_WAIT 228 GO satisfied wait. CNM_MSG_ON_WAIT 232 Message received during wait. CNM_OPINPUT_ON_WAIT 236 OPINPUT received during wait. CNM_DATA_ON_WAIT 240 DATA received during wait.

Refer to the IBM Tivoli NetView for z/OS Command Reference or the NetView online help for more information about the WAIT command.

HLL service routine reference The following service routines can be started from a command processor or installation exit routine written in PL/I or C. A description of each service routine is given, along with its associated parameters, usage notes, and return codes.

When writing a command processor or installation exit routine in PL/I, you can invoke an HLL service routine using the call or macro format. The PL/I macro format is provided for those users who want to code only the required parameters for a particular HLL service routine invocation. Code all of the parameters when using the PL/I call format or C invocation.

When you invoke a service routine from an HLL command processor or installation exit routine written in C, the first letter of the service routine name must be capitalized and the remaining letters must be lowercase. This restriction is a result of C being case-sensitive. PL/I does not have this restriction. CNMALTD (CNMALTDATA): alter data on a queue Use the CNMALTD routine to alter the contents of the top message on the initial data queue. Lines can be inserted, replaced, or deleted.

The CNMALTD routine syntax follows:

PL/I CALL FORMAT: CALL CNMALTD(hlbptr,adfunc,adbuf,adorigin,adqueue,adindex)

PL/I MACRO FORMAT: CNMALTDATA FUNC(adfunc) DATA(adbuf) ORIGIN(adorigin) QUEUE(adqueue) LINE(adindex)

C INVOCATION: void Cnmaltd(char *adfunc, void *adbuf, void *adorigin, int adqueue, int adindex)

Where:

Chapter 11. Service reference 183 CNMALTD (CNMALTDATA)

adbuf A varying length character field containing the buffer to be inserted. This field is required with INSLINE and REPLINE, but not used with DELLINE. adfunc An 8-byte character field that specifies the function to be performed. This field is required for all CNMALTD calls. The possible values follow: DELLINE Deletes a line of the current message in the specified queue. The line specified by adindex (the index value) is physically removed from the queue. You can delete all lines of a message. If the line that was last returned from GETLINE or GETMSG is deleted, the message pointer is moved back to the line preceding the deleted line. (See “CNMGETD (CNMGETDATA): Data queue manipulation” on page 204 for information.) adqueue and adindex are required operands for DELLINE. adbuf and adorigin are not required operands for this function. INSLINE Inserts a new line in the message in the specified queue. adindex specifies the line number that the new line will have after it is inserted. The index value can be one greater than the number of lines currently in the message to add a line on the end. All parameters are required for this function. REPLINE Replaces a line of the current message in the specified queue (if it exists). All parameters are required for this function. adindex A 4-byte integer field containing the line number of the message at the head of the queue to be manipulated. This field is required for all functions. adorigin A character field of fixed length n (where n ≥ 38) to contain an origin block. Define an origin block (adorigin) to be passed as a parameter to CNMALTD. This must be a separate structure from the origin block (ORIGBLCK) that was passed to the HLL command processor or installation exit routine as an initial parameter. ORIG_BLOCK_LENGTH cannot be less than 38. See DSIPORIG in Appendix A, “PL/I Control Blocks and Include Files,” on page 269 or DSICORIG in Appendix C, “C language control blocks and include files,” on page 279 for the PL/I and C mappings of an origin block. You are responsible for updating the origin block (adorigin) to reflect changes made by CNMALTD. This field is required for INSLINE and REPLINE, but not for DELLINE. adqueue A 4-byte integer field containing the number (index) of the queue on which the operation is to be performed. The only queue allowed for CNMALTD is the initial data queue (IDATAQ). The full message that started the HLL command processor through NetView automation or the message that drives DSIEX02A is on the initial data queue. This field is required for all functions. hlbptr A 4-byte pointer field containing the address of the HLB control block.

Usage Notes: 1. CNMALTD is primarily designed for use in DSIEX02A, where you can alter messages before they are automated or displayed.

184 Programming: PL/I and C CNMALTD (CNMALTDATA)

2. See “CNMSMSG (CNMSENDMSG): Send Message or Command” on page 251 for the definitions of line types.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro. CNM_BAD_FUNC 52 Incorrect adfunc value. CNM_BAD_QUEUE 72 Incorrect adqueue value. CNM_BAD_INDEX 76 Incorrect adindex value. CNM_QUEUE_EMPTY 80 The specified queue is empty. CNM_BAD_ORIGBLOCK 84 Incorrect value in ORIG_BLOCK_LENGTH. CNM_BAD_LENGTH 88 The length of (adbuf) is greater than (>) 32729. CNM_NOT_MLWTO 92 Message is not a multiline message. CNM_BAD_LINETYPE 96 Incorrect line type. Must be C,D,E,L,F, or ' '. CNM_NO_LINES_IN_MSG 264 All lines in the specified message have been deleted.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMAUTO (CNMAUTOTAB): Invoke automation table Use this service routine to invoke the NetView automation table from an HLL command processor or installation exit.

The CNMAUTO routine syntax follows:

PL/I CALL FORMAT: CALL CNMAUTO(hlbptr,atdata)

PL/I MACRO FORMAT: CNMAUTOTAB DATA(atdata)

C INVOCATION: void Cnmauto(void *atdata)

Where: atdata A varying length character field containing the data item to be automated. The data item must be in one of these forms: v A MDS-MU v A CP-MSU v A NMVT The CNMAUTO routine determines which form of data item has been passed in atdata and takes appropriate action to calculate the length of the data item. Refer to the SNA library for more information.

Chapter 11. Service reference 185 CNMAUTO (CNMAUTOTAB)

hlbptr A 4-byte pointer field containing the address of the HLB control block.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 A match was found and the data item was automated. CNM_FAIL_TO_AUTOMATE 24000 + X Nonzero return code, X, from DSIAUTO macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMCELL (CNMSTRCELL): storage cell You can use the CNMCELL service routine to allocate and free storage cells from a previously allocated storage pool. The token obtained by CNMPOOL must be passed to CNMCELL to identify the storage pool.

The CNMCELL routine syntax follows:

PL/I CALL FORMAT: CALL CNMCELL(hlbptr,pcfunc,pctoken,pcstrptr)

PL/I MACRO FORMAT: CNMSTRCELL FUNC(pcfunc) TOKEN(pctoken) STRPTR(pcstrptr)

C INVOCATION: void Cnmcell(char *pcfunc, int pctoken, void *pcstrptr)

Where: hlbptr A 4-byte pointer field containing the address of the HLB control block. pcfunc An 8-byte character field that specifies the function to be performed: ALLOC Allocate cell FREE Free cell pcstrptr A 4-byte pointer field to contain the address of the cell. This field is returned to the caller for ALLOC and provided by the caller for FREE. pctoken A 4-byte integer field containing the token identifying the storage pool. The caller provides this field for all functions (the token is returned from CNMPOOL).

Usage Note: A storage cell within a pool is associated with the NetView subtask under which it was allocated. The storage cell cannot be referenced from a task other than the one with which it is associated.

Return Codes:

186 Programming: PL/I and C CNMCELL (CNMSTRCELL)

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro. CNM_BAD_TOKEN 32 Incorrect pctoken. CNM_BAD_FUNC 52 Incorrect pcfunc. CNM_BAD_CLASS 112 Possible storage overlay. Report to IBM Software Support. CNM_BAD_ADDR 160 The storage pointed to by pcstrptr is not addressable. CNM_NOT_IN_POOL 204 Cell not in storage pool. CNM_BAD_CELL_ADDRESS 256 Address is not on valid cell boundary. CNM_CELL_ALREADY_FREE 260 Cell has already been freed.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMCMD (CNMCOMMAND): Invoke NetView commands Use the CNMCMD service routine to run a NetView command from an HLL command processor. If the called command is a long-running command, the caller is suspended until the long-running command is completed. The caller regains control at the instruction following the CNMCMD invocation.

The CNMCMD routine syntax follows:

PL/I CALL FORMAT: CALL CNMCMD(hlbptr,cmdstr)

PL/I MACRO FORMAT: CNMCOMMAND DATA(cmdstr)

C INVOCATION: void Cnmcmd(void *cmdstr)

Where: cmdstr A varying length character field containing the NetView command (including its parameters) to be run. hlbptr A 4-byte pointer field containing the address of the HLB control block.

Usage Notes: 1. Commands are started with a HDRMTYPE of HDRTYPEC. This type is consistent with the NetView command list language and REXX. 2. The return code from HLL command processors and NetView long-running commands is returned properly to HLL command processors through the CNMCMD interface. If you wish to call a long-running command and have it be separately rollable, you can prefix the command with CMD HIGH. For example, CNMCOMMAND DATA ('CMD HIGH BROWSE NETLOGA') enables

Chapter 11. Service reference 187 CNMCMD (CNMCOMMAND)

the BROWSE panel to roll independently from the calling HLL command processor. Refer to the NetView online help for more information about the CMD command. 3. CNMCMD does not process immediate commands (type=I in DSIPARM member CNMCMD). 4. A negative return code generated from CNMCMD indicates a failure in the CNMCMD service routine, whereas a positive return code generated from CNMCMD indicates a failure in the NetView command that was to be run by CNMCMD. A -5 return code generated from CNMCMD indicates that the NetView command this is running was cancelled. In this case, the command processor does any necessary cleanup and sets the exit HLBRC to -5 to pass the RESET information to its caller. 5. A -1 return code generated from CNMCMD indicates an unexpected error in the called command procedure. 6. You cannot invoke CNMCMD from an HLL installation exit routine or from an HLL command processor while holding a lock. 7. The NetView service point command service (SPCS) commands are not supported under the HLL API and must not be started by CNMCMD. Refer to the NetView online help for a list of SPCS commands.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. -CNM_BAD_INVOCATION -4 Not started from a command processor. -CNM_NO_STORAGE -24 Nonzero return code from DSIGET macro. -CNM_BAD_LENGTH -88 Command length is not valid. -CNM_LOCKED -208 CNMCMD issued while holding a lock. X-CNM_BAD_EXCMS X-3000 Nonzero return code X. See values for X that follow. Z Return code from a command. See CNMCMD usage notes for return codes -5 and -1.

Values for X

Return Code Value for X Description -4 Nonzero return code, 4 (drop), from installation exit. -100-Y Nonzero return code, Y, from DSICES macro. -200-Y Nonzero return code, Y, from DSILCS (CWB) macro. -300-Y Nonzero return code, Y, from DSIGET macro. -400-Y Nonzero return code, Y, from DSIPRS macro. -500-Y Nonzero return code, Y, from either DSIGET or DSILCS indicates storage failure. -600-Y Nonzero return code, Y, from DSILCS (SWB) macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information.

188 Programming: PL/I and C CNMCNMI (CNMI)

CNMCNMI (CNMI): CNMI access under a DST The CNMI service of NetView enables HLL command processors running under a DST to send and receive data across the CNMI. You can use this service in conjunction with CNMGETD to manipulate data on the CNMI solicited data queue (CNMIQ).

The CNMI routine syntax follows:

PL/I CALL FORMAT: CALL CNMCNMI(hlbptr,cnfunc,cndata,cndest,cntimout)

PL/I MACRO FORMAT: CNMI FUNC(cnfunc) DATA(cndata) DEST(cndest) TIMEOUT(cntimout)

C INVOCATION: void Cnmcnmi(char *cnfunc, void *cndata, char *cndest, int cntimout)

Where: cndata A varying length character field containing the RU to be sent (beginning with an RH header). This field is required for all functions. The RU length must be at least 3 bytes and no longer than 32729 characters. cndest An 8-byte character field that specifies the name of the PU to which the RU is sent. This field is required for all functions. cnfunc An 8-byte character field that specifies the function to be performed. This field is required for all CNMCNMI calls. SENDRESP Sends RUs and expects only a positive or negative response. SENDRPLY Sends RUs and expects a reply RU or a negative response. cntimout A 4-byte integer field specifying the number of seconds to wait for a reply or response. This is an optional field. If you do not specify cntimout, the default is 0. If you specify a timeout, the RH header must indicate that the embedded network services (NS) RU solicits a reply. This causes NetView to generate a procedure-related identifier (PRID). Refer to the z/OS Communications Server library for more information. For requests that generate multiple RU (chained) replies, cntimout applies only to the first RU in the chain. hlbptr A 4-byte pointer field containing the address of the HLB control block.

Usage Notes: 1. You cannot invoke CNMCNMI from an HLL command processor while holding a lock. HLL command processors enter a wait state when sending requests over the CNMI. The wait ends when a response or reply is received or when the specified timeout expires. 2. You cannot issue CNMCNMI from an HLL installation exit routine. 3. Responses to CNMI solicited data requests are placed on the CNMI solicited data queue (CNMIQ).

Chapter 11. Service reference 189 CNMCNMI (CNMI)

4. The XITCI installation exit routine is started for both solicited and unsolicited data. See Chapter 2, “HLL installation exit routines,” on page 11 for more information about this exit. Also see Chapter 3, “HLL Data Services command processors,” on page 27 for a discussion on “Unsolicited HLL Data Services Command Processors (DSCP).” When the unsolicited HLL DSCP receives control, the command buffer (CMDBUF) contains the unsolicited data RU. For more information about installing a DST, see Chapter 3, “HLL Data Services command processors,” on page 27.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_BAD_INVOCATION 4 Not started from a command processor or not under a DST. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro. CNM_BAD_RULENG 48 Incorrect cndata length. CNM_BAD_FUNC 52 Incorrect cnfunc. CNM_BAD_TIMEOUT 56 cntimout less than (<) 0. CNM_NEED_PRID 60 Timeout specified but PRID not generated. The PRID generation bit in the RU must be set if a timeout is specified. CNM_NEG_RESPONSE 64 Negative response received. (Sense code in HLBSENSE.) CNM_TIME_OUT 68 Timeout occurred. CNM_LOCKED 208 CNMI issued while holding a lock. CNM_DST_FAILURE 2000 + X Nonzero return code, X, which is the DSRB + X minor return code for solicited CNMI data or VSAM data set services. CNM_BAD_ZCSMS 20000 + (X Nonzero return code (major), X, and nonzero + (X * 100) + Y * 100) + Y return code (minor), Y, from DSIZCSMS.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler or the MVS/ESA VSAM library for more information. CNMCPYS (CNMCOPYSTR): Copy storage Use the CNMCPYS service routine to copy storage from one address to another. If the source or destination is not addressable, this service routine enables the copy operation to process without ending abnormally. However, the service routine does not stop you from overwriting storage if it is addressable.

The CNMCPYS routine syntax follows:

PL/I CALL FORMAT: CALL CNMCPYS (hlbptr, csfrom, csto, cslen, cstype)

PL/I MACRO FORMAT: CNMCOPYSTR FROM(csfrom) TO(csto) LENG(cslen) COPYTYPE(cstype)

C INVOCATION: void Cnmcpys(void *csfrom, void *csto, int cslen, char *cstype)

190 Programming: PL/I and C CNMCPYS (CNMCOPYSTR)

Where: csfrom A 4-byte pointer field containing the address of the source data. cslen A 4-byte integer field containing the number of bytes of storage (0 to 16777215) to be copied. If the value specified by cslen is greater than the actual length of the specified csto buffer, a storage overlay can occur. Take special care when deciding the value of cslen. csto A 4-byte pointer field containing the address of the destination. cstype Is the type of copy to perform. Valid types are: FIXTOFIX Copy cslen bytes of storage from a fixed-length buffer to another fixed-length buffer. FIXTOVAR Copy cslen bytes of storage from a fixed-length buffer to a varying length buffer. VARTOFIX Copy cslen bytes of storage from a varying length buffer to a fixed-length buffer. VARTOVAR Copy cslen bytes of storage from a varying length buffer to another varying length buffer. hlbptr A 4-byte pointer field containing the address of the HLB control block.

Usage Notes: 1. The length field of varying length buffers is not set or altered by CNMCPYS. 2. When using CNMCPYS with C and when copying FIXTOFIX, FIXTOVAR, or VARTOFIX, pass CNMCPYS a pointer to a pointer to your fixed-length buffer. You can do this by designating a variable as a pointer to a string, and then passing the address of that pointer to CNMCPYS.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_BAD_LENGTH 88 cslen greater than (>) 16777215 or less than (<) 0. Copy not performed. CNM_BAD_ADDR 160 The storage pointed to by csto or csfrom is not addressable. CNM_BAD_CSTYPE 252 Incorrect cstype. CNM_BAD_ESTAE 15000 Nonzero return code from ESTAE macro.

Refer to the z/OS library for more information.

Chapter 11. Service reference 191 CNMC2T (CNMCODE2TXT)

CNMC2T (CNMCODE2TXT): Code point translation You can use NetView with a problem-management database to open problem records when NetView alerts are received. The code point translation service routine is provided in PL/I and C to translate the numeric code points, received in the alert, into readable text.

Note: This function is not supported when NetView is in a distributed system configuration.

The CNMC2T service routine provides translation for various types of code points to multicultural text.

The CNMC2T routine syntax follows:

PL/I CALL FORMAT: CALL CNMC2T(hlbptr,trdata,trdatlen,trtable,trcode)

PL/I MACRO FORMAT: CNMCODE2TXT DATA(trdata) LENG(trdatlen) TABLE(trtable) CODE(trcode)

C INVOCATION: void Cnmc2t(void *trdata, int trdatlen, char *trtable, int trcode)

Where: hlbptr A 4-byte pointer field containing the address of the HLB control block. trcode A 4-byte integer field containing the code point to be translated. trdata A varying length character field to which the code point text is to be returned. trdatlen A 4-byte integer field containing the length of trdata. This is the maximum length of the area provided to receive the returned text. If the value specified by trdatlen is less than the length of the text to be returned, the truncated text is returned in trdata and a return code of CNM_DATA_TRUNC is generated. The full length of the text that was truncated is stored in HLBLENG (Hlbleng). If the value specified by trdatlen is equal to or greater than the length of the text to be returned, and HLBRC (Hlbrc) = CNM_GOOD, the length of the returned text is stored in HLBLENG (Hlbleng). If the value specified by trdatlen is greater than the length of the receiving data buffer (trdata), a storage overlay can occur. Take special care when deciding the value of trdatlen. trtable An 8-byte character field that specifies the table to be used in translating the code point. Valid table names are: SNAALERT SNA alert description code point SNACAUSE SNA probable cause

192 Programming: PL/I and C CNMC2T (CNMCODE2TXT)

SNADDATA SNA detailed data SNADDAT5 SNA detailed data code point, subfield X'85' SNADDAT6 SNA detailed data code point, subfield X'86' SNAFCAUS SNA failure cause SNAICAUS SNA install cause SNAREACT SNA recovery actions SNAUCAUS SNA user cause

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_NOT_FOUND 20 Table not found. CNM_DATA_TRUNC 40 Data truncated; trdatlen is too small. CNM_BAD_ADDR 160 Address of trdata is not valid. CNM_BAD_TABLE 312 Incorrect table name. CNM_BAD_CODE 316 Code point not found; length of trdata is 0.

CNMGETA (CNMGETATTR): Query message attributes You can use the CNMGETA service routine to obtain attributes of messages on the initial data queue (IDATAQ). You can also retrieve action messages, DOM information for messages, and DOMs processed by HLLs. The values of the attributes are returned to you in character string form.

The CNMGETA routine syntax follows:

PL/I CALL FORMAT: CALL CNMGETA(hlbptr,ganame,gadata,gadatlen,gaqueue)

PL/I MACRO FORMAT: CNMGETATTR ITEM(ganame) DATA(gadata) LENG(gadatlen) QUEUE(gaqueue)

C INVOCATION: void Cnmgeta(char *ganame, void *gadata, int gadatlen, int gaqueue)

Where: gadata A varying length character field containing the resulting value for the specified attribute.

Chapter 11. Service reference 193 CNMGETA (CNMGETATTR)

Note: If an attribute does not apply to the particular message or MSU type data, the gadata field is set to a null value for character data. Bit fields are returned as all character zeros. gadatlen A 4-byte integer field containing the length of gadata. This is the maximum length of the area provided to receive the returned data. You provide the value for gadatlen. If the value specified by gadatlen is less than the length of the data to be returned, the truncated data is returned in gadata and a return code of CNM_DATA_TRUNC is generated. The full length of the data that was truncated is stored in HLBLENG (Hlbleng). If the value specified by gadatlen is equal to or greater than the length of the data to be returned, and HLBRC (Hlbrc) = CNM_GOOD, the length of the returned data is stored in HLBLENG (Hlbleng). If the value specified by gadatlen is greater than the length of the receiving data buffer (gadata), a storage overlay can occur. Take special care when deciding the value of gadatlen. ganame An 8-byte character field that specifies the attribute. The following are the valid attributes: ACTIONDL An EBCDIC string that indicates why the NetView action message was deleted. The following are the values: (null) The message is not a DOM (delete operator message). LOCAL The message was deleted by operator overstrike or by the CONSOLE DELETE stage. NETVIEW The message was deleted by the NetView DOM command, using the NVELID option, or internally by NetView. SMSGID The message was deleted by an MVS DOM-by-SMSGID. A single message was deleted by its specific ID. This is the most frequent type of MVS DOM. TOKEN The message was deleted by an MVS DOM-by-token. TCB The message was deleted because the task ended that issued the message. In some cases MVS converts these messages into DOM-by-SMSGID. ASID The message was deleted because the address space that issued the message ended. In some cases MVS converts these messages into DOM-by-SMSGID. INVALID The DOM contained an unrecognizable combination of bit settings. This can indicate a user exit problem or a data area overlay problem. ACTIONMG An action message with of value of 1 or 0. For a value of 1, NetView

194 Programming: PL/I and C CNMGETA (CNMGETATTR)

treats the message as an MVS action message. Action messages are WTORs or those having a Descriptor code matching the setting of MVSPARM.ActionDescCodes in CNMSTYLE. ATTNID A VSE attention identifier. A plus sign (+) indicates that a reply is required for this message immediately. A (-) indicates that a reply is required for this message. This function has a value if the message is from a VSE system, but null for non-VSE messages. AUTOTOKE A 1- to 8-character name of the MVS message processing facility (MPF) automation token. This can also be set as a result of a DSIVSAM or DSIVSMX request.

Note: If you specify AUTO(YES) or AUTO(NO) in the MPF table, the values “YES” and “NO” are not automation tokens. CART An 8-byte MVS command and response token (CART). The CART might contain non-displayable characters.

Note: CART only has a value if the messages were originally a MDB. DESC Are the MVS descriptor codes as a series of 16, 1 (on) and 0 (off) EBCDIC characters representing the bits in order. Refer to the MVS/ESA library for more information about code values. IFRAUGMT Is the Greenwich Mean Time when the automated internal function request (AIFR) was created. This value is returned as an 8-byte hexadecimal value. IFRAUIND Returns 2-byte of indicator bits as a series of 16, 1 (on) and 0 (off) EBCDIC characters represent the bits in order. This data is mapped in DSIIFR. The bit positions are: (1) MVS system information attached (WQE data). (5) Message from NetView PPT. (6) Message received cross-domain. (11) Message was PRI routed by ASSIGN command. (12) Message was SEC routed by ASSIGN command. (13) Message was COPY routed by ASSIGN command. (14) Message was routed to authorized receiver. (15) Message was from down-level domain (no AIFR received). (16) Message was unsolicited.

Note: 1. Other bits can be tested, but have no suggested use. All the bits are defined in the DSIIFR mapping control blocks; refer to IBM Tivoli NetView for z/OS Programming: Assembler. 2. Messages with the unsolicited flag on are eligible for ASSIGN PRI and SEC routing. 3. This attribute indicates the AIFR indicator fields IFRAUIND and IFRAUIN2.

Chapter 11. Service reference 195 CNMGETA (CNMGETATTR)

4. When using extended multiple console support (EMCS) consoles, only MVS system messages that are received by the CNMCSSIR task are considered unsolicited messages. 5. For more information about solicited and unsolicited messages, refer to the IBM Tivoli NetView for z/OS Automation Guide. IFRAUIN3 Returns 1 byte of indicator bits as a series of 8 1 (on) and 0 (off) EBCDIC characters representing the bits in order. This data is mapped in DSIIFR. The bit positions and their meaning are: v (Bits 1-2) Indicate cross-domain command priority as follows: 00 = Default priority 01 = Low priority 10 = High priority 11 = Test the receiver for priority v (Bit 3) VM PMX IFRAUI3X Retrieves the 32 bits of binary flags that are located in the DSIIFR map for a message, beginning at label IFRAUI3X. Browse the assembler macro, DSIIFR, for a description of these fields. IFRAUSB2 A 2-byte user field from the message which is returned as a 2 characters.

Note: IFRAUSRB and IFRAUSB2 refer to the same user field in the message, but return the value in different formats. IFRAUSC2 A 16-byte user field from the message which is returned as a series of 128, 1 (on) and 0 (off) characters representing the bits in order. See also IFRAUSRC.

Note: IFRAUSRC and IFRAUSC2 refer to the same user field in the message, but return the value in different formats. IFRAUSDR Is the 1- to 8-character name of the originating NetView task. IFRAUSRB A 2-byte user field from the message which is returned as a series of 16, 1 (on) and 0 (off) characters representing the bits in order. See also IFRAUSB2.

Note: IFRAUSRB and IFRAUSB2 refer to the same user field in the message, but return the value in different formats. IFRAUSRC A 16-byte user field from the message which is returned as 16 characters. See also IFRAUSC2.

Note: IFRAUSRC and IFRAUSC2 refer to the same user field in the message, but return the value in different formats. IFRAUTA1 Returns 6-byte of indicator bits as a series of 48, 1 (on) and 0 (off)

196 Programming: PL/I and C CNMGETA (CNMGETATTR)

EBCDIC characters representing the bits in order. IFRAUTA1 enables checking of control information. The bit positions are: (1,2,25) HOLD action. (5,6,26) SYSLOG action. (7,8,27) NETLOG action. (9,10,28) HCYLOG action. (11,12,29) DISPLAY action. (13,14,30) BEEP action. (20) Message from MVS. (23) VSE format message. (24) Action message. (47) Automation vector extensions exist. (48) Presentation vectors exist in data buffers.

Note: 1. Other bits can be tested, but have no suggested use. 2. See the DSIIFR fields IFRAUTA1 thru IFRAUTA6 for more information. 3. For a description of all bits, refer to IBM Tivoli NetView for z/OS Programming: Assembler. IFRAUWF1 Is 4-bytes of MVS-specific WTO information returned as a series of 32, 1 (on) and 0 (off) characters representing the bits in order. Bit positions are: (6) Message is a WTOR (7) Message is suppressed (8) Broadcast to all (9) Display JOBNAMES (10) Display STATUS (14) Display SESSION Other bits can be tested, but have no suggested use. JOBNAME A 1- to 8-character MVS job name identifier. Because the JOBNAME is the name of the job that originated the message, it might not be the same as the name of the job to which the message is referring. For example, the job names might be different when MVS issues a message about the NetView job. Also, JOBNAME can contain the name of an initiator (instead of the job name) when a job is started or ended. If the message is issued during startup or termination, extract the job name from the message text rather than using the JOBNAME function.

Note: The same information is available using MSGCOJBN. JOBNUM An 8-character MVS JOB number identifier.

Note: The MVS job identifier might contain embedded blanks. Depending on the MVS release, JOBNUM can be a character string such as JOB 4 which including blanks is 8 characters.

Chapter 11. Service reference 197 CNMGETA (CNMGETATTR)

KEY An 8-character retrieval key associated with the message. KEY might contain non-displayable values.

Note: | 1. Make sure you provide an 8-byte area to contain the returned key. | Otherwise, the key might be truncated. | 2. To use the MVS D R,KEY command, specify only EBCDIC characters | for KEY. MCSFLAG Returns the system message flags as a series of 8, 1 (on) and 0 (off) EBCDIC characters representing the bits in order. The bit positions are: (1) - Send message conditionally to console SYSCONID (2) - Send message unconditionally to console SYSCONID (3) - RESP (4) - REPLY (5) - BRDCST (6) - HDRCPY only (7) - NOTIME (8) - NOCPY

Note: This function does not return the same mapping of multiple console support flags as the automation table compare item. MSGASID An MVS system address space identifier from which the message was issued. The value of MSGASID is a 1- to 5-digit decimal number.

Note: This value is null for messages that do not come from an MVS address space. MSGAUTH A 2-character value indicating whether the messages was issued from an authorized program. Bit positions and their meanings are: 00 - WTO message is not from MVS 10 - WTO is from an unauthorized program 11 - WTO is from an authorized program MSGCATTR Is 2-bytes of MVS message attribute flags returned as a series of 16, 1 (on) and 0 (off) EBCDIC characters representing the bits in order. Bit positions and their meaning are: (1) - Message is suppressed. (2) - Message is the command response. (3) - Message issued by authorized program. (4) - Message is to be retained by Automation Message Retention Facility (AMRF).

| Usage note: Other bits can be tested but have no suggested use. MSGCMISC Is 1 byte of MVS miscellaneous routing flags returned as a series of 8, 1 (on) and 0 (off) EBCDIC characters representing the bits in order. Bit positions and their meaning are:

198 Programming: PL/I and C CNMGETA (CNMGETATTR)

(1) - Display UD (undeliverable) messages. (2) - Display only UD messages. (3) - Queue by ID only. (4) - Indicates whether the message has been marked in the message processing facility (MPF) table as eligible for NetView automation.

Note: 1. This function has a value only if the message currently being processed was originally an MDB. 2. Other bits can be tested but have no suggested use. MSGCMLVL Is 2-bytes of MVS message level flags returned as a series of 16 on (1) and off (0) EBCDIC characters representing the bits in order. Bit positions and their meaning are: (1) - WTOR (2) - Immediate action (3) - Critical eventual action (4) - Eventual action (5) - Informational (6) - Broadcast

| Usage note: Other bits can be tested, but have no suggested use. MSGCMSGT Is 2 bytes of MVS message type flags returned as a series of 16 on (1) and off (0) EBCDIC characters representing the bits in order. Bit positions and their meaning are: (1) Display job names (2) Display status (3) Monitor active (6) Monitor SESS

Note: 1. This function has a value only if the message currently being processed was originally an MDB. 2. Other bits can be tested, but have no suggested use. MSGCOJBN A 1- to 8-character returned originating job name.

Note: Also available in JOBNAME. MSGCPROD A 16-character MVS product level. The character are defined as follows: v The first 4 characters represent an MVS control point object version level. v The next 4 characters represent the control program name (MVS). v The last 8 characters represent the function modification identifier (FMID) of the originating system.

Chapter 11. Service reference 199 CNMGETA (CNMGETATTR)

Note: This function has a value only if the message currently being processed was originally an MDB. MSGCSPLX Is the 1- to 8-character name of the MVS SYSPLEX where the received message originated.

Note: This function has a value only if the message currently being processed was received from an MVS SYSPLEX or from an MVS system that specified a sysplex name in a couple data set and was originally a MDB. MSGCSYID A 1- to 3-digit decimal number system identification for DOM. The value of MSGCSYID can be to 255.

Note: This function has a value only if the message currently being processed was originally an MDB. MSGDOMFL Is 1 byte of MVS DOM flags returned as a series of 8, 1 (on) and 0 (off) EBCDIC characters representing the bits in order. Bit positions and their meaning are: (1) DOM by message ID (2) DOM by system ID (3) DOM by ASID (4) DOM by job step TCB (5) DOM by token

Note: 1. This function has a value only if the message currently being processed was originally an MDB. 2. NetView EMCS consoles are set up by default as DOM(NORMAL) receivers. As a result, the DOMs that are received from MVS by these consoles are usually DOM by MSGID, and the TOKEN, SYSID, ASID, and TCB flags are usually not set on when the DOM is received from MVS. MSGGBGPA Is 4 bytes of hexadecimal background presentation attributes. Bytes and their descriptions are: Byte 1 - Background control field Byte 2 - Background color field Byte 3 - Background highlighting field Byte 4 - Background intensity field

Note: This function has a value only if the message currently being processed was originally an MDB. MSGGDATE Is the message date in a seven-character format yyyyddd, where yyyy is the year and ddd indicates a calendar day.

| Usage note: This is not necessarily the current date. It can be the date | that MVS associates with the issuing of the message.

200 Programming: PL/I and C CNMGETA (CNMGETATTR)

MSGGFGPA Is 4 bytes of hexadecimal foreground presentation attributes. Bytes and their meaning are: Byte 1 - Foreground control field Byte 2 - Foreground color field Byte 3 - Foreground highlighting field Byte 4 - Foreground intensity field

Note: This function has a value only if the message currently being processed was originally an MDB. MSGGMFLG Is 2 bytes of MVS general message flags returned as a series of 16, 1 (on) and 0 (off) EBCDIC characters representing the bits in order. Bit positions and their meaning are: v Delete operator message (DOM)

Note: This function has a value only if the message currently being processed was originally an MDB. MSGGMID | A 4-character MVS message identifier. The value of MSGGMID is a | composite of MSGGSEQ and MSGGSYID. MSGGMID might contain | non-displayable characters. This field contains the same information as | SMSGID, except that SMSGID is returned as a decimal number and | MSGGMID is returned as hexadecimal value. MSGGSEQ | A sequence number associated with the message. This value is a 1- to | 8-digit decimal number, and is generated from the last 3 bytes of | MSGGMID. MSGGSYID | An ID of the system from which the message was issued. This value is | a 1- to 3-digit decimal number that is generated from the first byte of | MSGGMID. MSGGTIME | A time that MVS associates with the message. An 11-character time in | the form hh:mm:ss:th, where hh is the hours, mm is the minutes, ss is the | seconds, and th is tenths and hundredths of seconds. MSGSRCNM A 1- to 17-character source name. This source name is an identifier from the source object that was provided by either the DSIMMDBS or CNMPMDB API invocation. For more information about DSIMMDBS, refer to IBM Tivoli NetView for z/OS Programming: Assembler. For more information about CNMPMDB see “CNMPMDB (CNMPRSMDB): Process Message Data Block” on page 236. The source name is selected from the source object by the following rules: v The first nickname, if any v The first network identifier concatenated to a network addressable unit (NAU) name, with a period (.) between, if both exist in sequence v The first NAU name, if it exists

Chapter 11. Service reference 201 CNMGETA (CNMGETATTR)

v The string “N/A” if none of the other names in this list are specified in the source object v Null, if there is no source object For more information about how the source object is defined, refer to the DSIAIFRO mapping in IBM Tivoli NetView for z/OS Programming: Assembler.

Note: This function has a value only if the message currently being processed was originally an MDB with an associated source object. MSGSRCOB The entire source object which was provided on the DSIMMDBS or CNMPMDB application programming interface (API) invocation. This value can contain non-displayable characters. The maximum length that is returned is 1100 bytes. For more information about DSIMMDBS refer to IBM Tivoli NetView for z/OS Programming: Assembler. For more information about CNMPMDB, see “CNMPMDB (CNMPRSMDB): Process Message Data Block” on page 236. MSGTOKEN A 1- to 10-digit decimal number that indicates the token associated with the message.

| Usage note: You can use a TOKEN value to group WTOs by setting | MSGTOKEN prior to issuing the WTO command. Subsequently, these | messages can be deleted using a single DOM command by specifying | the token value in MSGTOKEN. Refer to IBM Tivoli NetView for z/OS | Programming: REXX and the NetView Command List Language for | information about DOM token. MSGTSTMP A message time-stamp. The value of this field is the time when the NetView message buffer was created. The field is a 6-character string in the form hhmmss: v hh is hours v mm is minutes v ss is seconds MSGTYP The system message types flags returned as a series of 3, 1 (on) and 0 (off) EBCDIC characters. The value of the characters are as follows: 1 SESS (corresponds to IFRAUWF1(14)) 2 JOBNAMES (corresponds to IFRAUWF1(9)) 3 STATUS (corresponds to IFRAUWF1(10)) MVSRTAIN In NetView HLL procedures, a 3-bit field describing MVS Retain characteristics of the message.

Note: These 3 flags correspond to 3 flags defined in the MVS WQE control block. The exact meaning and use of the flags is a property of the operating system. Refer to operating system documentation for specific information.

202 Programming: PL/I and C CNMGETA (CNMGETATTR)

1xx AMRF retained message x1x Retain in AMRF xx1 Do not retain in AMRF NVDELID A NetView message deletion ID. A 24-character EBCDIC value for a message that can be saved and used later as input to the DOM command to delete an action message. PARTID Is the first 2 characters of the 6-character prefix for VSE messages. The 2 returned characters are the message partition ID only if the sending system uses those characters to designate a partition ID for a message.

Note: PARTID only has a value if the message originated on a VSE system. PRTY A the priority message as set by the originator. This field is a 1- to 5-digit decimal number. NetView does not use this field when processing the message.

Note: This function has a value only if the message currently being processing was originally an MDB. REPLYID A reply identifier for WTORs. This field has a maximum length of 8 characters. For messages from VSE systems, the REPLYID is the last 3 characters of the 6-character message prefix. The 3 returned characters are the message reply ID only if the sending system uses those characters to designate a reply ID for a message. ROUTCDE Are the MVS routing codes assigned to the message. The value returned is a series of 1 (on) and 0 (off) EBCDIC characters representing the bytes in order. The maximum number of ROUTCDEs assigned to a message is 128. SESSID A 1- to 8-character ID of the terminal access facility (TAF) session that sent the message.

Note: If the TAF session is started with a SESSID that is the same as the domain ID, the SESSID is set unpredictably and can give unpredictable results. SMSGID A 1- to 10-character decimal number that identifies a particular instance of a message. This function can be used by the DOM command to identify action messages to be removed from the display. This field contains the same information as MSGGMID, except that SMSGID is returned as a decimal number and MSGGMID is returned as a hexadecimal value. SYSCONID An MVS system console name associated with the message. System console names are 2 to 8 characters in length.

Chapter 11. Service reference 203 CNMGETA (CNMGETATTR)

SYSID A 1- to 8-character identifier of the MVS system that sent the message. SYSID can be used in a sysplex to route commands to the appropriate system. gaqueue A 4-byte integer field containing the number of the queue holding the message. Only attributes for the initial data queue (IDATAQ) can be obtained. hlbptr A 4-byte pointer field containing the address of the HLB control block.

Usage Notes: 1. Other information, which exists in the ORIG_BLOCK, is available when you call the CNMGETD service routine. See “CNMGETD (CNMGETDATA): Data queue manipulation” for more information. 2. Refer to IBM Tivoli NetView for z/OS Programming: REXX and the NetView Command List Language for more information. 3. Some attributes apply to all types of messages, while others apply only to certain types of messages. For example, JOBNAME is meaningful only for messages received from MVS.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 The value requested is returned in gadata. CNM_DATA_TRUNC 40 gadatlen was too small. Data truncated. CNM_BAD_FUNC 52 Incorrect ganame. CNM_BAD_QUEUE 72 Incorrect gaqueue value. CNM_QUEUE_EMPTY 80 The specified queue is empty. CNM_BAD_LENGTH 88 gadatlen less than (<) 0. CNM_BAD_ADDR 160 The storage pointed to by gadata is not addressable.

CNMGETD (CNMGETDATA): Data queue manipulation Use the CNMGETD service routine to manipulate input queue data. Input queue data consists of logical groups of data buffers based on the type of information about the queue. The types of information that can be placed on the input queues are: Single-line Message Contains one data buffer for each logical group. The data buffer contains the text of the message. The logical group represents the actual message. Multiline Message Contains one or more data buffers for each logical group. Each data buffer contains the text from one line of the multiline message. The logical group represents the actual multiline message. Automation MSU Contains one or more data buffers for each logical group. Reply MSU Contains one or more data buffers for each logical group.

204 Programming: PL/I and C CNMGETD (CNMGETDATA)

The CNMGETD routine syntax follows:

PL/I CALL FORMAT: CALL CNMGETD(hlbptr,gdfunc,gdbuf,gdbuflen,gdorigin,gdqueue,gdindex)

PL/I MACRO FORMAT: CNMGETDATA FUNC(gdfunc) DATA(gdbuf) LENG(gdbuflen) ORIGIN(gdorigin) QUEUE(gdqueue) LINE(gdindex)

C INVOCATION void Cnmgetd(char *gdfunc, void *gdbuf, int gdbuflen, void *gdorigin, int gdqueue, int gdindex)

Where: gdbuf A varying length character field containing the data buffer to be returned. This field is required for GETFIRST (GETMSG), GETNEXT (GETLINE), and PEEKBFR (PEEKLINE). It is not required for FLUSHBFR (FLUSHLIN), FLUSHGRP (FLUSHMSG), or FLUSHQ. gdbuflen A 4-byte integer field containing the length of gdbuf. This is the maximum length of the area provided to receive the returned data buffer. You provide the value for gdbuflen. This field is required for GETFIRST (GETMSG), GETNEXT (GETLINE), and PEEKBFR (PEEKLINE). If the value specified by gdbuflen is less than the length of the data buffer to be returned, the truncated data is returned in gdbuf and a return code of CNM_DATA_TRUNC is generated. The full length of the data buffer that is truncated is stored in HLBLENG (Hlbleng).

Note: GETFIRST (GETMSG) and GETNEXT (GETLINE) requests continue to advance through the queue independent of the truncation. Use a combination of PEEKBFR (PEEKLINE) with FLUSHBFR (FLUSHLIN), FLUSHGRP (FLUSHMSG), or FLUSHQ when retrieving complete data buffers of unknown length. If the value specified by gdbuflen is equal to or greater than the length of the data buffer to be returned, and HLBRC (Hlbrc) = CNM_GOOD, the length of the returned data buffer is stored in HLBLENG (Hlbleng). If the value specified by gdbuflen is greater than the length of the receiving data buffer (gdbuf), a storage overlay can occur. Take special care when deciding the value of gdbuflen. gdfunc An 8-byte character field that specifies the function to be performed. Additional field values are provided to support input queue data of any type. The values support both message and non-message data. The existing message-related values (GETMSG, GETLINE, and so on) are still supported. FLUSHGRP (FLUSHMSG) Skips to the next logical group in the specified queue.

Chapter 11. Service reference 205 CNMGETD (CNMGETDATA)

FLUSHNXT (FLUSHLIN) Skips over the next data buffer of the specified queue. This function crosses logical group boundaries until the queue is empty. FLUSHQ Discards all logical groups in the specified queue.

Note: If this service is used in a command processor which is driven by automation, do not flush the initial data queue unless you have copied the command buffer string to a local variable because the command buffer is also flushed. GETFIRST (GETMSG) Returns the first data buffer of the next logical group of buffers on the specified queue. If one or more buffers of a group have already been returned by GETFIRST (GETMSG) or GETNEXT (GETLINE), the current GETFIRST (GETMSG) skips to the next logical group in the queue, discarding any skipped data buffers. GETNEXT (GETLINE) Returns the next buffer in the specified queue. This function crosses logical group boundaries until the queue is empty. Check ORIG_LINE_TYPE to determine which line is last. PEEKBFR (PEEKLINE) Returns a data buffer from the logical group at the head of the specified queue whose buffer number is specified by gdindex. Flushed and received data buffers can still be obtained unless the logical group is flushed or a logical buffer in a subsequent logical group was obtained. gdindex A 4-byte integer field containing the number (index) of the group at the head of the queue to be manipulated. This field is required only for PEEKBFR (PEEKLINE). gdorigin A character field of fixed length n (where n > = 38) to contain an origin block. Define an origin block (gdorigin) to be passed as an operand to CNMGETD. This must be a separate structure from the origin block (ORIGBLCK) that was passed to the HLL command processor or installation exit routine as an initial parameter. ORIG_BLOCK_LENGTH cannot be less than 38. See Appendix A, “PL/I Control Blocks and Include Files,” on page 269 and Appendix C, “C language control blocks and include files,” on page 279 for the PL/I and C mappings of an origin block. This field is required for GETFIRST (GETMSG), GETNEXT (GETLINE), and PEEKBFR (PEEKLINE). gdqueue A 4-byte integer field containing the number (index) of the queue on which to perform the operation. This field is required for all functions. Valid values follow:

Queue Queue Name Number Function TRAPQ 1 Message queue. Contains trapped messages. See “TRAP command” on page 182.

206 Programming: PL/I and C CNMGETD (CNMGETDATA)

Queue Queue Name Number Function OPERQ 2 Operator input queue. See “GO command” on page 177 and “QUEUE command” on page 178. DATAQ 3 Data queue. Contains data sent from another HLL command processor or installation exit routine. See “CNMSMSG (CNMSENDMSG): Send Message or Command” on page 251. IDATAQ 4 Initial data queue. Contains the full message or MSU that invokes the HLL command processor through NetView automation. It also contains messages that drive DSIEX02A. This is also the queue where an application command processor receives an MDS-MU from the NetView high-performance transport, the MS transport, or operations management for an unsolicited request or asynchronous reply. CNMIQ 5 CNMI solicited data queue. Contains RUs solicited through the CNMI service routine. Chained RUs are treated like multiline messages. See “CNMCNMI (CNMI): CNMI access under a DST” on page 189. MDSMUQ 6 MDS-MU data queue. Contains message units (MUs) received as synchronous replies. The MDS-MUs are received from operations management, the MS transport, and the high-performance transport. hlbptr A 4-byte pointer field containing the address of the HLB control block.

Usage Notes: 1. The following items are available after issuing CNMGETD. The NetView command list language equivalents are listed in the descriptions. ORIG_MSG_TYPE Provides the 1-character NetView buffer type of the received message or MSU, and is equivalent to &HDRMTYPE. This control variable returns a X'10' when an MSU buffer string is being handled. ORIG_LINE_TYPE Provides the MLWTO line type and is equivalent to &LINETYPE. This control variable returns the character M for the MSU buffer and an H for the HIER buffer. ORIG_PROCESS Is the message identifier of the message currently being processed by NetView and is equivalent to &MSGID. This control variable returns a null value when an MSU buffer string is being handled. ORIG_DOMAIN Is the domain where the message most recently received by NetView originated and is equivalent to &MSGORIGIN. 2. See Appendix A, “PL/I Control Blocks and Include Files,” on page 269 and Appendix C, “C language control blocks and include files,” on page 279 for mapping of the origin block.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK.

Chapter 11. Service reference 207 CNMGETD (CNMGETDATA)

Return Code Name Value Description CNM_DATA_TRUNC 40 gdbuflen was too small. Data truncated. CNM_BAD_FUNC 52 Incorrect gdfunc value. CNM_BAD_QUEUE 72 Incorrect gdqueue value. CNM_BAD_INDEX 76 Incorrect gdindex value. CNM_QUEUE_EMPTY 80 The specified queue is empty. CNM_BAD_LENGTH 88 gdbuflen less than (<) 0. CNM_BAD_ADDR 160 The storage pointed to by either gdbuf or gdorigin is not addressable. CNM_NO_LINES_IN_MSG 264 All buffers in the specified logical group have been deleted.

CNMHRGS (CNMHREGIST): high-performance transport application registration The CNMHRGS service routine registers any application that wants to send data to or receive data from another application through the high-performance transport API. Register the application before attempting to send or receive data.

CNMHRGS also deregisters applications, which results in the termination of the high-performance transport’s awareness of the application. After deregistration, the application cannot send or receive any further data.

The CNMHRGS routine syntax follows:

PL/I CALL FORMAT: CALL CNMHRGS(hlbptr,hrtype,hrappl,hrcmd,hrlogmod,hrrepl,hrnotify,hrpri)

PL/I MACRO FORMAT: CNMHREGIST TYPE(hrtype) APPL(hrappl) COMMAND(hrcmd) LOGMODE(hrlogmod) REPLACE(hrrepl) NOTIFY(hrnotify) PRI(hrpri)

C INVOCATION: void Cnmhrgs(char *hrtype, char *hrappl, char *hrcmd, char *hrlogmod, char *hrrepl char *hrnotify, char *hrpri)

Where: hlbptr A 4-byte pointer field containing the address of the HLB control block. hrappl An 8-byte character field that specifies the application to be registered or de-registered. The identifier name can be one of: v An architecturally defined 4-byte value (padded with blanks to 8 bytes) for high-performance application programs. The following names are reserved by NetView and cannot be specified in a CNMHRGS invocation:

208 Programming: PL/I and C CNMHRGS (CNMHREGIST)

ALERT X'23F0F3F1' EP_OPS X'23F0F1F6' EP_SPCS X'23F0F1F4' LINKSERV X'23F0F3F5' MDS_RECEIVE X'23F0F0F1' MDS_ROUTER X'23F0F1F0' MS_CAPS X'23F0F1F1' OPS_MGMT X'23F0F1F7' R_BRIDGE X'30F0F5F9' RTMCMD_O X'30F0F7F2' RMTCMD_R X'30F0F5F5' RTMCMD_S X'30F0F7F0' SPCS X'23F0F1F5' No character equivalent X'30F0F7F3' v A 1–8 character installation-defined name (padded with blanks). Use the EBCDIC characters 0–9 and A-Z (capitals only). The name STATUS is reserved for the NetView status focal point and is not allowed on a CNMHRGS invocation. hrcmd An 8-byte character field that specifies the command processor that is started when unsolicited or asynchronous data is routed to the application. The NetView program verifies that the task is authorized to issue the command specified on hrcmd. This field is required for REGAPPL. hrlogmod An 8-byte character field that specifies the logmode that is used for sending the application data. This name must be a logmode that is defined to the local VTAM and the receiving LU or command processor (CP) with which this application communicates.

Note: hrlogmod is used only on the initial registration request for an application. You cannot change a registered application’s logmode unless you deregister the application.

Chapter 11. Service reference 209 CNMHRGS (CNMHREGIST)

hrnotify An 8-byte character field that specifies whether the MS or operations management served application receives session outage notification for LUs in contact with the LU 6.2 sessions. ALL Indicates that the application receives an MDS-MU containing an SNA condition report with sense data every time the last SNASVCMG session has been lost. This notification is received even if the session outage is not related to an error. ERROR Indicates that the application receives an MDS-MU containing an SNA condition report with sense data every time the last SNASVCMG session has been lost because of session failure. NONE Indicates that the application does not receive session outage notification. NONE is the default for the PL/I macro format. If you do not specify the NOTIFY keyword when using the PL/I macro format, the default value is used. Otherwise, this field is required. hrpri An 8-byte character field that specifies the MQS priority for incoming requests. The MQS priority is used when the high-performance transport uses the MQS for processing any unsolicited MDS-MUs. HIGH Processing begins after any NORMAL requests currently in progress completes, but before queued NORMAL or LOW requests. LOW Processing is preempted by HIGH and NORMAL priority requests. This is the default. NORMAL Processing preempts a queue of LOW priority requests. TEST CNMHRGS queues the request based on the command priority of the receiving task. The command priority can be set using the OVERRIDE or DEFAULT commands. Refer to the IBM Tivoli NetView for z/OS Command Reference for more information. hrrepl A 4-byte character field that specifies whether this registration is to supersede any previous registration for this application. NO Specifies that this registration does not replace the current registration for this application. YES Specifies that this registration replaces the current registration for this application. YES is the default for the PL/I macro format.

This is a required field for REGAPPL. However, if you do not specify the REPLACE keyword in the PL/I macro format, the default value is used. hrtype A 10-byte character field that specifies the type of request: DEREGAPPL Deregisters an application from the high-performance transport. REGAPPL Registers an application to the high-performance transport.

210 Programming: PL/I and C CNMHRGS (CNMHREGIST)

Usage Notes: 1. If you specify a logmode that is not defined in the logmode table, VTAM defaults the logmode to the first entry in the logmode table. 2. The NetView task where an application receives an MDS-MU is determined as follows: v For an MDS reply, the receiving task is the task under which the requesting application was running. v For an MDS request, the receiving task is the task from which CNMHRGS is started for the receiving application. v For an MDS error message: – If the agent unit of work correlator (AUOWC) matches an active AUOWC in the active transaction list: - For an outgoing request, the receiving task is the task under which the requesting application was running. - For an incoming request, the receiving task is the task under which the receiving application was running. – If the AUOWC does not match an active AUOWC, the receiving task is the task from which CNMHRGS is started for the receiving application. 3. You can change the task under which CNMHRGS was started by registering the application from the desired task and specifying YES for hrrepl.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Successful registration/deregistration. CNM_NOT_FOUND 20 Deregistration unsuccessful. hrappl not registered. CNM_NO_STORAGE 24 Registration unsuccessful. No storage available. CNM_NOT_IN_ASYNCH 44 Deregistration unsuccessful. Issued from an installation exit. CNM_DUPL_NAME 104 Registration unsuccessful. hrappl already registered. CNM_BUSY 472 Registration/deregistration unsuccessful. Queues are in use. CNM_BAD_APPL_NAME 476 Registration/deregistration unsuccessful. hrappl syntax incorrect. CNM_APPL_NAME_RSTD 480 Registration/deregistration unsuccessful. hrappl restricted. CNM_BAD_REG_TYPE 492 Incorrect hrtype. CNM_BAD_REPLACE_VALUE 504 Incorrect hrrepl. CNM_BAD_LOGMODE 580 Registration unsuccessful, hrlogmod does not match the existing logmode for hrappl. CNM_LOGMODE_REQUIRED 584 Registration unsuccessful. A value for hrlogmod is required. CNM_BAD_NOTIFY 592 Incorrect rgnotify value specified. CNM_BAD_CES + X 9000 + X Registration unsuccessful. Nonzero return code, X, from DSICES macro using hrcmd.

Chapter 11. Service reference 211 CNMHSMU (CNMHSENDMU)

CNMHSMU (CNMHSENDMU): Send high-performance message unit The CNMHSMU service routine enables NetView applications to send data to a specified target through the high-performance transport API. The high-performance transport uses an LU 6.2 conversation, and VTAM selects the appropriate session for the actual transmission. You can invoke CNMHSMU only in applications registered through CNMHRGS or the REGISTER command.

The data is sent in the form of an MDS-MU. You can supply: v A completely built MDS-MU v An MDS-MU that is missing one or more of: – A unit of work correlator (UOWC) – An origin NETID – An origin LUNAME v A GDS variable that can be contained in an MDS-MU, and can supply sufficient other fields for the service routine to build an MDS-MU header. Refer to the SNA library for more information about MDS-MUs and GDS variables.

The CNMHSMU service routine builds the necessary NetView MQS buffer with the specified data and queues it to the high-performance transport.

The CNMHSMU routine syntax follows:

PL/I CALL FORMAT: CALL CNMHSMU(hlbptr,hsdtype,hsdata,hssupcor,hscorrar, hstimout,hssynch,hsrplcmd, hsoappl,hsdstnet,hsdstlu,hsdstapl,hsmutype,hspri)

PL/I MACRO FORMAT: CNMHSENDMU DATATYPE(hsdtype) DATA(hsdata) SUPPCORREL(hssupcor) CORRELAREA(hscorrar) TIMEOUT(hstimout) SYNCH(hssynch) REPLYCMD(hsrplcmd) ORIGAPPL(hsoappl) DESTNET(hsdstnet) DESTLU(hsdstlu) DESTAPPL(hsdstapl) MUTYPE(hsmutype) PRI(hspri)

C INVOCATION: void Cnmhsmu(char *hsdtype, void *hsdata, void *hssupcor, void *hscorrar, int hstimout, char *hssynch, char *hsrplcmd, char *hsoappl, char *hsdstnet, char *hsdstlu, char *hsdstapl, int hsmutype, char *hspri)

where: hlbptr A 4-byte pointer field containing the address of the HLB control block. hscorrar A 53-byte character field in which a new unit of work correlator (X'1549') GDS variable is created and returned by the CNMHSMU service routine. If you specify hscorrar for an MDSMU, NetView creates the unit of work correlator in this area and inserts it into the specified MDS-MU while copying it into the buffer for the high-performance transport. If you omit hscorrar, the MDS-MU must be complete and ready to be transmitted as supplied.

212 Programming: PL/I and C CNMHSMU (CNMHSENDMU)

For a NONMDSMU, specify either hscorrar or hssupcor. If you specify hscorrar, CNMHSMU creates the unit of work correlator GDS variable in this area and uses it in building the MDS header. If you specify both hssupcor and hscorrar, hssupcor is used. hsdata A varying length character field containing the data being sent. For either MDSMU or NONMDSMU the first 2 bytes must contain the entire length of the data and the next 2 bytes must contain the key. hsdstapl An 8-byte character field that specifies the destination high-performance application name. The application name can be one of: v An architecturally defined 4-byte value (padded with blanks to 8 bytes) for MS application programs. v A 1–8 character installation-defined name (padded with blanks). Use the EBCDIC characters 0–9 and A-Z (capitals only). v A 1–8 character NetView-reserved name (padded with blanks) that represents an architecturally defined 4-byte value. The NetView-defined names and their corresponding values follow: ALERT X'23F0F3F1' EP_ALERT X'23F0F3F0' EP_OPS X'23F0F1F6' MS_CAPS X'23F0F1F1' OPS_MGMT X'23F0F1F7' This field is required for NONMDSMU. hsdstlu An 8-byte character field that specifies the LU name of the destination LU. Specify the 1–8 character LU name (padded with blanks to 8 characters) beginning with an EBCDIC character 0–9 and A-Z (capitals only), @, #, or $, and followed by EBCDIC characters 0–9 and A-Z (capitals only). This field is required for NONMDSMU. hsdstnet An 8-byte character field that specifies the ID of the network of the destination LU. Specify the 1-8 character NETID (padded with blanks to 8 characters) beginning with an EBCDIC character, @, #, or $, and followed by EBCDIC characters 0–9 and A-Z (capitals only). The value of this field defaults to the network name that VTAM determines based on the LU name of the remote node (specified with the hsdstlu field) if you: v Specify blanks for this field for the PL/I call format. v Do not specify the DESTNET keyword when using the PL/I macro format. v Specify blanks for this field for the C invocation format.

Chapter 11. Service reference 213 CNMHSMU (CNMHSENDMU)

hsdtype An 8-byte character field indicating whether the data item specified with the hsdata field is an MDS-MU or a non-MDS-MU. MDSMU Indicates that the hsdata is an MDS-MU. MDSMU is the default for the PL/I macro format. NONMDSMU Indicates that the hsdata is not a complete MDS-MU because it does not contain an MDS-MU header. The CNMHSMU service routine envelopes this data in an MDS-MU header before sending it.

If you do not specify the DATATYPE keyword when using the PL/I macro format, the default value is used. hsmutype A 4-byte integer field that specifies the index number that identifies the type of MDS-MU to build. The type identifies whether the MDS-MU is a request, a reply, or an error message, and whether additional messages are expected. The following types are defined as constants: 1 REQUEST_WITH_REPLY 2 REQUEST_WITHOUT_REPLY 3 REPLY_ONLY 4 REPLY_NOTLAST 5 REPLY_LAST 6 ERROR_MESSAGE This is a required keyword for NONMDSMU. hsoappl An 8-byte character field that specifies the origin high-performance application name. The application name can be one of the following values: v An architecturally defined 4-byte value (padded with blanks to 8 bytes) for high-performance application programs. v A 1-8 character installation-defined name (padded with blanks). Use the EBCDIC characters 0–9 and A-Z (capitals only). This field is required for NONMDSMU. hspri An 8-byte character field that specifies the MQS priority for incoming solicited requests or any MDS error messages resulting from any outgoing MDS-MUs. The MQS priority is used when the high-performance transport uses the MQS for processing any solicited MDS-MUs or any MDS error messages. HIGH Processing begins after any NORMAL requests currently in progress completes, but before queued NORMAL or LOW requests. LOW Processing is preempted by HIGH and NORMAL priority requests. This is the default for all requests other than synchronous requests. NORMAL Processing preempts a queue of LOW priority requests. This is the default for synchronous requests.

214 Programming: PL/I and C CNMHSMU (CNMHSENDMU)

TEST CNMHSMU queues the request based on command priority of the receiving task. The command priority can be set using the OVERRIDE or DEFAULT commands. Refer to the IBM Tivoli NetView for z/OS Command Reference for more information. hsrplcmd An 8-byte character field containing the name of the command to be driven with the reply. The hsrplcmd field is used only in an application that is sending REQUEST_WITH_REPLY with the reply being received asynchronously. Otherwise, it is ignored. This is an optional field. The default is the registered command for the invoking application. hssupcor A varying length character field containing a complete unit of work correlator (X'1549') GDS variable. The hssupcor field must contain a 2-byte length, a 2-byte key, and at least 1 byte of correlator data. Refer to the SNA library for more information about defining the correlator. hssupcor is not valid for an MDS-MU. For a NONMDSMU, specify either hssupcor or hscorrar. If you specify hssupcor, the supplied value is used to build the MDS header. No validity checking is done for a correlator supplied by the invoker. hssynch An 8-byte character field that specifies whether the high-performance application is to receive the reply synchronously. NO Indicates that the reply is received asynchronously. NO is the default for the PL/I macro format. NO_BUF Do not suspend the application but buffer replies until the last is received. This value is equivalent to the NO value. NO_UNBUF Do not suspend the application and forward replies immediately. YES Indicates that the reply is received synchronously. YES_BUF Suspend the application and buffer its replies. This value is equivalent to the YES value. If you do not specify the SYNCH keyword when using the PL/I macro format for REQUEST_WITH_REPLY, the default value is used. Otherwise, the field is required for REQUEST_WITH_REPLY. hstimout A 4-byte integer field that specifies the number of seconds to wait for the reply of an outstanding REQUEST_WITH_REPLY. For a REQUEST_WITH_REPLY that generates multiple replies, the timeout value applies only to the last reply. The NetView program initializes default and maximum timeout values for the LU 6.2 transport send services. The initial default and maximum timeout values are 120 and 86400 seconds, respectively. You can change these values with the DEFAULTS command. The valid values for hstimout are: 1 ... X Where X is the maximum timeout value.

Chapter 11. Service reference 215 CNMHSMU (CNMHSENDMU)

0 Indicates the default timeout value. -1 Indicates the maximum timeout value. If you do not specify the SECONDS keyword when using the PL/I macro format for REQUEST_WITH_REPLY, the default timeout value is used. Otherwise, this field is required for REQUEST_WITH_REPLY.

Usage Notes: 1. For a synchronous REQUEST_WITH_REPLY, control is returned to the invoking program after the last reply, or an error message is received and placed on the MDSMUQ data queue. Otherwise, control is returned after CNMHSMU successfully queues the request to the high-performance transport. 2. When the invoking program is suspended because of a synchronous REQUEST_WITH_REPLY, the NetView task where the program is running is not suspended. The task still receives and processes messages and commands. 3. For a synchronous REQUEST_WITH_REPLY from a DST, a DSRB is marked in-use and the DSRB is not available for other use until the suspended program is started again. 4. For MDSMU, all fields within the MDS-MU header must be correct except for origin NETID and LUNAME. The service routine can determine and set these fields. If the correlator is not contained in the data, specify hscorrar. 5. For REPLY_ONLY, REPLY_NOTLAST, REPLY_LAST, and ERROR_MESSAGE, specify hssupcor to return the correlator sent with the request. 6. The high-performance transport implements a timeout value for the application receiving the data. If the invocation of CNMHSMU specifies a timeout value greater than the timeout value set by the transport at the receiving node, the sending application might time out in less than the specified interval. 7. When VTAM is active, you can use CNMHSMU to send data to another application in the same domain. 8. If hsdstnet is not the NETID determined by VTAM for the LU specified in hsdstlu, the send fails. 9. A high-performance application cannot send data to itself within the same NetView. 10. A return code 24 or 28 from DSIPUSH indicates that DSIOLGFP is not defined correctly in DSIPARM member CNMCMD. 11. If CNM_BAD_CES is returned: v Verify that DSI6SNDP is defined correctly in member CNMCMD. v If you specify hrrepcmd, verify that it is defined correctly in member CNMCMD. v If you specify a synchronous REQUEST_WITH_REPLY, verify that DSIOSRCP is defined correctly in member CNMCMD. 12. Refer to the IBM Tivoli NetView for z/OS Administration Reference for the correct definitions of the command processors supplied by the NetView product. 13. For MDSMU, if you omit the NETID subfield of the destination subvector from the MDS-MU header, VTAM determines the network name used, based on the LU name in the NAU name subfield of the destination subvector. 14. If you do not specify the destination NETID, and the destination LU name exists in more than one network, VTAM determines the destination NETID based on the active configuration.

216 Programming: PL/I and C CNMHSMU (CNMHSENDMU)

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_BAD_INVOCATION 4 Task is ending, TVBABEND/ TVBLOGOF is on. CNM_NO_STORAGE 24 No storage is available. CNM_NOT_IN_ASYNCH 44 Send MU service is started from an installation exit. CNM_BAD_TIMEOUT 56 Timeout value is not valid. CNM_BAD_LENGTH 88 MDS-MU length is not valid. CNM_TASK_INACTIVE 220 DSIHPDST not active. CNM_BAD_DATA_TYPE 400 Data type is not valid. CNM_BAD_DATA 404 Data missing or is not valid. CNM_SAME_APPL 408 Application cannot send data to the same application within the same NetView program. CNM_SYNCH_NOT_COMP 412 SYNCH(YES) is not allowed under a NetView installation exit or the PPT. CNM_OAPPL_NOT_REG 416 Application is not registered. CNM_BAD_UOW 424 UOW is missing or not valid. CNM_BAD_OAPPL 440 Origin application name is not valid. CNM_BAD_DNETID 444 Destination network ID missing or is not valid. CNM_BAD_DLU 448 Destination LU name is not valid. CNM_BAD_DAPPL 452 Destination application name is not valid. CNM_BAD_REPLY 460 Reply is not valid. CNM_BAD_MUTYPE 464 Bad MUTYPE given. CNM_BAD_SYNCH 468 Bad SYNCH option. CNM_BUSY 472 User list is full. CNM_SYNCH_CMD_MISSING 508 SYNCH(YES) is specified but DSIOSRCP or DSIOLGFP is not defined or is not defined correctly in DSIPARM member CNMCMD. CNM_REQ_CANCELED 552 Synchronous request cancelled by user. CNM_TASK_NO_AUTH 556 Task does not have authorization to run the registered command associated with the origin application name. CNM_SNACR_MISSING 588 SNA condition report (X'1532') is missing from the MDS error message. CNM_NETID_UNINIT 596 NETID is not initialized. CNM_BAD_MQS + X 1000 + X Nonzero return code, X, from DSIMQS macro. CNM_BAD_PUSH + X 4000 + X X is the return code from DSIPUSH. CNM_BAD_CES + X 9000 + X Nonzero return code, X, from DSICES macro.

Chapter 11. Service reference 217 CNMINFC (CNMINFOC)

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMINFC (CNMINFOC): Query NetView Character Information The CNMINFC service routine allows you to obtain information about the current NetView environment. CNMINFC returns character data.

The CNMINFC routine syntax follows:

PL/I CALL FORMAT: CALL CNMINFC (hlbptr,icname,icdata,icdatlen)

PL/I MACRO FORMAT: CNMINFOC ITEM(icname) DATA(icdata) LENG(icdatlen)

C INVOCATION: void Cnminfc(char *icname, void *icdata, int icdatlen)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. icdata Is a varying length character field containing the character data to be returned. icdatlen Is a 4-byte integer field containing the length of icdata. This is the maximum length of the area provided to receive the returned data. You provide the value of icdatlen. This field must be greater than 0 and less than 32729. If the value specified by icdatlen is less than the length of the data to be returned, the truncated data is returned in icdata and a return code of CNM_DATA_TRUNC is generated. The full length of the data that was truncated is stored in HLBLENG (Hlbleng). If the value specified by icdatlen is equal to or greater than the length of the data to be returned, and HLBRC (Hlbrc) = CNM_GOOD, the length of the returned data is stored in HLBLENG (Hlbleng). If the value specified by icdatlen is greater than the length of the receiving data buffer (icdata), a storage overlay can occur. icname Is an 8-byte character field that specifies the name of a variable. Valid names are: APPLID Is the NetView domain ID appended with a 3-character alphanumeric value assigned by the NetView program. AUTCONID Is the MVS console identifier associated with this autotask. This association was made using the AUTOTASK command with the console keyword. This value of AUTCONID is the console name of the MVS console where NetView commands can be entered to run under this autotask. CLOCK Is the current value returned by STCK instruction (not displayable).

218 Programming: PL/I and C CNMINFC (CNMINFOC)

CURCONID Is the MVS console obtained by a NetView task. This console was obtained with the GETCONID command or by issuing an MVS command. The value of CURCONID is the console name of the MVS console that this task uses to enter MVS commands. CURSYS Is a 1- to 8-character name of the current operating system. DATE Is the current date in the form of mm/dd/yy, where mm is the month, dd is the day, and yy is the year. DATETIME Equivalent to &DATE followed by &TIME. DATETIM2 Is the date and time in the YYYYMMDD HH:MM:SS format. DOMAIN Is the 1- to 5-character name of the current NetView domain. ECVTPSEQ | Is the z/OS product sequence number found in the MVS IHAECVT | data area. HCOPY Is the name of the device defined as the hardcopy log printer started by the operator. If there is no device defined as the hardcopy printer for this operator, HCOPY is null. IPV6 Indicates the IPv6Env setting in the CNMSTYLE member: 4 Indicates that the IPv6Env statement is set to NONE. 6 Indicates that the IPv6Env statement is set to ONLY. M Indicates that the IPv6Env statement is set to MIXED. LU Is the logical unit name for the operator terminal. MVSLEVEL | Is the currently running version of MVS. NETID Is the VTAM network identifier. This field has a maximum length of 8 characters.

| Note: If VTAM has never been active while NetView is active, the | value is assigned from the NETID statement in the CNMSTYLE | member. NVVER Is the version and release of the currently running NetView program. The value of NVVER is a 4-character string in the form of NVvr, where: NV Indicates NetView. v Indicates the version number of NetView. r Indicates the release number of NetView. OPID Is the operator or task ID that issued the call to CNMINFC. OPID is a 1- to 8-character identifier.

Chapter 11. Service reference 219 CNMINFC (CNMINFOC)

OPSYSTEM Is the operating system for which NetView was compiled, and the HLL command processor or installation exit routine is running. OPSYSTEM must be MVS/ESA. OWNER Is the operator ID of the task that owns the VOST. Note that data is only returned for VOST tasks. PID The process ID for this HLL command processor or installation exit routine. Used for CNMSMSG with smmsgtyp=DATA (not displayable). STARTIME The NetView start time (not displayable). SUPPCHAR Is the 1-character NetView suppression character. SYSPLEX Is the 1- to 8-character name of the MVS SYSPLEX where the command list is executing.

Note: This function has a value only if the command list is executing on an MVS SYSPLEX or on an MVS system that specified a sysplex name in a couple data set. TASK Is a character string indicating the type of task under which the command processor or installation exit routine is running. Possible values follow: DST Data Services Task HCT Hardcopy Task MNT Main Task NNT NetView-to-NetView Task OPT Optional Task OST Operator Station Task PPT Primary POI Task UNKNOWN None of the above. TASKNAME The name of the task under which the HLL command processor or installation exit routine is running. TIME Is the CPU time in the form of hh:mm, where hh is the hour and mm is the minutes. The time is based on a 24-hour clock, so 3:00 P.M. is shown as 15:00. VTAM Is the version and release of VTAM is a 4-character string in the form of either VTvr or Vvrm, where: VT Indicates that the access method is the VTAM program. v Indicates the version number r Indicates the release number m Indicates the modification number

220 Programming: PL/I and C CNMINFC (CNMINFOC)

Note: The value of the VTAM is null if the VTAM program is not active. VTCOMPID Is a 14-character VTAM component identifier. The VTAM component identification can be: 5695-11701-xxx

Where: xxx is the release number. Additional VTAM component identifiers can be added in future updates to VTAM.

Note: The value of VTCOMPID is null if VTAM is not active. YEAR Is the 4-digit year.

Usage Notes: 1. Refer to IBM Tivoli NetView for z/OS Programming: REXX and the NetView Command List Language for a complete description of the NetView command list language variables. 2. CLOCK, PID, and STARTIME are 8-character representations of the TOD-clock (time-of-day) value returned by the STCK instruction.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 The value requested is returned in icdata. CNM_DATA_TRUNC 40 icdatlen was too small. Data truncated. CNM_BAD_FUNC 52 Incorrect icname. Value unchanged. CNM_BAD_LENGTH 88 icdatlen less than (<) 0. CNM_BAD_ADDR 160 The storage pointed to by icdata is not addressable.

CNMINFI (CNMINFOI): Query NetView Integer Information Use the CNMINFI routine to obtain information about the current NetView environment. CNMINFI returns integer data.

The CNMINFI routine syntax follows:

PL/I CALL FORMAT: CALL CNMINFI(hlbptr,iiname,iinumb)

PL/I MACRO FORMAT: CNMINFOI ITEM(iiname) DATA(iinumb)

C INVOCATION: void Cnminfi(char *iiname, int *iinumb)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block.

Chapter 11. Service reference 221 CNMINFI (CNMINFOI)

iiname Is an 8-byte character field that specifies the name of the variable. Valid names are: ABENDRTN1 If processing as a long-running command ABEND routine, then return true. ASID Is the NetView's current address space identifier. The value of ASID is a 1-to 5-digit decimal number. ATTENDED1 Is a single character variable with a value of 1 or 0. The values for ATTENDED are: 1 Indicates one of the following tasks: v An OST with a display v An NNT with a corresponding OST v An autotask with an associated MVS console assigned using the AUTOTASK command v A distributed autotask 0 Indicates one of the following tasks: v An autotask without an associated MVS console assigned using the AUTOTASK command v Another type of task, such as a DST or an OPT task

Note: 1. If the associated operator is an autotask, the presentation data is not eligible for display unless the autotask is associated with an active MVS console. 2. ATTENDED can be used in conjunction with DISTAUTO and AUTOTASK variables to further define the characteristics of the task. For example, if ATTENDED is 1, DISTAUTO is 0, and AUTOTASK is 1, then the task is an autotask with an associated MVS console. AUTOTASK The single character value of either 1 or 0 indicating whether or not a task is an autotask. The values follow: 1 Indicates that the task is an autotask 0 Indicates that the task is not an asterisk

These iinames contain Boolean values (0 = false and 1 = true). AWAITINP1 If waiting for operator input, then return true. CLOSING1 If NetView is terminating, then return true. COLORS Is the number of colors that can be displayed.

1. These iinames contain Boolean values (0 = false and 1 = true).

222 Programming: PL/I and C CNMINFI (CNMINFOI)

DISTAUTO Denotes if task is a distributed autotask started with the RMTCMD command. The values are as follows: 1 Indicates the task is a distributed autotask 0 Indicates the task is not a distributed autotask LOGOFRTN1 If processing as a long-running command routine, then return true. MVTUFLD Is the user field from the DSIMVT NetView control block (MVTUFLD). OPER32701 If an OST with a 327x display terminal is attached, then return true. RESETREQ1 If RESET or CANCEL was requested, then return true. the internal RESET flag is turned off as a result of this query. See “RESET command” on page 179 for further details. SCRNSER Is the return serial number of the screen update. TIBUFLD Is the user field from the DSITIB NetView control block (TIBUFLD). TVBUFLD Is the user field from the DSITVB NetView control block (TVBUFLD). USEREXIT If the integer value is 0, the environment is that of a command processor. If the integer value is 2–17, the environment is that of an installation exit. If the integer value is one of the following values, the environment is that of an installation exit running under a DST: 233 USERDINT DSM initialization exit 234 USERVINT VSAM initialization exit 235 USERVINP VSAM input exit 236 USERVOUT VSAM output exit 237 USERCINP CNMI input exit 238 USERCOUT CNMI output exit 240 USERXLOG External log exit 241 USERBINT Sequential log initialization exit

Chapter 11. Service reference 223 CNMINFI (CNMINFOI)

242 USERBOUT Sequential log output exit

See DSIPCONS in Appendix A, “PL/I Control Blocks and Include Files,” on page 269 or DSICCONS in Appendix C, “C language control blocks and include files,” on page 279 for a list of constants useful when coding installation exit routines. WEEKDAYN Is a numeric value from 1 to 7 indicating the day of the week (from Monday through Sunday). These are the values that are returned: 1 = Monday 2 = Tuesday 3 = Wednesday 4 = Thursday 5 = Friday 6 = Saturday 7 = Sunday iinumb Is a 4-byte integer field containing the integer value returned.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 The value requested is returned in iinumb. CNM_BAD_FUNC 52 Incorrect iiname. Value unchanged. CNM_BAD_ADDR 160 The storage pointed to by iinumb is not addressable.

CNMIPXL (CNMIPXLATE): IP Address Translation The CNMIPXL service routine can be used by writers of HLL command procedures to validate a presentation form IP address and convert it to another format, either a standard format or a compressed format. It can also convert an IP address in binary to a presentation form of the IP address.

The CNMIPXL routine syntax follows:

PL/I CALL FORMAT: CALL CNMIPXL(hlbptr,xltype,xlinData,xlinLen,xloutData,xloutLen)

PL/I MACRO FORMAT: CNMIPXLATE TYPE(xltype) INDATA(xlinData) INLEN(xlinData) OUTDATA(xloutData) OUTLEN(xloutLen)

C INVOCATION: void Cnmipxl(char *xltype, void *xlinData, int xlinLen, void *xloutData, int xloutLen)

Where:

224 Programming: PL/I and C CNMIPXL (CNMIPXLATE) hlbptr A 4-byte pointer containing the address of the HLB control block. xltype An 8-byte string containing the type of IP address verification or translation to be done. The valid strings follow: PCHECK Verify that the input data is an IP address in presentation form. P2PV4 Convert an IP address in presentation form to standard presentation form, in which IPv4, IPv4-mapped IPv6, and IPv4-compatible IPv6 addresses are presented in dotted decimal IPv4 address format. The IPv6 addresses are presented in colon hex format. In a standard presentation form, all segments of an address are present and leading zeros are removed. P2PV6 Convert an IP address in presentation form to an IPv6 presentation form. The IPv4 and IPv4-mapped IPv6 addresses are presented as IPv4-mapped IPv6 addresses. All IP addresses are returned in standard presentation form. P2PCOMP Convert an IP address in presentation form to presentation form compressed, in which one group of multiple, consecutive zero address segments is replaced by a double-colon (::). The compression only applies to IPv4-mapped IPv6, IPv4-compatible IPv6, and IPv6 addresses. The IPv4 addresses are returned in standard presentation form. P2NV4 Convert an IP address in presentation form to a 4-byte binary (network byte order) representation of an IPv4 address. Only IPv4, IPv4-mapped IPv6, and IPv4-compatible IPv6 addresses can be converted. P2NV6 Convert an IP address in presentation form to a 16-byte binary (network byte order) representation of an IP address. An IPv4 address is converted to the binary representation of an IPv4-mapped IPv6 address. N2PSTD Convert an IP address in binary (network byte order) to a standard presentation form. The IPv4, IPv4-mapped IPv6, and IPv4-compatible IPv6 addresses are converted to the dotted decimal IPv4 address format. N2PSTDM4 Convert an IP address in binary to a standard presentation form. The IPv4-mapped IPv6, IPv4-compatible IPv6, and IPv6 addresses are returned in their standard presentation forms. An IPv4 address is returned in IPv4-mapped IPv6 presentation form. N2PSTDC4 Convert an IP address in binary to a standard presentation form. This is similar to the N2PSTDM4 option, except that an IPv4 address is returned in an IPv4-compatible IPv6 presentation form. N2PV4 Convert an IP address in binary to the dotted decimal standard

Chapter 11. Service reference 225 CNMIPXL (CNMIPXLATE)

presentation form for an IPv4 address. Only IPv4, IPv4-mapped IPv6, and IPv4-compatible IPv6 addresses can be converted in this format. N2PCOMP Convert an IP address in binary to its presentation form compressed. An IPv4 address is returned in dotted decimal standard presentation form, while all other address types are compressed, if possible. xlinData A 4-byte pointer field containing the address of the IP address data to be verified or translated. xlinLen A 4-byte integer containing the length of the input IP address data. xloutData A 4-byte pointer field containing the address of an area into which a converted IP address is to be placed. This parameter is ignored if PCHECK is requested. The caller is expected to provide sufficient storage for the data that can be returned. xloutLen A 4-byte integer containing the length of the area into which the converted IP address data is to be placed. This parameter is ignored if PCHECK is requested.

Usage Notes: 1. Upon return to the caller, Hlbrc (C) or HLBRC (PL/I) contains the return code from the IP address verification/translation service. When the call is for an IP address translation request and the return code is CNM_GOOD, Hlbleng (C) or HLBLENG (PL/I) contains the length of the translated IP address data placed in the output data area. 2. When using CNMIPXL with C, xlinData and xloutData (if the requested type is not PCHECK) must be passed as addresses of pointers to the respective IP address data areas. As an example, assume that inData has been defined as an area that holds IP address data to be converted and outData has been defined as the area to contain the translated IP address. The following lines illustrate how this information would then be passed to the CNMIPXL service: /* Define the pointers to the IP address data areas. */

void *pInIPAddress; void *pOutIPAddress;

/* Sets the input and output data pointers for the Cnmipxl call. */

pInIPAddress = (void *)&inData; xlinData = (void *)&pInIPAddress;

pOutIPAddress = (void *)&outData; xloutData = (void *)&pOutIPAddress; 3. If an IP address translation request succeeded but the translated IP address data did not fit in the area whose length is contained in xloutLen, then the following things happen: v The xloutLen bytes of translated IP address data are placed in the output data area v Hlbrc (C) or HLBRC (PL/I) is set to CNM_DATA_TRUNC v Hlbleng (C) or HLBLENG (PL/I) is set to the size of the storage area that would be necessary to hold the translated IP address data

226 Programming: PL/I and C CNMIPXL (CNMIPXLATE)

Return Codes:

Return Code Name Value Description CNM_GOOD 0 IP address verified or translated. CNM_DATA_TRUNC 40 IP address translated but did not fit into output data area. CNM_BAD_FUNC 52 Incorrect xltype value. CNM_BAD_LENGTH 88 Incorrect xlinLen or xloutLen. CNM_BAD_ADDR 160 Effectively zero xlinData or xloutData. CNM_BAD_P_IPXLATE + x 26000 + x Failed IP address verification or translation. The x is the return code from a service routine that handles presentation form verification and translation. CNM_BAD_N_IPXLATE + 27000 + x Failed IP address translation. The x is the x return code from a service routine that handles network byte order (binary) translation.

CNMKIO (CNMKEYIO): Keyed File Access Under a DST The CNMKIO service routine provides access to DST managed key-sequenced VSAM files from an HLL command processor. This service routine performs its function only when started from an HLL command processor running under a DST. Calls from other environments are rejected.

The CNMKIO routine syntax follows:

PL/I CALL FORMAT: CALL CNMKIO(hlbptr,vsfunc,vsdata,vsdatlen,vskey,vsoption)

PL/I MACRO FORMAT: CNMKEYIO FUNC(vsfunc) DATA(vsdata) LENG(vsdatlen) KEY(vskey) OPTIONS(vsoption)

C INVOCATION: void Cnmkio(char *vsfunc, void *vsdata, int vsdatlen, void *vskey, char *vsoption)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. vsdata Is a varying length character field containing the buffer to be returned or written. You provide this field for PUT. This field is returned for GET and is not required for ERASE or ENDREQ. vsdatlen Is a 4-byte integer field containing the length of vsdata. This is the maximum length of the area provided to receive the returned data. You provide the value of vsdatlen. This field is required only for GET. If the value specified by vsdatlen is less than the length of the data to be returned, the truncated data is returned in vsdata and a return code of

Chapter 11. Service reference 227 CNMKIO (CNMKEYIO)

CNM_DATA_TRUNC is generated. The full length of the data that was truncated is stored in HLBLENG (Hlbleng). If the value specified by vsdatlen is equal to or greater than the length of the data to be returned, and HLBRC (Hlbrc) = CNM_GOOD, the length of the returned data is stored in HLBLENG (Hlbleng). If the value specified by vsdatlen is greater than the length of the receiving data buffer (vsdata), a storage overlay can occur. Take special care when deciding the value of vsdatlen. vsfunc Is an 8-byte character field that specifies the function to performed. ENDREQ Cancels a request for update. ERASE Erases the record. GET_EH Gets a record equal to or higher than the key. GET_EQ Gets a record equal to the key.

Note: The key field must match exactly, including blanks. GET_NEXT Gets the next record in ascending sequence. GET_PREV Gets the next record in descending sequence. PUT Writes or rewrites the record. vskey A varying length character field containing the VSAM key used for access to the requested data. This field is required for GET_EQ, GET_EH, or ERASE/DIRECT. vsoption Is an 8-byte character field that specifies the type of access to the file. You provide this field for all functions except ENDREQ. DIRECT Put a new record directly to the file or erase a record directly from the file (without invoking GET first). You can use PUT/DIRECT only for a new record. If the record already exists, CNM_DUPL_KEY is returned. For an existing record, ERASE/DIRECT gives the same result as GET/UPDATE followed by ERASE/UPDATE. If the record does not exist, CNM_NOT_FOUND is returned. You can use DIRECT only with PUT and ERASE. NOUPDATE The record is not updated. You can use NOUPDATE only with GET. UPDATE Get a record for update or replace. Erase the record that was gotten for update. PUT/UPDATE and ERASE/UPDATE must be preceded by a successful GET/UPDATE. You can use UPDATE only with GET, PUT, and ERASE.

228 Programming: PL/I and C CNMKIO (CNMKEYIO)

Usage Notes: 1. You cannot issue CNMKIO from an HLL installation exit routine or from an HLL command processor while holding a lock. 2. For more information about installing a DST, see Chapter 3, “HLL Data Services command processors,” on page 27.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_BAD_INVOCATION 4 Not started from a command processor. CNM_NOT_FOUND 20 Record with requested vskey not found. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro. CNM_END_FILE 36 End of file encountered. CNM_DATA_TRUNC 40 vsdatlen was too small. Data truncated. CNM_BAD_FUNC 52 Incorrect vsfunc. CNM_BAD_LENGTH 88 vsdatlen less than (<) 0. CNM_BAD_OPTION 128 Incorrect vsoption. CNM_BAD_ADDR 160 The storage pointed to by vsdata is not addressable. CNM_BAD_COMBO 176 Incorrect combination vsfunc and vsoption. CNM_DUPL_KEY 200 Record with requested key already exists. Existing record is not changed. CNM_LOCKED 208 CNMKIO issued while holding a lock. (CNM_BAD_ZVSMS + X) * (100 + X) * 256 Nonzero return code from DSIZVSMS. X is 256 + Y + Y the major return code from DSIZVSMS. Y is the minor return code from DSIZVSMS. CNM_DST_FAILURE + X 2000 + X Nonzero return code, X, which is the DSRB minor return code for solicited CNMI data or VSAM data set services.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler or the VSAM library for more information. CNMLK (CNMLOCK): Controlling a Lock You can use the CNMLK service routine to obtain, release, and test the control of a named lock. You can use this service to serialize access to resources shared by multiple tasks. CNMLK does not allow for serialization within a task. HLL command processors holding a lock cannot use any services that can suspend execution of an HLL command processor.

The CNMLK routine syntax follows:

PL/I CALL FORMAT: CALL CNMLK(hlbptr,lkfunc,lkname,lkscope,lkoption)

PL/I MACRO FORMAT: CNMLOCK FUNC(lkfunc) NAME(lkname) SCOPE(lkscope) OPTION(lkoption)

Chapter 11. Service reference 229 CNMLK (CNMLOCK)

C INVOCATION: void Cnmlk(char *lkfunc, void *lkname, char *lkscope, char *lkoption)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. lkfunc Is an 8-byte character field that specifies the function to be performed: LOCK Obtains control of the lock name. TEST Tests if the lock name is available. UNLOCK Releases control of the lock name. lkname Is a varying length character field to hold the user-defined name of the lock. (Length is 1–12 characters.) This field is required for all functions. lkoption Is an 8-byte character field that specifies whether the HLL command processor or installation exit routine waits for the lock to become available. This field is required only for LOCK. Possible values follow: NOWAIT Do not wait if the lock is not available. An appropriate return code is returned (CNM_LOCKED or CNM_LOCK_INUSE). WAIT Wait until the lock is available. The task is suspended. lkscope Is an 8-byte character field reserved for future use. Provide a null or blank value in this field for all functions.

Usage Notes: 1. Do not invoke CNMSMSG with smdestyp = OPER while holding a lock. The operator task can be running with autowrap off, and the HLL command processor or installation exit routine might hang waiting for the operator to clear the screen, thus holding the lock for an indefinite period. 2. A hierarchical order on lock requests is used to prevent deadlock. The alphabetical order of the lock names defines the hierarchy. Therefore, lock requests for lock names alphabetically less than or equal to a presently held lock name fail, and return code CNM_LOCKED is generated. For example, assume the last lock request was for lkname = GVARIABLE. A new lock request for lkname = TVARIABLE is successful because TVARIABLE is alphabetically greater than GVARIABLE. However, a new lock request for lkname = CVARIABLE is unsuccessful because CVARIABLE is alphabetically less than or equal to GVARIABLE. Return code CNM_LOCKED is generated and the lock request fails.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro. CNM_BAD_FUNC 52 Incorrect lkfunc.

230 Programming: PL/I and C CNMLK (CNMLOCK)

Return Code Name Value Description CNM_BAD_NAME 108 Length of lkname greater than (>) 12 characters or the specified lkname was not locked. CNM_BAD_OPTION 128 Incorrect lkoption. CNM_LOCKED 208 The lkname is unavailable because it is alphabetically less than or equal to the lock name of the last lock request. CNM_LOCK_INUSE 212 lkname is not available; currently held by another task. CNM_BAD_ENQ + X 21000 + X Nonzero return code X from DSIENQ macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler or the MVS/XA library for more information. CNMMEMC (CNMCLOSMEM): Close NetView Partitioned Data Set Use the CNMMEMC service routine to close a member of a NetView partitioned data set that was previously opened by CNMMEMO. The token returned by CNMMEMO must be passed to CNMMEMC to allow the file to be closed. All members opened by CNMMEMO are automatically closed at program termination.

The CNMMEMC routine syntax follows:

PL/I CALL FORMAT: CALL CNMMEMC(hlbptr,mctoken)

PL/I MACRO FORMAT: CNMCLOSMEM TOKEN(mctoken)

C INVOCATION: void Cnmmemc(int mctoken)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. mctoken Is a 4-byte integer field containing the token returned by CNMMEMO.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_BAD_TOKEN 32 Token not found. CNM_BAD_DKS + X 10000 + X Nonzero return code, X, from DSIDKS macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information.

Chapter 11. Service reference 231 CNMMEMO (CNMOPENMEM)

CNMMEMO (CNMOPENMEM): Open NetView Partitioned Data Set Use the CNMMEMO service routine to open members of NetView partitioned data sets. A token identifying the open member is returned to you. This token is passed to CNMMEMR to read records from the member and to CNMMEMC to close the member.

The CNMMEMO routine syntax follows:

PL/I CALL FORMAT: CALL CNMMEMO(hlbptr,motoken,moddname,momemnam)

PL/I MACRO FORMAT: CNMOPENMEM TOKEN(motoken) DATASET(moddname) MEMBER(momemnam)

C INVOCATION: void Cnmmemo(int *motoken, char *moddname, char *momemnam)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. moddname Is an 8-byte character field that specifies the DD name of the partitioned data set. The NetView predefined DD names are: BNJPNL1 BNJPNL2 CNMPNL1 DSICLD DSILIST DSIMSG DSIOPEN DSIPARM DSIPRF DSIVTAM momemnam Is an 8-byte character field that specifies the name of the member. motoken Is a 4-byte integer field containing the token to be used by subsequent CNMMEMR and CNMMEMC requests.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_BAD_DDNAME 16 Incorrect moddname (not found). CNM_NOT_FOUND 20 momemnam not found. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro.

232 Programming: PL/I and C CNMMEMO (CNMOPENMEM)

Return Code Name Value Description CNM_BAD_ADDR 160 The storage pointed to by motoken is not addressable. CNM_BAD_DKS + X 10000 + X Nonzero return code, X, from DSIDKS macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMMEMR (CNMREADMEM): Read NetView Partitioned Data Set Use the CNMMEMR service routine to read a record from a member of a NetView partitioned data set that was previously opened by CNMMEMO. The token returned by CNMMEMO must be passed to CNMMEMR to allow reading.

The CNMMEMR routine syntax follows:

PL/I CALL FORMAT: CALL CNMMEMR(hlbptr,mrtoken,mrdata,mrdatlen,mrinclude)

PL/I MACRO FORMAT: CNMREADMEM TOKEN(mrtoken) DATA(mrdata) LENG(mrdatlen) INCL(mrinclude)

C INVOCATION: void Cnmmemr(int mrtoken, void *mrdata, int mrdatlen, char *mrinclude)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. mrdata Is a varying length character field to contain the received record. mrdatlen Is a 4-byte integer field containing the length of mrdata. This is the maximum length of the area provided to receive the returned record. You provide the value of mrdatlen. If the value specified by mrdatlen is less than the length of the record to be returned, the truncated record is returned in mrdata and a return code of CNM_DATA_TRUNC is generated. The full length of the truncated record is stored in HLBLENG (Hlbleng). If the value specified by mrdatlen is equal to or greater than the length of the record to be returned, and HLBRC (hlbrc) = CNM_GOOD, the length of the returned record is stored in HLBLENG (Hlbleng). If the value specified by mrdatlen is greater than the length of the receiving data buffer (mrdata), a storage overlay can occur. mrinclude Is a 6-byte character field that specifies whether INCLUDE cards are to be processed: INCL Specifies to process INCLUDE cards. NOINCL Specifies that INCLUDE cards are not processed.

Chapter 11. Service reference 233 CNMMEMR (CNMREADMEM)

mrtoken Is a 4-byte integer field containing the token returned by CNMMEMO.

Usage Note: If the return code indicates that there was a problem with an INCLUDE card or the member specified by the include card (CNM_SYNTAX_ERROR, CNM_INVAL_MEMBER, CNM_INVAL_NEST, CNM_SYSTEM_ERROR), the record returned in mrdata is the INCLUDE card that is not valid.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_IOERROR 28 I/O error occurred. CNM_BAD_TOKEN 32 Token not found. CNM_END_FILE 36 End of file encountered. CNM_DATA_TRUNC 40 mrdatlen was too small. Data truncated. CNM_BAD_LENGTH 88 mrdatlen less than (<) 0. CNM_BAD_ADDR 160 The storage pointed to by mrdata is not addressable. CNM_SYNTAX_ERROR 520 Syntax error in INCLUDE card. CNM_INVAL_MEMBER 524 Incorrect member specified in INCLUDE card. CNM_INVAL_NEST 528 Incorrect nesting of INCLUDE cards. CNM_SYSTEM_ERROR 532 Internal NetView system error while processing INCLUDE card. CNM_BAD_INCLUDE 536 Incorrect value for mrinclude. CNM_BAD_DKS + X 10000 + X Nonzero return code, X, from DSIDKS macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMNAMS (CNMNAMESTR): Named Storage The CNMNAMS routine allows you to allocate, free, locate, and reallocate named areas of virtual storage.

The CNMNAMS routine syntax follows:

PL/I CALL FORMAT: CALL CNMNAMS(hlbptr,nsfunc,nsptr,nsname,nsleng,nsclass)

PL/I MACRO FORMAT: CNMNAMESTR FUNC(nsfunc) STRPTR(nsptr) NAME(nsname) LENG(nsleng) CLASS(nsclass)

C INVOCATION: void Cnmnams(char *nsfunc, void *nsptr, void *nsname, int *nsleng, int nsclass)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block.

234 Programming: PL/I and C CNMNAMS (CNMNAMESTR) nsclass Is a 4-byte integer field containing the class of the named storage area, as follows: 0 = Residency of caller 1 = 31-bit storage 2 = 24-bit storage

This field is required by the caller for ALLOC and REALLOC. This field is not required for FREE or LOCATE. nsfunc Is an 8-byte character field that specifies the function to be performed: ALLOC Allocates the named storage area. FREE Frees or deallocates the named storage area. LOCATE Locates the existing named storage area. REALLOC Reallocates the named storage area. Old data is preserved. nsleng Is a 4-byte integer field containing the size of the named storage area. This field is required by the caller for ALLOC and REALLOC and is returned to the caller for LOCATE. This field is not required for FREE. nsname Is a varying length character field containing the name of the storage area. This field is required for all functions and is provided by the caller. nsptr Is a 4-byte pointer field containing the address of the named storage. This field is required by the caller for ALLOC, REALLOC, and LOCATE. This field is not required for FREE.

Usage Notes: 1. The named storage areas provide a way of sharing data among different HLL command processors and installation exit routines or among multiple invocations of an HLL command processor or installation exit routine. When allocated, a named storage area remains allocated until it is either explicitly freed or the task under which it was allocated ends. 2. A named storage area is associated with the NetView subtask under which it was allocated. Named storage areas can be manipulated (using LOCATE, FREE, or REALLOCATE) only by HLL command processors and installation exit routines running under the mainline of that task. You cannot reference a named storage area from a task other than the one with which it is associated. 3. If ALLOC is requested for a name that has already been allocated, the address of the existing area is returned along with a nonzero return code. 4. If a previously allocated named storage area is reallocated to be larger than the original area, the content of the original area is preserved. If a previously allocated named storage area is reallocated to be smaller than the original area, the content of the original area is truncated at the length specified by the nsleng operand.

Chapter 11. Service reference 235 CNMNAMS (CNMNAMESTR)

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_NOT_FOUND 20 REALLOC, FREE, or LOCATE requested but no previous ALLOC was done. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro. CNM_BAD_FUNC 52 Incorrect function. CNM_BAD_LENGTH 88 nsleng less than (<) 0. CNM_DUPL_NAME 104 nsname already allocated. Allocation not done. CNM_BAD_NAME 108 Length of nsname greater than (>) 12 characters. CNM_BAD_CLASS 112 Incorrect nsclass. CNM_BAD_ADDR 160 The storage pointed to by nsname or nsleng is not addressable. CNM_BAD_PUSH + X 4000 + X Nonzero return code, X, from DSIPUSH macro. CNM_BAD_POP+X 5000 + X Nonzero return code, X, from DSIPOP macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMPMDB (CNMPRSMDB): Process Message Data Block The CNMPMDB service routine requests the NetView message processor to process a message data block (MDB) and its companion source object.

CNMPMDB accepts an MDB and a source object, transforms them into an automation internal function request (AIFR), and sends the AIFR through normal NetView message processing including invoking the automation table. The transformation of the MDB and source object into an AIFR includes establishing the values for the AIFR variables, such as MSGSRCNM and MSGSRCOB.

The CNMPMDB routine syntax follows:

PL/I CALL FORMAT: CALL CNMPMDB(hlbptr,mdmdb,mdsource,mdcorr)

PL/I MACRO FORMAT: CNMPRSMDB MDB(mdmdb) SOURCE(mdsource) CORREL(mdcorr)

C INVOCATION: void Cnmpmdb(void *mdmdb, void *mdsource, void *mdcorr)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. mdcorr Is a 16-character correlator value used for chaining together multiple related MDBs. Pass this parameter as all binary zeros for CNMPMDB invocations for single (non-chained) MDBs.

236 Programming: PL/I and C CNMNAMS (CNMNAMESTR)

For multiple related MDBs, pass all binary zeros for the mdcorr parameter on the first CNMPMDB invocation. CNMPMDB returns a correlator value in mdcorr. On subsequent calls to CNMPMDB for the multiple MDBs, pass the correlator value which was returned in mdcorr on the first invocation of CNMPMDB. When an MDB is sent with an end of text indicator, the mdcorr is returned with a zero value. mdmdb Is a 4-byte pointer field containing the address of an MDB. The maximum length of an MDB is 4 KB bytes. The maximum length of multiple related MDBs is 63 KB. mdsource Is a 4-byte pointer field containing the address of the source object. This is an optional field. If you do not want to specify a source object, pass zero in mdsource.

Usage Notes: 1. The CNMPMDB service routine returns control to the invoking program after it has scanned the automation table and done the synchronous portion of message processing. 2. The service does not free the MDB or source object. 3. If you create DOM MDBs, keep in mind that not all forms of DOM can be transported over OST-NNT sessions. If you are using any OST-NNT sessions, only create DOM MDBs that indicate DOM by MSGID.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 The MDB is accepted for processing. CNM_NO_STORAGE 24 Storage is not available. CNM_BAD_ADDR 160 The storage pointed to by mdcorr is not addressable. CNM_BAD_SEQUENCE 564 Third operand is not a valid correlator value. CNM_BAD_MDB 568 First operand is not valid for message data block (MDB). CNM_BAD_SOURCE_OBJ 572 Second operand is not a valid source object.

CNMPOOL (CNMSTRPOOL): Storage Pool You can use the CNMPOOL service routine to allocate, free, and locate storage pools. A storage pool is composed of one primary and zero or more secondary blocks of storage. Each storage block has a specified number of cells (of equal size) that can be allocated or freed using CNMCELL. Storage pool services provide a way to effectively manage large numbers of fixed size storage elements.

The CNMPOOL routine syntax follows:

PL/I CALL FORMAT: CALL CNMPOOL(hlbptr,spfunc,sptoken,spname,spleng,sppricnt, spseccnt,spclass)

Chapter 11. Service reference 237 CNMPOOL (CNMSTRPOOL)

PL/I MACRO FORMAT: CNMSTRPOOL FUNC(spfunc) TOKEN(sptoken) NAME(spname) LENG(spleng) PRICELLS (sppricnt) SECCELLS(spseccnt) CLASS(spclass)

C INVOCATION: void Cnmpool(char *spfunc, int *sptoken, void *spname, int spleng, int sppricnt, int spseccnt, int spclass)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. spclass Is a 4-byte integer field containing the storage class of the pool: 0 = Residency of caller 1 = 31-bit addressable 2 = 24-bit addressable

This field is required for ALLOC, but not for FREE or LOCATE. spfunc Is an 8-byte character field that specifies the function to be performed: ALLOC Allocates the pool FREE Frees the pool LOCATE Locates the pool spleng Is a 4-byte integer field containing the size of each cell in the pool. This field is required for ALLOC, but not for FREE or LOCATE. spname Is a varying length character field containing the name of the storage pool. This field is required for all functions and provided by the caller. sppricnt Is a 4-byte integer field containing the number of cells in the primary block. This field is required only for ALLOC. spseccnt Is a 4-byte integer field containing the number of cells in the secondary block. This field is required only for ALLOC. sptoken Is a 4-byte integer field to contain the token identifying the storage pool. This field is returned for ALLOC and LOCATE for use with CNMCELL service. This field is not required for FREE.

Usage Notes: 1. A storage cell within a pool is associated with the NetView subtask under which it was allocated. It cannot be referenced from a task other than the one with which it is associated. 2. All storage pool names must be unique within a given task.

238 Programming: PL/I and C CNMPOOL (CNMSTRPOOL)

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_NOT_FOUND 20 spname not found. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro. CNM_BAD_FUNC 52 Incorrect spfunc. CNM_BAD_LENGTH 88 spleng less than (<) 4. CNM_DUPL_NAME 104 spname already allocated. Allocation not done. CNM_BAD_NAME 108 Length of spname greater than (>) 12. CNM_BAD_CLASS 112 Incorrect spclass. CNM_BAD_ADDR 160 The storage pointed to by sptoken is not addressable. CNM_BAD_PRI_COUNT 192 Incorrect sppricnt. CNM_BAD_SEC_COUNT 196 Incorrect spseccnt.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMQAPI (CNMOPREP): Resource Object Data Manager The CNMQAPI service routine enables interaction with a specified resource object data manager (RODM). All RODM API functions are supported through this interface, including querying for data, changing data, and triggering methods.

Note: CNMQAPI applies only to those RODMs under the control of the DSIQTSK task. Refer to the IBM Tivoli NetView for z/OS Automation Guide for an example of managing your RODMs with DSIQTSK in a NetView automation scenario that uses RODM.

The CNMQAPI routine syntax follows:

PL/I CALL FORMAT: CALL CNMQAPI(hlbptr,qaacb,qatif,qaresp,qafunc,qawaitf,qawaitt)

PL/I MACRO FORMAT: CNMOPREP ACB(qaacb) TIF(qatif) RESPONSE(qaresp) FUNCTION(qafunc) WAITF(qawaitf) WAITT(qawaitt)

C INVOCATION: void Cnmqapi (char*qaacb, char*qatif,char*qaresp, char*qafunc, char*qawaitf, int *qawaitt)

Where: hlbptr Is a 4-byte field containing the address of the HLB control block. qaacb Is a RODM access block following the format of the RODM API. For more information about RODM, refer to the IBM Tivoli NetView for z/OS Resource Object Data Manager and GMFHS Programmer's Guide. The access block contains these fields:

Chapter 11. Service reference 239 CNMQAPI (CNMOPREP)

orname This field specifies the name of the RODM that the caller wants to access. If this field is blank (X'40'), the current runtime RODM is used. The current runtime RODM is defined in the DSIQTSKI initialization member in DSIPARM with the AO parameter on the REP keyword. Refer to the IBM Tivoli NetView for z/OS Administration Reference for a description of the DSIQTSKI keywords. The name is left-justified and must be padded with blanks (X'40') to 8 characters. signon_token Specifies the RODM signon token to be used within the call. CNMQAPI ignores this field and fills it with the sign-on token received by DSIQTSK when it initially connects to the RODM being accessed. Refer to IBM Tivoli NetView for z/OS Administration Reference for more information. user_appl_id This field specifies the application name of the caller. CNMQAPI sets this field to the user application specified with the ID parameter of the REP keyword (of DSIQTSKI) for the RODM being accessed by this call. Refer to the IBM Tivoli NetView for z/OS Administration Reference for a description of the DSIQTSKI keywords. qafunc Is a varying length function block, following the format of the RODM API function block, that describes the function requested and all required parameters. The actual function block format depends on the function being requested. Refer to the IBM Tivoli NetView for z/OS Resource Object Data Manager and GMFHS Programmer's Guide for a description of the function block format. qaresp Is a response block following the format of the RODM API response block control structure. Refer to IBM Tivoli NetView for z/OS Resource Object Data Manager and GMFHS Programmer's Guide for information about the RODM response block. qatif Is a transaction information block following the format of the RODM API transaction information block. Refer to IBM Tivoli NetView for z/OS Resource Object Data Manager and GMFHS Programmer's Guide for a description of the RODM API transaction information block. qawaitf Specifies whether the request waits when a checkpoint is detected. If a checkpoint is in progress for the specified RODM, the request is placed on a queue until the checkpoint is complete. Upon checkpoint completion, the request is processed. Valid values follow: N Do not wait for checkpoint completion. N is the default. Y Wait for checkpoint completion. qawaitt Is a 2-byte field that specifies the maximum time in seconds for which the call is suspended if a checkpoint wait is to be started. The valid value range is 10—3600 seconds (1 hour). If you specify a time greater than 3600, 3600 is used. If you do not specify this field, the default specified with the T keyword of the DSIQTSKI initialization member for the DSIQTSK task is used.

240 Programming: PL/I and C CNMQAPI (CNMOPREP)

Refer to IBM Tivoli NetView for z/OS Administration Reference for more information.

Usage Notes: 1. An application can connect to RODM with an option specifying that RODM can truncate its responses if the application response block is smaller than the RODM response. If this option is used, RODM truncates the response, does not save the overflow data, and informs the application of the condition. This information is sent in the return code and reason code in the transaction information block. DSIQTSK connects using this option, saving CNMQAPI from having to deal with overflow cleanup. 2. CNMQAPI returns two sets of return codes. The caller can use either of them. The first set is in the transaction information block provided by the user upon invocation. These return codes are RODM return codes and are documented for each possible function in the IBM Tivoli NetView for z/OS Resource Object Data Manager and GMFHS Programmer's Guide. 3. The second set is in the HLB. The HLBRC field of the HLB contains a return code upon return from CNMQAPI. 4. APF-authorized command processors can access RODM without a password or password phrase. Provide a keyword for command processors that can be authority-checked to control access to RODM.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Successful. CNM_NO_PASSWORD 8 A command processor tried to access RODM without specifying a password or password phrase but was either not APF-authorized or the APF-authorization code was not 1. CNM_NO_REPOS 604 RODM not under control of RODM access and control component. CNM_API_FAILURE 608 CNMQAPI failure. Internal macro call failure—might be storage. CNM_INVAL_PARMS 612 Incorrect parameters received. CNM_NO_STOR 616 No storage. CNM_TIMEOUT 620 Checkpoint in progress. CNM_BAD_OPR 25000 + X Nonzero return code, X, from DSIOPR macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMRGS (CNMREGIST): Application Registration The CNMRGS service routine enables registration and deregistration of any MS application with the NetView MS transport, or any operations management served application with the NetView operations management application. In addition, MS applications can register as focal points while both MS applications and operations management served applications can register as capable of receiving focal point information. Refer to the IBM Tivoli NetView for z/OS Application Programmer's Guide for more information about management services and remote operations.

Chapter 11. Service reference 241 CNMRGS (CNMREGIST)

The CNMRGS routine syntax follows:

PL/I CALL FORMAT: CALL CNMRGS(hlbptr,rgtype,rgappl,rgcmd,rgfpcat,rgfocpt,rgrepl,rgnotify,rgpri)

PL/I MACRO FORMAT: CNMREGIST TYPE(rgtype) APPL(rgappl) COMMAND(rgcmd) FPCATEGORY(rgfpcat) FOCALPOINT(rgfocpt) REPLACE(rgrepl) NOTIFY(rgnotify) PRI(rgpri)

C INVOCATION: void Cnmrgs(char *rgtype, char *rgappl, char *rgcmd, char *rgfpcat, char *rgfocpt, char *rgrepl, char *rgnotify, char *rgpri)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. rgappl Is an 8-byte character field that specifies the MS application or operations management served application being registered or deregistered. The application name can be one of the following: v An architecturally defined 4-byte value (padded with blanks to 8 bytes) for MS application programs. The following names are reserved by NetView and cannot be specified in a CNMRGS invocation: Reserved Name Hex Equivalent ALERT X'23F0F3F1' EP_OPS X'23F0F1F6' EP_SPCS X'23F0F1F4' HMON_DST X'30F0F8F5' HMON_OST X'30F0F8F4' LINKSERV X'23F0F3F5' MS_CAPS X'23F0F1F1' MDS_ROUT X'23F0F1F0' OPS_MGMT X'23F0F1F7' RMTCMD_R X'30F0F5F5'

242 Programming: PL/I and C CNMRGS (CNMREGIST)

RTMCMD_S X'30F0F7F0' RTMCMD_O X'30F0F7F2' R_BRIDGE X'30F0F5F9' SPCS X'23F0F1F5' No character equivalent X'23F0F0F1' No character equivalent X'30F0F7F3' v A 1– to 8–character installation-defined name (padded with blanks). Use the EBCDIC characters 0-9 and A-Z (capitals only). The name STATUS is reserved for the NetView status focal point and is not allowed on a CNMRGS invocation. rgcmd Is an 8-byte character field that specifies the command procedure to be started when unsolicited or asynchronous solicited data is routed to the application. The NetView program verifies that the task has the authority to issue the command specified. This field is required for REGSMAPPL and REGOMSERVD. rgfocpt Is an 8-byte character field that specifies whether the MS application is a focal point application: NO The MS application is not a focal point application. NO is the default for the PL/I macro format. YES The MS application is a focal point application.

If you do not specify the FOCALPOINT keyword when using the PL/I macro format for REGMSAPPL, the default value is used. Otherwise, this field is required for REGMSAPPL. rgfpcat Is an 8-byte character field that specifies the name of an application registered as a focal point application. This is the focal point category from which you want to receive information.

Note: NetView supplies three focal point applications, ALERT (X'23F0F3F1'), OPS_MGMT (X'23F0F1F7') and SPCS (X'23F0F1F5'). For REGOMSERVD, you can specify only OPS_MGMT for rgfpcat. For more information about the focal points, refer to the IBM Tivoli NetView for z/OS Automation Guide. rgnotify Is an 8-byte character field that specifies whether the MS or operations management served application receives session outage notification for LUs in contact with the MS transport. ALL Indicates that the application receives an MDS-MU containing an SNA condition report with sense data every time the last SNASVCMG session has been lost. This notification is received even if the session outage is not related to an error.

Chapter 11. Service reference 243 CNMRGS (CNMREGIST)

ERROR Indicates that the application receives an MDS-MU containing an SNA condition report with sense data every time the last SNASVCMG session has been lost because of a session failure. NONE Indicates that the application does not receive session outage notification. NONE is the default for the PL/I macro format. If you do not specify the NOTIFY keyword when using the PL/I macro format, the default value is used. Otherwise, this field is required. rgpri Is an 8-byte character field that specifies the MQS priority for incoming requests. The MQS priority is used when the MS transport uses the MQS for processing any unsolicited MDS-MUs. HIGH Processing begins after any NORMAL requests currently in progress completes, but before queued NORMAL or LOW requests. LOW Processing is preempted by HIGH and NORMAL priority requests. This is the default. NORMAL Processing preempts a queue of LOW priority requests. TEST CNMRGS queues the request based on the command priority of the receiving task. The command priority can be set using the OVERRIDE or DEFAULT commands. Refer to the NetView online help. rgrepl Is an 8-byte character field that specifies whether this registration is to supersede the previous registration for this application. NO Specifies that this registration does not replace the current registration for this application. YES Specifies that this registration replaces the current registration for this application. YES is the default for the PL/I macro format.

If you do not specify the REPLACE keyword when using the PL/I macro format for REGMSAPPL or REGOMSERVD, the default value is used. Otherwise, this field is required for REGMSAPPL and REGOMSERVD. rgtype Is a 12-byte character field that specifies the type of request, as follows: DEREGMSAPPL Deregisters an MS application from the NetView MS transport. DEREGOMSERVD Deregisters an operations management served application from REGMSAPPL Registers an MS application to the NetView MS transport. REGOMSERVD Registers a second-level application to operations management.

Usage Notes: 1. You can register an application as both an MS application and an operations management served application.

244 Programming: PL/I and C CNMRGS (CNMREGIST)

2. When you specify that an MS application is a focal point, the focal point category name is the application name specified in rgappl. 3. Any registered application that was once a focal point application continues to receive focal point data from any application that did not attempt to send data while it was deregistered. To recognize that an application is no longer a focal point, the sending application must attempt to send data to a focal point application that has been deregistered. 4. NetView determines the task where an application receives an MDS-MU as follows: v For an MDS reply, the receiving task is the task under which the requesting application is running. v For an MDS request, the receiving task is the task from which CNMRGS is started for the receiving application. v For an MDS error message: – If the AUOWC matches an active AUOWC in the active transaction list: - For an outgoing request, the receiving task is the task under which the requesting application is running. - For an incoming request, the receiving task is the task under which the receiving application is running. – If the AUOWC does not match an active AUOWC, the receiving task is the task from which CNMRGS is started for the receiving application. 5. You can change the task under which CNMRGS was started by reregistering the application from the desired task and specifying YES for rgrepl.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Successful registration/deregistration. CNM_NOT_FOUND 20 Deregistration unsuccessful. rgappl not registered. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro. CNM_NOT_IN_ASYNC 44 Deregistration unsuccessful. Issued from an exit. CNM_DUPL_NAME 104 Registration unsuccessful. rgappl already registered. CNM_BUSY 472 Registration/deregistration unsuccessful. Queues are in use. CNM_BAD_APPL_NAME 476 Registration/deregistration unsuccessful. rgappl syntax incorrect. CNM_APPL_NAME_RSTD 480 Registration/deregistration unsuccessful. rgappl restricted. CNM_BAD_FPCAT_NAME 484 Registration/deregistration unsuccessful. rgfpcat syntax incorrect. CNM_BAD_FPCAT_CHOICE 488 Registration unsuccessful. rgfpcat has an incompatible value. CNM_BAD_REG_TYPE 492 Incorrect rgtype. CNM_BAD_FOCALPT_VALUE 496 Incorrect rgfocpt. CNM_CANT_BE_FOCALPT 500 Registration unsuccessful. rgfocpt has an incompatible value.

Chapter 11. Service reference 245 CNMRGS (CNMREGIST)

Return Code Name Value Description CNM_BAD_REPLACE_VALUE 504 Incorrect rgrepl. CNM_BAD_PRI_VALUE 512 Incorrect rgpri value specified. Value must be blank, LOW, NORMAL, HIGH, or TEST. CNM_BAD_NOTIFY 592 Incorrect rgnotify value specified. CNM_BAD_CES + X 9000 + X Nonzero return code, X, from DSICES macro using rgcmd.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMSCAN (CNMSSCAN): Parse or Convert Character String–PL/I Only You can use the CNMSCAN service routine to extract data from an input string and assign the extracted data to one or more receiving variables. The input string is scanned from left to right and is interpreted according to the specifications defined by the format string. Each receiving variable must have the same data type as its corresponding type specifier in the format string. You can specify up to 10 receiving variables in the argument list. The number of fields successfully parsed and converted is returned to you in panumfld.

When the first format specification is found, the value of the first input field is converted according to the first format specification and stored in the first receiving variable in the argument list. When the second format specification is found, the value of the second input field is converted according to the second format specification and stored in the second receiving variable in the argument list. This process continues until all of the format specifications in the format string are processed.

The CNMSCAN routine syntax follows:

PL/I CALL FORMAT: CALL CNMSCAN(hlbptr,pastring,pattern,panumfld,pafld1,...,pafld10)

PL/I MACRO FORMAT: CNMSSCAN DATA(pastring) FORMAT(pattern) COUNT(panumfld) P1(pafld1)...P10(pafld10)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. pafld1,.....,pafld10 Is a list of receiving variables. The last variable named in this list receives the value of the last input field parsed and converted according to the last specification in the format string. Declare each of the variables named in this list to have the same data type as its corresponding type specifier in the format string. You can specify up to 10 variables to receive parsed and converted data. panumfld Is a 4-byte integer field containing the number of fields successfully parsed and converted. This field is returned to you.

246 Programming: PL/I and C CNMSCAN (CNMSSCAN) pastring Is a varying length character field containing the input string to be parsed and converted. pattern Is a varying length character field containing the format specifications. The format string (pattern) determines how the data elements in the input string (pastring) are parsed and converted.

Usage Notes: 1. The format string consists of a series of format specifications that are defined as follows: v The character %, which designates the beginning of each format specification. (Required for each format specification.) v The character *, which indicates that the data in the corresponding input field is skipped. No assignment is made to a receiving variable. (Optional) v A numerical value that defines a maximum field width to scan in the input string. (Optional) v The character h (halfword) or l (long or fullword), which indicates the size of the argument that the value of the parsed or converted input data is assigned. (Optional) v Any number of white-space characters, which can be interspersed within or between format specifications for readability. However, do not insert blanks between braces ({}). (Optional) v The type specifier for the parsed or converted input data to be stored in the receiving variable. (Required) 2. The type specifier directs the conversion of the input field. CNMSCAN places the result in the receiving variable, unless you specify assignment suppression with an *. An input field is a string of characters other than spaces, unless the type specifier is a c or { }. The input field extends to the next character that does not meet the criteria of the type specifier, or until the width of the field, if specified, is reached. 3. The type specifier determines the interpretation of the next input field. If the input field does not meet this expectation, CNMSCAN returns to its caller. Valid specifiers are: c Expect any character. Space characters that are ordinarily skipped are read. Specify a field width to parse and convert more than one character. For example, %3c retrieves the next 3 characters of the input string. To skip over spaces before obtaining a character, use %1s. See the description that follows on the type specifier s.

Note: The receiving variable to contain the character string result must be declared as a fixed-length character string. d Expect a decimal value. Input is an optionally signed sequence of decimal digits. Any spaces in the input string preceding the decimal digits are skipped. The decimal digits are delimited by the next non-decimal character in the input string. n A data element is not parsed and converted from the input string. The value stored is the number of characters successfully read (including blanks) from the input string up to that point in the call to CNMSCAN.

Note: If the end of the input string occurs before the %n is reached, the value stored is 0.

Chapter 11. Service reference 247 CNMSCAN (CNMSSCAN)

s Expect a character string. Any spaces in the input string preceding the character string are skipped. The character string is delimited by a space. If you do not specify a field width, the field width defaults to the length of the string.

Note: The receiving variable to contain the character string result must be declared as a varying length character string. u Expect an unsigned decimal value. Any spaces in the input string preceding the decimal digits are skipped. The decimal digits are delimited by the next nondecimal character in the input string. x Expect a hexadecimal value. Input is an optionally signed sequence of hexadecimal digits. Any spaces in the input string preceding the hexadecimal digits are skipped. The hexadecimal digits are delimited by the next non-hexadecimal character in the input string. {} Expect a string that is not delimited by spaces. The character string is set within the braces. The corresponding input field is read to the first character that does not appear between braces ({}). If the first character is ¬ (or ‘5F’x), the effect is reversed. The input field is read to the first character that appears between braces ({}). Do not insert blanks between braces ({}) unless this is the desired effect. {¬} Parses until the end of the string. {¬a} Parses until the character a is found. {a} Parses until any character other than an a is found. {} Parses until any character is found.

Note: The receiving variable to contain the character string result must be declared as a varying length character string. 4. If your format string specifies fewer data elements to be parsed and converted than your input string contains, the remaining data elements in the input string are ignored. 5. CNMSCAN returns when it encounters a format specification it does not expect or when it reaches the end of the input string. 6. If you invoke CNMSCAN using the PL/I call format and all 10 paflds are not specified, a warning message is issued at compile time. 7. You can use CNMSCAN only in an HLL command processor or installation exit routine written in PL/I. 8. The PARSEL2R command provides a function similar to CNMSCAN. However, because of its conversion capabilities, CNMSCAN is more suitable to HLL command processors.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_BAD_ADDR 160 The storage pointed to by panumfld or pafld1,...,pafld10 is not addressable.

248 Programming: PL/I and C CNMSCOP (CNMSCOPECK)

CNMSCOP (CNMSCOPECK): Command, Keyword, and Value Authorization Checking The CNMSCOP service routine determines whether the user is authorized to issue a specific command, keyword, and value combination from a particular operator ID. The security check is based on the authority of the operator ID of the task invoking CNMSCOP. The type of authorization checking that is performed is determined by the setting of the CMDAUTH keyword on the REFRESH command or by the setting of the SECOPTS.CMDAUTH statement in the CNMSTYLE member. Only NetView authorization checking is performed. No attempt is made to determine if a resource is in the span of control of the task (operator).

The CNMSCOP routine syntax follows:

PL/I CALL FORMAT: CALL CNMSCOP(hlbptr,sccmd,sckwd,scvalue)

PL/I MACRO FORMAT: CNMSCOPECK VERB(sccmd) KEYWORD(sckwd) VALUE(scvalue)

C INVOCATION: void Cnmscop(char *sccmd, char *sckwd, char *scvalue)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. sccmd Is an 8-byte character field that specifies the verb of the command to be checked for authorization. Blanks or (*) imply that the command verb that started the HLL command processor is used. This field is required. sckwd Is an 8-byte character field that specifies a keyword of the command to be checked for authorization. Blanks or (*) imply that no specific keyword is checked. scvalue Is an 8-byte character field that specifies a value of sckwd to be checked for authorization. Blanks or (*) imply that no specific keyword value is to be checked.

Usage Notes: 1. Authorization to access commands, keywords, and keyword values is defined by the setting of the CMDAUTH keyword on the REFRESH command or by the setting of the SECOPTS.CMDAUTH statement in the CNMSTYLE member. For more information, refer to IBM Tivoli NetView for z/OS Security Reference. 2. CNMSCOP does not check the validity of a command. Use it only to verify whether an operator has authorization to issue a particular command.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro.

Chapter 11. Service reference 249 CNMSCOP (CNMSCOPECK)

Return Code Name Value Description CNM_COMMAND_NA 132 sccmd not authorized. CNM_KEYWORD_NA 136 sckwd not authorized. CNM_VALUE_NA 140 scvalue not authorized. CNM_BAD_COMMAND 144 Incorrect syntax of sccmd or sccmd was not found. Check for length greater than (>) 8 or incorrect characters in sccmd. sccmd might be incorrectly defined. See usage notes if CNMSCOP was started from an HLL installation exit routine. CNM_BAD_KEYWORD 148 VALUE (scvalue) was specified without a keyword (sckwd). sckwd must be specified when scvalue is specified. CNM_SAF_FAILURE 624 An unexpected return code was received from SAF. CNM_KWRD_VAL_NA 628 The keyword and value combination specified is not authorized. This return code can only be issued when a command authorization table or an SAF product is being used for command authorization. CNM_BAD_SEC_ENVIR 632 Authorization to issue this command, keyword, or keyword and value combination is not granted because the security environment for the operator cannot be established. Message BNH239E is issued when this condition is first encountered to provide the security product return code information. Message BNH273I is issued when the condition has been corrected. CNM_TBL_FAILURE 636 Authorization to issue this command, keyword, or keyword and value combination is not granted because an unexpected return code was received from the command authorization table. Message BNH199E is issued indicating the command identifier and the operator ID being checked. CNM_NO_SEC_INFO 640 Authorization to issue this command, keyword, or keyword and value combination is not granted because the NetView internal security information containing the source ID of the command cannot be found. Message BNH277E is issued identifying the command, keyword or value being checked. CNM_NO_OP_INFO 644 Authorization to issue this command, keyword, or keyword and value combination is not granted because the source ID is blank in the NetView internal security information. Message BNH277E is issued identifying the command, keyword or value being checked. CNM_BAD_CES + X 9000 + X Nonzero return code, X, from DSICES macro. CNM_BAD_KVS + X 11000 + X Nonzero return code, X, from DSIKVS macro.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information.

250 Programming: PL/I and C CNMSMSG (CNMSENDMSG)

CNMSMSG (CNMSENDMSG): Send Message or Command Use the CNMSMSG service routine to send a message or command to specific destinations in your network.

The CNMSMSG routine syntax follows:

PL/I CALL FORMAT: CALL CNMSMSG(hlbptr,smtext,smmsgtyp,smdestyp,smdestid)

PL/I MACRO FORMAT: CNMSENDMSG DATA(smtext) MSGTYPE(smmsgtyp) DESTTYPE(smdestyp) DEST(smdestid)

C INVOCATION: void Cnmsmsg(void *smtext, char *smmsgtyp, char *smdestyp, char *smdestid)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. smdestid Is an 8-byte character field that specifies the destination ID. This is a required operand when smdestyp is EXTLOG, SEQLOG, TASK, or OPCLASS. When smdestyp is EXTLOG, SEQLOG, or TASK, smdestid is the name of the destination task. You can use an asterisk (*) to imply “self” when smdestyp = TASK. Specifying smdestid = * is the same as issuing CNMSMSG with smdestyp = OPER and smdestid = null. When smdestyp is OPCLASS, smdestid is the group ID of a particular group of operators defined by the ASSIGN command. Refer to the ASSIGN command in the NetView online help for more information.

Note: PPT is accepted as a synonym for the primary POI task (xxxxxPPT) where xxxxx is the domain ID in the local NetView program. smdestyp Is an 8-byte character field that specifies the destination type. This is a required operand. Possible values follow: AUTHRCV Authorized receiver EXTLOG External system management facility (SMF) log NETVLOG NetView log OPCLASS All operators in group OPER Operator task invoking this service routine SEQLOG Sequential log SYSOP System console

Chapter 11. Service reference 251 CNMSMSG (CNMSENDMSG)

TASK Another task smmsgtyp Is an 8-byte character field that specifies the message type. This is a required operand. The possible values follow: COMMAND Is the command to be run. (The command is asynchronously scheduled to be run.) DATA Is the nonprintable data in response to REQUEST. NetView places a process ID in the origin block (ORIGBLCK). This ID must be included at the beginning of the returned data. This process ID is used to route data to the correct instance of an HLL command processor or installation exit routine if there are multiple activations of the same HLL command processor or installation exit routine. The data returned from CNMSMSG with smmsgtyp=DATA can be read by CNMGETD from the data queue (DATAQ). MSG Single line message. ORIG_LINE_TYPE=’ ’ MSG_C Control line message.ORIG_LINE_TYPE=’C’ MSG_D Data line message.ORIG_LINE_TYPE=’D’ MSG_E End of multiline message. ORIG_LINE_TYPE=’E’ MSG_F MSG_D and MSG_E combined. ORIG_LINE_TYPE=’F’ MSG_L Label line message. ORIG_LINE_TYPE=’L’ REQUEST Is the request for data. REQUEST is similar to COMMAND except the command to run is the name of the HLL command processor that is to return data through CNMSMSG with smmsgtyp=DATA. smtext Is a varying length character field containing the message text. This is a required operand. The values are explained as follows: v If smmsgtyp is MSG, MSG_C, MSG_L, MSG_D, MSG_E, or MSG_F, smtext is the text of the message. v If smmsgtyp is COMMAND, smtext is either a command procedure name or a NetView command. v If smmsgtyp is REQUEST, the first token must be the name of the HLL command processor that sends a reply to the request. NetView concatenates the process ID to the end of smtext and the request for data is sent. As a result, if smtext contains input for the target task, the target task must take into account that the last 8 bytes of CMDBUF are always the process ID. v If smmsgtyp is DATA, the process ID must be concatenated with the data. Specify smtext as follows: smtext = ORIGIN->ORIG_PROCESS||’text’

Table 17 on page 253 shows message and destination type combinations that are not valid.

252 Programming: PL/I and C CNMSMSG (CNMSENDMSG)

Table 17. Incorrect Message and Destination Type Combinations OPER TASK SYSOP NETVLOG EXTLOG SEQLOG AUTHRCV OPCLASS MSG MSG_C x x x MSG_L x x x MSG_D x x x MSG_E x x x MSG_F x x x COMMAND x x x x x x x REQUEST x x x x x x x DATA x x x x x x x

Usage Notes: 1. The amount of data that can be sent by CNMSMSG varies based on the value of smmsgtyp. The following limits are enforced for the smmsgtyp values. MSG 32000 bytes MSG_C 32000 bytes MSG_L 32000 bytes MSG_D 32000 bytes MSG_E 32000 bytes MSG_F 32000 bytes COMMAND 31998 bytes REQUEST 31989 bytes DATA 32500 bytes 2. Multiline messages are treated as single line messages when CNMSMSG is started from DSIEX02A. 3. CNMSMSG generates a return code of CNM_BAD_INVOCATION when started from DSIEX04 or DSIEX09. You can invoke CNMSMSG from DSIEX02A only when smdestyp is TASK and smmsgtyp is one of the message options. COMMAND and REQUEST are not permitted as smmsgtyp values. When invoking CNMSMSG from DSIEX02A. you can also send a command to another task, in a way similar to EXCMD, by specifying smmsgtyp=COMMAND, smdestyp=TASK, and the desired smtext and smdestid. 4. Messages sent to a console with smmsgtyp = MSG_C, MSG_D, MSG_E, MSG_F, or MSG_L are truncated if they are longer than the screen width of that console.

Chapter 11. Service reference 253 CNMSMSG (CNMSENDMSG)

5. You can display as many control (MSG_C) and label (MSG_L) lines on a console as desired. However, a maximum of six control or label lines are held on the screen if the data lines for that multiline message cause the screen to wrap. 6. Do not invoke CNMSMSG with smdestyp = OPER while holding a lock. The operator task can be running with autowrap off, and the HLL command processor or installation exit routine might hang waiting for the operator to clear the screen, thus holding the lock for an indefinite period. 7. When the SECOPTS.AUTHCHK statement in the CNMSTYLE member specifies SOURCEID, or the REFRESH command specifies SECOPTS=AUTHCHK, command authorization checking is performed against the original source of the command rather than against the environment in which the command runs. When CNMSMSG is used to queue a command, a SOURCEID is also queued. If the invoker is running in an installation exit, the SOURCEID is the name of the task (TVBOPID) under which the installation exit that started CNMSMSG is running. If CNMSMSG is started in a command processor, the SOURCEID is the ID of the task under which the command is issued or the existing SOURCEID at the time the command was queued. For more information about SOURCEID, refer to the IBM Tivoli NetView for z/OS Administration Reference.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_BAD_INVOCATION 4 Not started from an allowed installation exit. CNM_NO_STORAGE 24 Nonzero return code from DSIGET macro. CNM_BAD_LENGTH 88 smtext is too long. CNM_BAD_MSGTYP 116 Incorrect message type. CNM_BAD_DESTYPE 120 Incorrect destination type. CNM_TYP_CONFLICT 124 Conflict between message and destination type. CNM_LOG_INACTIVE 216 DSIWLS failure. Log was inactive. CNM_TASK_INACTIVE 220 DSIMQS failure. Task was inactive. CNM_BAD_MQS + X 1000 + X Bad return code, X, from DSIMQS. CNM_BAD_WLS + X 6000 + X Bad return code, X, from DSIWLS. CNM_BAD_PSS + X 7000 + X Bad return code, X, from DSIPSS. CNM_BAD_WTO + X 8000 + X Bad return code, X, from DSIWCS.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMSMU (CNMSENDMU): Send Message Unit The CNMSMU service routine allows MS applications and operations management served applications in NetView to send data to a specified target. You can invoke CNMSMU only in applications registered through CNMRGS or the REGISTER command.

The data is sent in the form of an MDS-MU. The invocation can supply: v A completely built MDS-MU v An MDS-MU that is missing one or more of the following: – A unit of work correlator

254 Programming: PL/I and C CNMSMU (CNMSENDMU)

– An origin NETID – An origin LUNAME v Data and sufficient other fields for the service routine to build an MDS-MU header.

Note: Refer to the SNA library for more information about MDS-MUs.

The CNMSMU service routine builds the necessary NetView MQS buffer with the specified data and queues it for the NetView MS transport.

The CNMSMU routine syntax follows:

PL/I CALL FORMAT: CALL CNMSMU(hlbptr,sudtype,sudata,susupcor,sucorrar,sutimout,susynch, surplcmd,suoappl,sudstnet,sudstlu,sudstapl,sumutype,supri)

PL/I MACRO FORMAT: CNMSENDMU DATATYPE(sudtype) DATA(sudata) SUPPCORREL(susupcor) CORRELAREA(sucorrar) TIMEOUT(sutimout) SYNCH(susynch) REPLYCMD(surplcmd) ORIGAPPL(suoappl) DESTNET(sudstnet) DESTLU(sudstlu) DESTAPPL(sudstapl) MUTYPE(sumutype) PRI(supri)

C INVOCATION: void Cnmsmu(char *sudtype, void *sudata, void *susupcor, void *sucorrar, int sutimout, char *susynch, char *surplcmd, char *suoappl, char *sudstnet, char *sudstlu, char *sudstapl, int sumutype, char *supri)

Where: hlbptr Is a 4-byte character field containing the address of the HLB control block. sucorrar Is a 53-byte area in which a new unit of work correlator (X'1549') GDS variable is created and returned by the CNMSMU service routine. If you specify sucorrar for MDSMU, NetView creates the unit of work correlator in this area and inserts it into the specified MDS-MU while copying it into the buffer for the MS transport. If you omit sucorrar, the MDS-MU must be complete and ready to be transmitted as supplied. For a NONMDSMU, specify either sucorrar or susupcor. If you specify sucorrar, CNMSMU creates the UOWC GDS variable in this area and uses it in building the MDS header. sudata Is a varying length character field containing the data being sent. For either MDSMU or NONMDSMU, the first 2 bytes must contain the entire length of the data and the next 2 bytes must contain the key. sudstapl Is an 8-byte character field that specifies the destination application name. The application name can be one of the following:

Chapter 11. Service reference 255 CNMSMU (CNMSENDMU)

v An architecturally defined 4-byte value (padded with blanks to 8 bytes) for MS application programs. v A 1–8 character installation-defined name (padded with blanks). Use the EBCDIC characters 0–9 and A–Z (capitals only). v A 1–8 character NetView-reserved name (padded with blanks) that represents an architecturally defined 4-byte value. NetView-reserved names and the corresponding values follow: ALERT X'23F0F3F1' EP_ALERT X'23F0F3F0' EP_OPS X'23F0F1F6' MS_CAPS X'23F0F1F1' OPS_MGMT X'23F0F1F7' This field is required for NONMDSMU. sudstlu Is an 8-byte character field that specifies the LU name or VTAM CP name of the destination LU or VTAM CP. If the destination LU is not specified, then the default is the CP. Specify the 1–8 character LU or VTAM CP name (padded with blanks to 8 characters) beginning with an EBCDIC character 0–9 and A–Z (capitals only), @, #, or $, and followed by EBCDIC characters 0–9 and A–Z (capitals only). This is a required field for NONMDSMUs.

Note: For sends within the same NetView, the send services always fills in the NetView LU name as the origin LU. sudstnet Is an 8-byte character field that specifies the ID of the network of the destination LU or VTAM CP. Specify the 1–8 character NETID (padded with blanks to 8 characters) beginning with an EBCDIC character 0—9 and A—Z (capitals only), @, #, or $, and followed by EBCDIC characters 0—9 and A—Z (capitals only). The value of this field defaults to the network name that VTAM determines based on the LU name or VTAM CP name of the remote node (specified with the hsdstlu field) if: v You specify blanks for this field for the PL/I call format. v You do not specify the DESTNET keyword when using the PL/I macro format. v You specify blanks for this field for the C invocation format. sudtype Is an 8-byte character field indicating whether the data item specified in the sudata keyword is an MDS-MU or a non-MDS-MU. MDSMU Indicates that the sudata is an MDS-MU. MDSMU is the default for the PL/I macro format. NONMDSMU Indicates that the sudata is not a complete MDS-MU because it does

256 Programming: PL/I and C CNMSMU (CNMSENDMU)

not contain an MDS-MU header. The CNMSMU service routine envelopes this data in an MDS-MU before sending it. If you do not specify the DATATYPE keyword in the PL/I macro format, the default value is used. sumutype Is a 4-byte integer field that specifies the index number that identifies the type of MDS-MU to build. The type identifies whether the MDS-MU is a request, a reply, or an error message, and whether additional messages are expected. Types defined as constants are as follows: 1 REQUEST_WITH_REPLY 2 REQUEST_WITHOUT_REPLY 3 REPLY_ONLY 4 REPLY_NOTLAST 5 REPLY_LAST 6 ERROR_MESSAGE This field is required for NONMDSMU. suoappl Is an 8-byte character field that specifies the origin application name. The application name can be one of the following values: v An architecturally defined 4-byte value (padded with blanks to 8 bytes) for MS application programs. v A 1–8 character installation-defined name (padded with blanks). Use the EBCDIC characters 0-9 and A-Z (capitals only). v A 1–8 character NetView-reserved name (padded with blanks) that represents an architecturally defined 4-byte value. NetView-reserved names and the corresponding values follow: EP_OPS X'23F0F1F6' OPS_MGMT X'23F0F1F7' Only use OPS_MGMT as suoappl if operations management on the origin NetView program is defined as a focal point. This field is required for NONMDSMU. supri Is an 8-byte character field that specifies the MQS priority for incoming solicited requests or any MDS error messages resulting from any outgoing MDS-MUs. The MQS priority is used when the MS transport uses the MQS for processing any solicited MDS-MUs or any MDS error messages. HIGH Processing begins after any NORMAL requests currently in progress completes, but before queued NORMAL or LOW requests. LOW Processing is preempted by HIGH and NORMAL priority requests. This is the default for all requests other than synchronous requests. NORMAL Processing preempts a queue of LOW priority requests. This is the default for synchronous requests.

Chapter 11. Service reference 257 CNMSMU (CNMSENDMU)

TEST CNMSMU queues the request based on the command priority of the receiving task. The command priority can be set using the OVERRIDE or DEFAULT commands. Refer to the NetView online help. surplcmd Is an 8-byte character field containing the name of the NetView command to be driven with the reply. The surplcmd field is used only in an MS application that is sending a REQUEST_WITH_REPLY with the reply being received asynchronously. Otherwise, it is ignored. This is an optional field. The default is the registered command for the invoking application. susupcor Is a varying length character field containing a complete unit of the unit of work correlator (X'1549') GDS variable. Refer to the SNA library for more information about defining the correlator. The susupcor field is not valid for MDSMU. For NONMDSMU, specify either suspcor or sucorrar. If you specify susupcor, the supplied value is used to build the MDS header. No validity checking is done for a correlator supplied by the invoker. susynch Is an 8-byte character field that specifies whether the MS application is to receive the reply synchronously. NO Indicates that the reply is received asynchronously. NO is the default for the PL/I macro format. NO_BUF Do not suspend the application but buffer replies until the one last is received. This value is equivalent to the NO value. NO_UNBUF Do not suspend the application and forward replies immediately. YES Indicates that the reply is received synchronously. YES_BUF Suspend the application and buffer its replies. This value is equivalent to the YES value. If you do not specify the SYNCH keyword when using the PL/I macro format for REQUEST_WITH_REPLY, the default value is used. Otherwise, this field is required for REQUEST_WITH_REPLY. sutimout Is a 4-byte integer field that specifies the number of seconds to wait for a reply to an outstanding REQUEST_WITH_REPLY. For a REQUEST_WITH_REPLY that generates multiple replies, the timeout value applies only to the last reply. For requests that generate multiple replies, the timeout value applies only to the last reply. NetView initializes the default and maximum timeout values for the LU 6.2 transport send services. The initial default and maximum timeout values are 120 seconds and 86400 seconds, respectively. You can change these values with the DEFAULTS command. The valid values for sutimout are:

258 Programming: PL/I and C CNMSMU (CNMSENDMU)

1 ... X Where X is the maximum timeout value. 0 Indicates the default timeout value. –1 Indicates the maximum timeout value. If you do not specify the TIMEOUT keyword when using the PL/I macro format for REQUEST_WITH_REPLY, the default timeout value is used. Otherwise, this field is required for REQUEST_WITH_REPLY.

Usage Notes: 1. For a synchronous REQUEST_WITH_REPLY, control is returned to the invoking program after the last reply or an error message is received and placed on the MDSMUQ data queue. Otherwise, control is returned after CNMSMU successfully queues the request to the MS transport. 2. When the invoking program is suspended because of a synchronous REQUEST_WITH_REPLY, the NetView task where the program is running is not suspended. The task still receives and processes messages and commands. 3. For a synchronous REQUEST_WITH_REPLY from a data services task (DST), a DSRB is marked in-use and the DSRB is not available for other use until the suspended program is resumed. 4. For MDSMU, all fields within the MDS-MU header must be correct except for origin NETID and LUNAME. NETID and LUNAME must be left out, not blank or null, for the service routine to determine and set these fields. If the correlator is not contained in the data, specify sucorrar. 5. For REPLY_ONLY, REPLY_NOTLAST, REPLY_LAST, and ERROR_MESSAGE, specify susupcor to return the correlator sent with the request. 6. The MS transport implements a timeout value for the application receiving the data. If the invocation of CNMSMU specifies a timeout value greater than the timeout value set by the transport at the receiving node, the sending application might time out in less than the specified interval. 7. When VTAM is active, you can use CNMSMU to send data to another application in the same domain. 8. If sudstnet is not the NETID determined by VTAM for the LU specified in sudstlu, the send fails. 9. An MS application or operations management served application cannot send data to itself within the same NetView program. 10. If you specify both susupcor and sucorrar, susupcor is used. 11. Return code 24 or 28 from DSIPUSH indicates that DSIOLGFP is not defined correctly in DSICMD. 12. If CNM_BAD_CES is returned: v Make sure DSI6SNDP is defined correctly in DSICMD. v If you specify hrrepcmd, make sure it is defined correctly in DSICMD. v If you specify a synchronous REQUEST_WITH_REPLY, make sure DSIOSRCP is defined correctly in DSICMD. v If the sending application is an operations management served application, make sure DSIOARCP is defined properly in DSICMD. 13. Refer to the IBM Tivoli NetView for z/OS Administration Reference for the correct definitions of the command processors supplied by the NetView product. 14. For MDSMU, if you omit the NETID subfield of the destination subvector from the MDS-MU header, VTAM determines the network name used, based on the LU name in the NAU name subfield of the destination subvector.

Chapter 11. Service reference 259 CNMSMU (CNMSENDMU)

15. If you do not specify the destination NETID, and the destination LU name exists in more than one network, VTAM determines the destination NETID based on the active configuration.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Requested function was performed. CNM_BAD_INVOCATION 4 Task is terminating, and a request-with-reply is being sent. CNM_NO_STORAGE 24 No storage is available. CNM_NOT_IN_ASYNC 44 Send MU service is started in an asynchronous exit. CNM_BAD_TIMEOUT 56 Time-out value is not valid. CNM_BAD_LENGTH 88 MDS-MU length is not valid. CNM_TASK_INACTIVE 220 DSI6DST task is inactive. CNM_BAD_DATA_TYPE 400 Data type is not valid. CNM_BAD_DATA 404 DATA missing or is not valid. CNM_SAME_APPL 408 Application cannot send data to the same application within the same NetView program. CNM_SYNCH_NOT_COMP 412 SYNCH(YES) is not allowed under a NetView installation exit or a PPT. CNM_OAPPL_NOT_REG 416 Application is not registered. CNM_BAD_SAPPL 420 Operations management served application is not registered. CNM_BAD_UOW 424 UOW missing or is not valid. CNM_BAD_RTI 428 R&TI missing or is not valid. CNM_BAD_OAN 432 OAN missing or is not valid. CNM_BAD_DAN 436 DAN is not valid. CNM_BAD_OAPPL 440 Origin application name is not valid. CNM_BAD_DNETID 444 Destination network ID missing or is not valid. CNM_BAD_DLU 448 Destination LU name missing or is not valid. CNM_BAD_DAPPL 452 Destination application name missing or is not valid. CNM_BAD_OII 456 OII in R&TI does not match TVBOPID. CNM_BAD_REPLY 460 Reply is not valid. CNM_BAD_MUTYPE 464 Bad MUTYPE given. CNM_BAD_SYNCH 468 Bad SYNCH option. CNM_BUSY 472 Too many concurrent requests. CNM_SYNCH_CMD_MISSING 508 SYNCH(YES) is specified but DSIOSRCP is not defined or is not defined correctly in DSICMD.

260 Programming: PL/I and C CNMSMU (CNMSENDMU)

Return Code Name Value Description CNM_SAME_OMAPPL 548 Operations management served application cannot send data to the same operations management served application within the same NetView. CNM_REQ_CANCELED 552 Synchronous request canceled by user. CNM_TASK_NO_AUTH 556 Task does not have authorization to run the registered command associated with the origin application or OAN. CNM_BAD_OM_MDSEM 560 Operations management served application is not allowed to send MDS error message. The routing report is sent instead. CNM_SNACR_MISSING 588 SNACR (X'1532') is missing from MDS error message. CNM_NETID_UNINIT 596 NETID is not initialized. CNM_BAD_MQS + X 1000 + X X is the return code from DSIMQS. CNM_BAD_PUSH + X 4000 + X X is the return code from DSIPUSH. CNM_BAD_CES + Y 9000 + Y Reply command is not valid. Y is the return code from DSICES.

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMSUBS (CNMSUBSYM): Substitute System Symbolics You can use the CNMSUBS service routine to substitute any MVS or user-defined system symbolics found in the source string for their system values and place the resulting string in the target string. The &DOMAIN symbolic supplied by the NetView product is also included in the substitution process.

The CNMSUBS routine syntax follows:

PL/I CALL FORMAT: CALL CNMSUBS(hlbptr,sssource,sstarget,sslen,sstype)

PL/I MACRO FORMAT: CNMSUBSYM SOURCE(sssource) TARGET(sstarget) LENG(sslen) COPYTYPE(sstype)

C INVOCATION: void Cnmsubs(void *sssource, void *sstarget, int *sslen, char *sstype)

Where: hlbptr Is a 4-byte pointer field containing the address of the HLB control block. sslen Is a 4-byte integer field containing the length of both sssource and sstarget which must be the same length. If the value specified by sslen is less than the length of the data to be returned, the truncated data is returned and a return code of CNM_DATA_TRUNC is generated. The length of the returned data is stored in HLBLENG(Hlbleng).

Chapter 11. Service reference 261 CNMSUBS (CNMSUBSYM)

If the value specified by sslen is equal to or greater than the length of the data to be returned and HLBRC(Hlbrc) = CNM_GOOD, the length of the returned data is stored in HLBLENG(Hlbleng). If the value specified is greater than the length of the receiving data area (sstarget), a storage overlay can occur. sssource Is a 4-byte pointer field containing the address of the source character string which has MVS system symbolics embedded in it or a single MVS system symbolic. Substitution is always performed on the &DOMAIN symbolic, unless substitution was disabled when NetView was started. For MVS and user-defined system symbolics, substitution is not performed if substitution was disabled when NetView was started, or you have not defined an MVS system symbolic on your MVS system. sstarget Is a 4-byte pointer field containing the address of the target character string which contains the source string with the MVS system symbolic values substituted upon completion of this service. sstype Is an 8-byte character field specifying whether the source and target fields are fixed or varying fields. The following are the valid types: FIXTOFIX Both sssource and sstarget are fixed length fields. FIXTOVAR sssource is a fixed length field and sstarget is a varying length field. VARTOFIX sssource is a varying length field and sstarget is a fixed length field. VARTOVAR Both sssource and sstarget are varying length fields.

Usage Notes: 1. The source and target fields cannot overlap. 2. The length field of varying length fields is not set or altered by CNMSUBS. 3. When using CNMSUBS with C and sstype's of FIXTOFIX, FIXTOVAR, or VARTOFIX, pass CNMSUBS the address of a pointer to your fixed length field. You can do this by coding a variable as a pointer to a string, and then passing CNMSUBS the address of that pointer.

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_DATA_TRUNC 40 sslen was too small. sstarget data truncated. CNM_BAD_LENGTH 88 sslen less than (<) 0. CNM_BAD_ADDR 160 The storage pointed to by ssource or sstarget is not addressable, or the storage pointed to by sstarget is protected (not writable). CNM_BAD_SSTYPE 320 Incorrect sstype. CNM_BAD_ESTAE 15000 Nonzero return code from ESTAE macro.

262 Programming: PL/I and C CNMVARS (CNMVARPOOL)

Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information. CNMVARS (CNMVARPOOL): Set or Retrieve Variables A variable pool is a collection of named variables whose values can be set or retrieved by NetView command procedures, assembler command processors, and HLL installation exit routines. You can access the following types of variable pools from HLL command processors or HLL installation exit routines: v The HLL command processor or installation exit routine’s own pool v The variable pool of the calling command procedure if the current HLL command processor or installation exit routine was called from a command procedure v The task global pool shared by all command procedures and HLL installation exit routines running under a NetView task v The common global pool shared by all command procedures and HLL installation exit routines running in a NetView address space.

The CNMVARS routine syntax follows:

PL/I CALL FORMAT: CALL CNMVARS(hlbptr,cvfunc,cvdata,cvdatlen,cvname,cvpool)

PL/I MACRO FORMAT: CNMVARPOOL FUNC(cvfunc) NAME(cvname) POOL(cvpool) DATA(cvdata) LENG(cvdatlen)

C INVOCATION: void Cnmvars(char *cvfunc, void *cvdata, int cvdatlen, void *cvname, char *cvpool)

Where: cvdata Is a varying length character field containing the value of the named variable. This field is required for PUT and GET, but not used for DCL. cvdatlen Is a 4-byte integer field containing the length of cvdata. This is the maximum length of the area provided to receive the returned data. You provide cvdatlen. This field is required only for GET. If the value specified by cvdatlen is less than the length of the data to be returned, the truncated data is returned in cvdata and a return code of CNM_DATA_TRUNC is generated. The full length of the data that was truncated is stored in HLBLENG (Hlbleng). If the value specified by cvdatlen is equal to or greater than the length of the data to be returned, and HLBRC (Hlbrc) = CNM_GOOD, the length of the returned data is stored in HLBLENG (Hlbleng). If the value specified by cvdatlen is greater than the length of the receiving data buffer (cvdata), a storage overlay can occur. cvfunc Is an 8-byte character field that specifies the function to be performed. This field is required for all CNMVARS calls.

Chapter 11. Service reference 263 CNMVARS (CNMVARPOOL)

DCL Declares the local variable to belong to one of the global pools, or resets it to the local pool. (You cannot declare a variable that belongs to the caller’s pool.) GET Gets the variable value PUT Sets the variable value cvname Is a varying length character field that specifies the name of the variable. This field is required for all functions. Valid characters are A–Z, 0–9, @, #, $, +, ., !, ?, and underscore. The first character of cvname cannot be a number or a period. cvpool Is an 8-byte character field that specifies the variable pool. This field is required for all functions. CALLER The local pool of the calling command procedure or HLL installation exit routine (if one exists). CGLOBAL Common global LOCAL The local pool of the current HLL command processor or installation exit routine TGLOBAL Task global hlbptr Is a 4-byte pointer field containing the address of the HLB control block.

Usage Notes: 1. You can access all existing NetView command list language and REXX global variables (both task and common) using CNMVARS. In the NetView command list language, all variable names (local and global) are restricted to a length of 1–11 characters. In REXX, local variable names can be 1–250 characters, while global variables must be 1–31 characters. In HLL, all variable names (local and global) are restricted to a length of 1–31 characters. 2. If you are accessing REXX or HLL global variables from the NetView command list language, the REXX and HLL variable names must adhere to NetView command list language rules. The character set allowed for variable names in NetView command list language is also smaller than in REXX and HLL. The valid characters for REXX variable names are the same as HLL; see the operand cvname previously mentioned. 3. The C program using CNMVARS must be called by a command list language, REXX, or HLL command procedure to PUT to or GET from a CALLER pool. Otherwise, a return code of CNM_BAD_POOL is issued. 4. You do not have to initially put a value into the calling HLL command processor or installation exit routine’s LOCAL pool before issuing a PUT in the called HLL command processor or installation exit routine CALLER pool. When control is returned to the calling HLL command processor or installation exit routine, you can issue a GET for the same variable name in the LOCAL pool to retrieve the value set in the called HLL command processor or installation exit routine’s CALLER pool.

264 Programming: PL/I and C CNMVARS (CNMVARPOOL)

5. Any PUTs in an HLL command processor or installation exit routine’s CALLER pool change the value of the same variable name in the calling command procedure or HLL installation exit routine’s LOCAL pool. 6. You can get three different values (cvdata) in the same variable name (cvname) if you specify different pools (cvpool). For example: CNMVARS FUNC(’PUT’) NAME(x) POOL(’LOCAL’) DATA(’cvdata1’); CNMVARS FUNC(’PUT’) NAME(x) POOL(’CGLOBAL’) DATA(’cvdata2’); CNMVARS FUNC(’PUT’) NAME(x) POOL(’TGGLOBAL’) DATA(’cvdata3); 7. The calling HLL command processor or installation exit routine’s LOCAL pool is the same as the called HLL command processor or installation exit routine’s CALLER pool. 8. The DCL operand can be useful when an HLL command processor invokes VIEW. Ensure that the variables are properly declared to the corresponding common or task global pools. Otherwise, the variables used can be from the local pool and the full-screen panel is not automatically updated. 9. Declare task and common global variables to their respective pools before invoking VIEW from an HLL command processor. Otherwise, VIEW does not pick up the values. DCL is not necessary for local variables. 10. Example 1: Declaring Variables to the Task or Common Global Pool REXX or NetView command list language has declared variables to the task or common global pool and values have been assigned to these variables. These values need to be displayed on a full-screen panel from an HLL command processor or installation exit routine. Before invoking VIEW, code in the HLL command processor or installation exit routine: CNMVARPOOL FUNC(’DCL’) NAME(cvname) POOL(’CGLOBAL’)

or CNMVARPOOL FUNC(’DCL’) NAME(cvname) POOL(’TGLOBAL’) 11. Example 2: Changing the Value of a Variable REXX or NetView command list language has declared variables to the task or common global pool and values have been assigned to these variables. These values must be changed within an HLL command processor or installation exit routine and then displayed on a full-screen panel. Before invoking VIEW, code in the HLL command processor or installation exit routine: CNMVARPOOL FUNC(’PUT’) NAME(cvname) POOL(’CGLOBAL’) DATA(cvdata) CNMVARPOOL FUNC(’DCL’) NAME(cvname) POOL(’CGLOBAL’)

or CNMVARPOOL FUNC(’PUT’) NAME(cvname) POOL(’TGLOBAL’) DATA(cvdata) CNMVARPOOL FUNC(’DCL’) NAME(cvname) POOL(’TGLOBAL’)

Note: The DCL can precede the PUT. 12. Example 3: Setting Values for Task and Common Variables An HLL command processor or installation exit routine has set values for either task or common variables. Before invoking VIEW, code in the HLL command processor or installation exit routine: CNMVARPOOL FUNC(’DCL’) NAME(cvname) POOL(’CGLOBAL’)

or CNMVARPOOL FUNC(’DCL’) NAME(cvname) POOL(’TGLOBAL’)

Note: If only a DCL is done (with no PUT), the VIEW panel is blank for that variable.

Chapter 11. Service reference 265 CNMVARS (CNMVARPOOL)

13. Example 4: Declaring a Variable to the Local Pool You might need to declare (DCL) a variable back to the local pool. Assume you have the same variable name in both the local and common global pool. If you have just started VIEW, the variable is declared to the common global pool. If you want to change the value of the variable in the local pool, issue: CNMVARPOOL FUNC(’DCL’) NAME(cvname) POOL(’LOCAL’)

Return Codes:

Return Code Name Value Description CNM_GOOD 0 Everything is OK. CNM_NOT_FOUND 20 cvname not found or value of cvname is null. CNM_DATA_TRUNC 40 cvdatlen was too small. Data truncated. CNM_BAD_FUNC 52 Incorrect cvfunc. CNM_BAD_LENGTH 88 cvdatlen less than (<) 0 or cvdata greater than (>) 255. CNM_BAD_NAME 108 Incorrect cvname. CNM_BAD_POOL 156 Incorrect cvpool. CNM_BAD_ADDR 160 The storage pointed to by cvdata is not addressable. CNM_BAD_CDS + X 14000 + X Nonzero return code, X. See values for X below.

Values for X:

Value for X Description 4 Incorrect variable name. 8 Variable name already defined in dictionary. 12 Insufficient storage. 20 Value length limit was exceeded. 28 No command procedure related to current action. 32 Data was truncated.

266 Programming: PL/I and C Part 6. Appendixes

Table 18 describes the PL/I control blocks and include files needed to write command processors and installation exits in PL/I. The files are located in the SCNMMAC1 data set. Table 18. List of PL/I control blocks and include files Include File Description DSIPLI include file This file includes all of the external HLL control blocks and include files needed to run PL/I programs in the NetView environment. DSIPCONS control This file contains the definitions for constants that are helpful when block coding HLL modules in PL/I. DSIPHLB control This file contains a PL/I mapping of the NetView HLL control block block (HLB). The HLB is built during command processor initialization and exists for the lifetime of the command processor. DSIPORIG control This file defines the mapping of the origin block of the request that block caused the current procedure to run. DSIPHLLS control This file defines entry points for HLL service routines for PL/I. block DSIPCNM control This file defines the HLL return codes for PL/I. block DSIPPRM control This file defines the NetView Bridge parameter control block to block PL/I HLL service routines.

270 Programming: PL/I and C Appendix B. PL/I samples

This appendix contains a table of the PL/I samples that are shipped with the NetView program in the CNMSAMP data set. When a data set name is referred to in this appendix, two names are given, for example PTMPPLT (CNMS4200). The first name is the alias name, and the name in parentheses is in the NetView samples library. You can use either name to access the samples. CNMCMD has definitions for the alias names to allow those names to be entered as commands.

To enter the member names as commands do the following tasks: 1. Compile and link-edit the samples using the alias name. 2. Delete the asterisk (*) in column 1 of the appropriate CMDDEF statement in CNMCMD to run the alias name as a command. No entries are needed in CNMCMD for installation exits. 3. Recycle NetView for the CNMCMD changes to go into effect.

Note: 1. Refer to the prologues of the samples for information about how certain samples are related and special cases for installation exit routines. 2. Each alias name for PL/I begins with the letter P. 3. In PL/I the alias name is the same as the procedure name, which is limited to 7 characters.

This appendix also contains a description of each sample, and coded samples of an installation exit routine and two command processors.

PL/I samples table Table 19 lists the PL/I samples that are shipped with the NetView program. The table contains the function, the alias name, and the name of the member in NETVIEW.V6R2M0.CNMSAMP. Table 19. PL/I Samples Shipped with the NetView Program Sample Function PL/I Alias Sample CNMSAMP Template for commands and installation exit PTMPPLT CNMS4200 routines Sample DSIEX03 to set a global variable PEXIT3 CNMS4210 Uses CNMSMSG to send data PSNDDAT CNMS4211 Uses WAIT FOR DATA PWATDAT CNMS4212 Sample DSIEX02A changes a WTO to an MLWTO PEXIT2A CNMS4213 Uses CNMCNMI to forward RUs to a PU PCNMI CNMS4214 Uses CNMKIO for I/O to VSAM PKEYIO CNMS4215 HLL command using CNMSCOP for command PSCOPCK CNMS4216 authorization checking Display full screen VIEW panel PFLVIEW CNMS4217 Activates LU and uses TRAP and WAIT to PACTLU CNMS4218 determine if activation is successful

Table 19. PL/I Samples Shipped with the NetView Program (continued) Sample Function PL/I Alias Sample CNMSAMP Uses CNMSMSG to log text to a sequential log PSEQLOG CNMS4219 Sets a common global variable for the USERVSAM PXITDI CNMS4220 DST Primes VSAM empty data set for USERVSAM DST PXITVN CNMS4221 Sends a request to USERVSAM DST PSNDDST CNMS4222 Processes VSAM requests under USERVSAM DST PDOVSAM CNMS4223 Primes VSAM empty data set for PKEYIO PPRIME CNMS4224 Sends a software alert to an application over the PHSNDMU CNMS4226 high performance transport Uses CNMQAPI to access a RODM PRODMCON CNMS4230 Sends an MSU directly to the automation table for PAUTOTB CNMS4231 evaluation Registers or deregisters an application as an MS PREGISTR CNMS4232 application or an operations management served application Sends a software alert to ALERT_NETOP from an PSENDMU CNMS4233 MS application Registers an application with the high performance PHREGSTR CNMS4236 transport Uses CNMPMDB to process MDB PPRSMDB CNMS4239 Uses the PIPE command to activate an LU, wait, and PACTPIP CNMS4305 trap the output messages

PTMPPLT (CNMS4200) This sample is a template for commands and installation exit routines in PL/I.

It appears in Chapter 7, “PL/I high-level language services,” on page 59.

PEXIT3 (CNMS4210) This is a sample DSIEX03 that sets a task global variable. This global variable contains the value of the last time that a command other than PSNDDAT was entered under an operator station task (OST). PWATDAT and PSNDDAT are used to interrogate this value. The HLL service routines used in this sample are CNMINFC (CNMINFOC) and CNMVARS (CNMVARPOOL).

PSNDDAT (CNMS4211) This sample uses CNMSMSG to send data. The sample is part of an example of sending messages containing a request, waiting for the response, and parsing the results.

272 Programming: PL/I and C PL/I Samples

variable and uses CNMSMSG to send the data back to the task that issued the PWATDAT. PWATDAT breaks out of the wait state and parses and displays the data.

The HLL service routines used in this sample are CNMVARS (CNMVARPOOL), CNMSMSG (CNMSENDMSG), and CNMINFC (CNMINFOC).

PWATDAT (CNMS4212) This sample uses the WAIT FOR DATA request. The sample is part of an example of sending messages containing a request, waiting on the response, and parsing the results.

The example finds the last time that a command was entered on a given OST. A task global variable is set by PEXIT3 every time a command is entered on an OST. PWATDAT uses CNMSMSG to issue a PSNDDAT on the task in question. PWATDAT then goes into a wait state. PSNDDAT retrieves the value of the global variable and uses CNMSMSG to send the data back to the task that issued the PWATDAT. PWATDAT breaks out of the wait state and parses and displays the data.

The HLL service routines used in this sample are CNMSMSG (CNMSENDMSG), CNMSCAN (CNMSSCAN), CNMCMD (CNMCOMMAND), and CNMGETD (CNMGETDATA).

PEXIT2A (CNMS4213) This sample exit converts a write-to-operator (WTO) to a multiline write-to-operator (MLWTO) by adding two lines to the single-line WTOs that drive the exit. The HLL service routines used in this sample are CNMGETD (CNMGETDATA) and CNMALTD (CNMALTDATA).

PCNMI (CNMS4214) This sample uses CNMCNMI to send FORWARD RUs to a PU requesting that the product set ID be returned. Any data returned is sent as a message to the operator. The prolog of the sample contains instructions for setup.

The NetView program provides the CNMCNMI service routine for use in communicating with devices in the network through the communications network management interface (CNMI). You can access any data that is returned using the CNMGETD service routine to retrieve records from the CNMI solicited data queue (CNMIQ).

The HLL service routines used in this sample are CNMSCAN (CNMSSCAN), CNMCNMI (CNMI), CNMGETD (CNMGETDATA), and CNMSMSG (CNMSENDMSG).

PKEYIO (CNMS4215) This sample illustrates how to code a NetView HLL command processor that allows input/output (I/O) to a VSAM file through the CNMKIO service routine. The command processor must run on a data services task (DST). To run this command, use the EXCMD command or the CNMSMSG service routine (using type set to COMMAND). The prologue of the sample explains how to set up the command processor.

Appendix B. PL/I samples 273 PL/I Samples

The HLL service routines used in this sample are CNMKIO (CNMKEYIO) and CNMSMSG (CNMSENDMSG).

PSCOPCK (CNMS4216) This sample illustrates the command authorization checking capabilities provided by the NetView program. It authorizes keywords and values using the PSCOPCK command. Set up the following elements: v Operator ID v Operator classes that can access the command v Operator profile

Refer to the prologue of the sample for more information. This command yields a message if the operator is not authorized to use the keyword and value specified when invoking the command.

The HLL service routines used in this sample are CNMSCAN (CNMSSCAN), CNMSCOP (CNMSCOPECK), and CNMSMSG (CNMSENDMSG).

PFLVIEW (CNMS4217) This sample illustrates the use of the full-screen VIEW command processor.

The HLL service routines used in this sample are CNMCMD (CNMCOMMAND) and CNMVARS (CNMVARPOOL).

PACTLU (CNMS4218) This sample illustrates how to issue a VTAM command to activate a logical unit (LU), trap the VTAM messages that result, and respond depending on the messages received.

The HLL service routines used in this sample are CNMSCAN (CNMSSCAN), CNMCMD (CNMCOMMAND), CNMGETD (CNMGETDATA), and CNMSMSG (CNMSENDMSG).

PSEQLOG (CNMS4219) This sample uses CNMSMSG to log text to a sequential log. The prolog of the sample contains instructions for setup.

The HLL service routines used in this sample are CNMSCAN (CNMSSCAN), CNMINFC (CNMINFOC), and CNMSMSG (CNMSENDMSG).

PXITDI (CNMS4220) This sample illustrates the DST initialization exit that is used by the USERVSAM DST. The HLL service routines used in this sample are CNMVARS (CNMVARPOOL) and CNMSMSG (CNMSENDMSG).

PXITVN (CNMS4221) This sample primes a VSAM empty data set for the USERVSAM DST.

274 Programming: PL/I and C PL/I Samples

PSNDDST (CNMS4222) This sample sends a PUT or GET request to the sample HLL data services command processor PDOVSAM to store and retrieve a given value for a specified key (key and value limited to 11 characters in length). The sample also allows a specified NetView program command list language variable (defined by the caller) to be set to the retrieved value.

The HLL service routines used in this sample are CNMSCAN (CNMSSCAN), CNMSMSG (CNMSENDMSG), CNMVARS (CNMVARPOOL), CNMGETD (CNMGETDATA), and CNMCMD (CNMCOMMAND).

PDOVSAM (CNMS4223) This sample is an HLL data services command processor that runs under the sample data services task (task ID USERVSAM). It processes PUT or GET requests sent by the PSNDDST sample, and writes or reads an 11-character value associated with an 11-character key to the sample DST's VSAM data set. The prologue of PDOVSAM contains instructions on installing the sample USERVSAM data services task.

The HLL service routines used in this sample are CNMSCAN (CNMSSCAN), CNMSMSG (CNMSENDMSG), and CNMKIO (CNMKEYIO).

PPRIME (CNMS4224) This sample primes a VSAM empty data set for PKEYIO.

PHSNDMU (CNMS4226) This sample sends a software alert to an application over the high performance transport.

The HLL service routines used are CNMHSMU (CNMHSENDMU) and CNMSMSG (CNMSENDMSG).

PRODMCON (CNMS4230) This sample invokes CNMQAPI which enables the user to access a RODM under the control of the NetView program. The coded example shows a RODM CONNECT function.

The HLL service routines used in this sample are CNMSMSG (CNMSENDMSG) and CNMQAPI (CNMOPREP).

PAUTOTB (CNMS4231) This sample sends an MSU directly to the automation table for evaluation. This sample provides a method of testing automation table statements without sending an alert through the hardware monitor.

The HLL service routines used in this sample are CNMAUTO (CNMAUTOTAB), CNMSMSG (CNMSENDMSG), and CNMSCAN (CNMSSCAN).

Appendix B. PL/I samples 275 PL/I Samples

PREGSTR (CNMS4232) This sample registers or deregisters an application as an MS application or an operations management served application.

Provide the following information: v Application name v Command name v Logmode v Replace option v Registration type

Refer to the prologue of the sample for more information. This command sends a message to the invoking operator that reports the return code from the registration or deregistration.

The HLL service routines used in this sample are CNMRGS (CNMREGIST), CNMSMSG (CNMSENDMSG), and CNMSCAN (CNMSSCAN).

PSENDMU (CNMS4233) This sample sends a software alert to ALERT_NETOP from an MS application.

The HLL service routines used in this sample are CNMSMU (CNMSENDMU) and CNMSMSG (CNMSENDMSG).

PHREGSTR (CNMS4236) This sample registers an application with the high performance transport.

Provide the following information: v Application name v Command name v Replace option v Registration type v Focal point category v Focal point option v Notify option

Refer to the prologue of the sample for more information. This command sends a message to the invoking operator that reports the return code from the registration or deregistration.

The HLL service routines used in this sample are CNMHRGS (CNMHREGIST), CNMSMSG (CNMSENDMSG), and CNMSCAN (CNMSSCAN).

PPRSMDB (CNMS4239) This HLL sample sends a Message Data Block (MDB) to the NetView program for processing. The MDB is a designed structure for message data. The MDB structure is mapped by the MVS control block IEAVM105.

276 Programming: PL/I and C PL/I Samples

The HLL services used in this sample are CNMPMDB (CNMPRSMDB) and CNMSMSG (CNMSENDMSG).

PACTPIP (CNMS4305) This sample illustrates how to use the PIPE command to issue a VTAM command. The VTAM command activates a logical unit (LU), traps the resulting VTAM messages, and responds depending on the messages received.

The HLL service routines used in this sample are CNMSCAN (CNMSSCAN), CNMVARS (CNMVARPOOL), CNMCMD (CNMCOMMAND), and CNMSMSG (CNMSENDMSG).

Appendix B. PL/I samples 277 278 Programming: PL/I and C Appendix C. C language control blocks and include files

Table 20 describes the C control blocks and the include files needed to write command processors and installation exits in the C language. The files are located in the SCNMMAC1 data set. Table 20. List of C control blocks and include files Include File Description DSIC include file This file is required and must be included by all HLL programs written in C. DSIC includes all of the external HLL control blocks and include files needed to run C programs in the NetView environment. DSICCONS control This file contains the definitions for constants that are helpful when block coding HLL modules in C. DSICVARC structure This structure type represents varying length character strings for type use in NetView HLL service routine invocations. DSICHLB control This file contains a C mapping of the NetView HLL control block block (HLB). The HLB is built during command processor initialization and exists for the lifetime of the command processor. DSICORIG control This file maps the origin block of the request that initiated the block current procedure. DSICPRM control This file defines the NetView Bridge parameter control block for C. block DSICCALL control This file defines the service routines for C. block DSICCNM control This file defines the HLL return codes for C. block

280 Programming: PL/I and C Appendix D. C samples

This appendix contains a table of the C samples that are shipped with the NetView program in the CNMSAMP data set. When a data set name is referred to in this appendix, two names are given, for example CTMPPLT (CNMS4201). The first name is the alias name, and the name in parentheses is in the NetView samples library. You can use either name to access the samples. CNMCMD has definitions for the alias names to enable those names to be entered as commands.

To enter the member names as commands, perform the following steps: 1. Compile and link-edit the samples using the alias name. 2. Delete the * in column 1 of the appropriate CMDDEF statement in CNMCMD to run the alias name as a command. No entries are needed in CNMCMD for installation exits. 3. Recycle the NetView program for the CNMCMD changes to take effect.

Note: 1. Refer to the prolog of the samples for information about how certain samples are related and special cases for installation exit routines. 2. Each alias name for C begins with the letter C.

This appendix also contains a description of each sample, and coded samples of an installation exit routine and two command processors.

C language samples table The following table refers to the C language samples that are shipped with the NetView program. The table contains the function, the alias name, and the name of the member in NETVIEW.V6R2M0.CNMSAMP. Table 21. C Samples Shipped with the NetView Program Sample Function C Alias Sample CNMSAMP Template for commands and installation exit routines CTMPPLT CNMS4201 Sample DSIEX03 to set a global variable CEXIT3 CNMS4240 Uses Cnmsmsg to send data CSNDDAT CNMS4241 Uses WAIT FOR DATA CWATDAT CNMS4242 Sample DSIEX02A changes a WTO to an MLWTO CEXIT2A CNMS4243 Uses Cnmcnmi to forward RUs to a PU CCNMI CNMS4244 Uses Cnmkio for I/O to VSAM CKEYIO CNMS4245 HLL command using Cnmscop for command authorization CSCOPCK CNMS4246 checking Display full screen VIEW panel CFLVIEW CNMS4247 Activates LU and uses TRAP and WAIT to determine if activation CACTLU CNMS4248 is successful Uses Cnmsmsg to log text to a sequential log CSEQLOG CNMS4249 DST initialization exit for USERVSAM DST CXITDI CNMS4250 Primes VSAM empty data set for USERVSAM DST CXITVN CNMS4251

Table 21. C Samples Shipped with the NetView Program (continued) Sample Function C Alias Sample CNMSAMP Sends a request to USERVSAM DST CSNDDST CNMS4252 Processes VSAM requests under USERVSAM DST CDOVSAM CNMS4253 Primes VSAM empty data set for CKEYIO CPRIME CNMS4254 Sends a software alert to an application over the high performance CHSNDMU CNMS4256 transport Uses CNMQAPI to access an RODM CRODMCON CNMS4260 Sends an MSU directly to the automation table for evaluation CAUTOTB CNMS4261 Registers or deregisters an application as an MS application on an CREGISTR CNMS4262 operations management served application Sends a software alert to ALERT_NETOP from an MS application CSENDMU CNMS4263 Registers an application with the high performance transport CHREGSTR CNMS4264 HLL call to process MDB service CPRSMDB CNMS4269 Uses the PIPE command to activate an LU, wait and trap the CACTPIP CNMS4405 output messages

CTMPPLT (CNMS4201) A template for commands and installation exit routines in C. It is included in Chapter 9, “C high-level language services,” on page 117.

CEXIT3 (CNMS4240) A sample DSIEX03 that sets a task global variable. This global variable contains the value of the last time that a command other than CSNDDAT was entered under an operator station task (OST). CWATDAT and CSNDDAT are used to interrogate this value. The HLL service routines used in this sample are Cnminfc and Cnmvars.

CSNDDAT (CNMS4241) Uses Cnmsmsg to send data. It is part of an example of sending messages containing a request, waiting on the response, and parsing the results.

The example finds the last time that a command was entered on a given OST. A task global variable is set by CEXIT3 every time a command is entered on an OST. CWATDAT uses Cnmsmsg to issue a CSNDDAT on the task in question. CWATDAT then goes into a wait state. CSNDDAT retrieves the value of the global variable and uses Cnmsmsg to send the data back to the task that issued the CWATDAT. CWATDAT breaks out of the wait state (it has received the data it was waiting for), and parses and displays the data.

The HLL service routines used in this sample are Cnmvars, Cnmsmsg, and Cnminfc.

CWATDAT (CNMS4242) Uses WAIT FOR DATA. It is part of an example of sending messages with a type of request, waiting on the response, and parsing the results.

Its purpose is to find the last time that a command was entered on a given OST. A task global variable is set by CEXIT3 every time a command is entered on an OST.

282 Programming: PL/I and C C Samples

CWATDAT uses Cnmsmsg to issue a CSNDDAT on the task in question. CWATDAT then goes into a wait state. CSNDDAT retrieves the value of the global variable and uses Cnmsmsg to send the data back to the task that issued the CWATDAT. CWATDAT breaks out of the wait state (it has received the data it was waiting for), and parses and displays the data.

The HLL service routines used in this sample are Cnmsmsg, Cnmcmd, and Cnmgetd.

CEXIT2A (CNMS4243) An exit that converts a write-to-operator (WTO) to an MLWTO by adding two lines to the single-line WTOs that are driving the exit. The HLL service routines used in this sample are Cnmgetd and Cnmaltd.

CCNMI (CNMS4244) This sample uses Cnmcnmi to send RUs to a PU requesting that the product set ID be returned. Any data returned is sent as a message to the operator. The prolog of the sample contains instructions for setup.

The NetView program provides the Cnmcnmi service routine for communicating with devices in the network through the CNMI. You can access any data that is returned using the Cnmgetd service routine to retrieve records from the CNMI solicited data queue (CNMIQ).

The HLL service routines used in this sample are Cnmcnmi, Cnmgetd, and Cnmsmsg.

CKEYIO (CNMS4245) Shows how to code a NetView HLL command processor that allows input/output to a VSAM file through the Cnmkio routine. The command processor must run on a DST. To run this command, use the EXCMD command or the Cnmsmsg service routine (with a type of COMMAND). The prolog of the sample explains how to set up a DST.

The HLL service routines used in this sample are Cnmkio and Cnmsmsg.

CSCOPCK (CNMS4246) Shows the command authorization checking capabilities provided by the NetView program. It authorizes keywords and values using the CSCOPCK command. For the command, set up: v Operator ID v Operator classes that can access the command v Operator profile

Refer to the prolog of the sample for more information. This command yields a message if the operator is not authorized to use the keyword and value specified when invoking the command.

The HLL service routines used in this sample are Cnmscop and Cnmsmsg.

Appendix D. C samples 283 C Samples

CFLVIEW (CNMS4247) Illustrates the use of the full-screen VIEW command processor.

The HLL service routines used in this sample are Cnmcmd and Cnmvars.

CACTLU (CNMS4248) Shows how to issue a VTAM command to activate an LU, trap the VTAM messages that result, and respond depending on the messages received.

The HLL service routines used in this sample are Cnmcmd, Cnmgetd, and Cnmsmsg.

CSEQLOG (CNMS4249) Uses Cnmsmsg to log text to a sequential log. The prolog of the sample contains instructions for setup.

The HLL service routines used in this sample are Cnminfc and Cnmsmsg.

CXITDI (CNMS4250) Illustrates the DST initialization exit that is used by the USERVSAM DST. The HLL service routines used in this sample are Cnmvars and Cnmsmsg.

CXITVN (CNMS4251) Prepares a VSAM empty data set for the USERVSAM DST.

CSNDDST (CNMS4252) Sends a PUT or GET request to the sample HLL data services command processor CDOVSAM to store and retrieve a given value for a specified key (key and value limited to 11 characters in length). The sample also allows a specified NetView command list language variable (defined by the caller) to be set to the retrieved value.

The HLL service routines used in this sample are Cnmsmsg, Cnmvars, Cnmgetd, and Cnmcmd.

CDOVSAM (CNMS4253) Is an HLL data services command processor that runs under the sample data services task (task ID USERVSAM). The command processor processes PUT or GET requests sent by the CSNDDST sample, and writes or reads an 11-character value associated with an 11-character key to the sample DST’s VSAM data set. The prolog of CDOVSAM contains instructions on installing the sample USERVSAM data services task.

The HLL service routines used in this sample are Cnmsmsg and Cnmkio.

CPRIME (CNMS4254) Prepares a VSAM empty data set for CKEYIO.

284 Programming: PL/I and C C Samples

CHSNDMU (CNMS4256) Sends a software alert to an application over the high performance transport.

The HLL service routines used are Cnmhsmu and Cnmsmsg.

CRODMCON (CNMS4260) Starts CNMQAPI which enables the user to access a RODM under the control of the NetView program. The coded example shows a RODM CONNECT function.

The HLL service routines used in this sample are Cnmsmsg and Cnmqapi.

CAUTOTB (CNMS4261) Sends an MSU directly to the automation table for evaluation. It provides a method of testing automation table statements without sending an alert through the hardware monitor.

The HLL service routines used in this sample are Cnmauto, Cnmsmsg, and Cnmscan.

CREGISTR (CNMS4262) Registers or deregisters an application as an MS application or an operations management served application.

Provide the following information: v Application name v Command name v Logmode v Replace option v Registration type

Refer to the prolog of the sample for more information. This command sends a message to the invoking operator that reports the return code from the registration or deregistration.

The HLL service routines used in this sample are Cnmrgs and Cnmsmsg.

CSENDMU (CNMS4263) Sends a software alert to ALERT_NETOP from an MS application.

The HLL service routines used in this sample are Cnmsmu and Cnmsmsg.

CHREGSTR (CNMS4266) Registers an application with the high performance transport.

Provide the following information: v Application name v Command name v Replace option

Appendix D. C samples 285 C Samples

v Registration type v Focal point category v Focal point option v Notify option

Refer to the prologue of the sample for more information. This command sends a message to the invoking operator that reports the return code from the registration or deregistration.

The HLL service routines used in this sample are Cnmhrgs and Cnmsmsg.

CPRSMDB (CNMS4269) This HLL sample sends an MDB to the NetView program for processing. The MDB is a designed structure for message data. The MDB structure is mapped by the MVS control block IEAVM105. The HLL service routines used in this sample are Cnmpmdb and Cnmsmsg.

CACTPIP (CNMS4405) Shows how to use the PIPE command to issue a VTAM command which activates an LU, traps the resulting VTAM messages, and responds depending on the messages received.

The HLL service routines used in this sample are Cnmvlc, Cnmvars, Cnmcmd, and Cnmsmsg.

286 Programming: PL/I and C Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan, Ltd. 19-21, Nihonbashi-Hakozakicho, Chuo-ku Tokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement might not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Corporation 2Z4A/101 11400 Burnet Road Austin, TX 78758 U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM’s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:

288 Programming: PL/I and C Programming Interfaces This publication documents intended Programming Interfaces that allow the customer to write programs to obtain the services of Tivoli NetView for z/OS.

Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at http://www.ibm.com/legal/copytrade.shtml .

Adobe is a trademark of Adobe Systems Incorporated in the United States, and/or other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other product and service names might be trademarks of IBM or other companies.

Privacy policy considerations IBM Software products, including software as a service solutions, (“Software Offerings”) may use cookies or other technologies to collect product usage information, to help improve the end user experience, to tailor interactions with the end user or for other purposes. In many cases no personally identifiable information is collected by the Software Offerings. Some of our Software Offerings can help enable you to collect personally identifiable information. If this Software Offering uses cookies to collect personally identifiable information, specific information about this offering’s use of cookies is set forth below.

This Software Offering does not use cookies or other technologies to collect personally identifiable information.

If the configurations deployed for this Software Offering provide you as customer the ability to collect personally identifiable information from end users via cookies and other technologies, you should seek your own legal advice about any laws applicable to such data collection, including any requirements for notice and consent.

For more information about the use of various technologies, including cookies, for these purposes, See IBM’s Privacy Policy at http://www.ibm.com/privacy and IBM’s Online Privacy Statement at http://www.ibm.com/privacy/details the section entitled “Cookies, Web Beacons and Other Technologies” and the “IBM Software Products and Software-as-a-Service Privacy Statement” at http://www.ibm.com/software/info/product-privacy.

Notices 289 290 Programming: PL/I and C Index

asynchronous (continued) Special characters panel update 4 (\0) end-of-string character 109 atdata operand 185 & (address) operator 106, 107 ATTNID, CNMGETA attribute 195 &HDRMTYPE variable 207 AUTCONID 218 &LINETYPE variable 207 authorization checking &MSGID variable 207 command 75, 138 &MSGORIGIN variable 207 command, keyword, value 249 &PARMSTR variable 62 logon 18 &PAUSE function 72, 134 authorized receiver 251 #pragma C variable 39 automating MSUs {} type specifier 248 C example 157 PL/I example 90 automating NetView messages 4 A AUTOTOKE, CNMGETA attribute 195 AAUTSKLP subtask 22 abbreviate command 17 access B command list variable BNJDSERV subtask 22 C example 130 BNJNETOP data set 22 PL/I example 70 BNJPALEX installation exit 13, 14 data 4 BNJPNL1 data set 232 data set 80, 144 BNJPNL2 data set 232 servers across hosts 8 books storage 79, 143 see publications xiii VSAM file 83 BSAM 21 accessibility xvii building request units, CNMI 119 ACTIONDL, CNMGETA attribute 194 ACTIONMG, CNMGETA attribute 194 adbuf operand 184 ADDR function C description 53 C control blocks, description 112 IEL0872I message 53 C examples passing pointer variables 52 accessing command list variables 130 address of the HLB control block 103 altering data 141 addressing mode 44 automating MSUs 157 adfunc operand 184 CNMI 145 adindex operand 184 coding DST installation exits 151 adorigin operand 54, 108, 184 coding installation exits 152 adqueue operand 184 coding WAIT FOR DATA 153 alert command authorization checking 138 high-performance transport data set access 144 C example 161 Hlbrc C return code field 12 PL/I example 96 invoking synchronous commands 123 MS transport keyed file access 149 C example 160 locks 133 PL/I example 95 message processing 137 alias, C sample 281 operator input 134 ALLOCATE command 7, 56, 113 registering applications allocating files, PL/I 56 high-performance transport 159 altering data MS transport 158 C example 141 operations management 158 PL/I example 78 registering applications, MS transport 158 API (application program interface) 4 registering applications, operations management 158 application registration retrieving information 129 with high-performance transport 94, 159 sending alerts, MS transport 160 with MS transport 92, 158, 241 sending commands 123 argc parameter in C 103 sending data, high-performance transport 161 argv parameter in C 103 sending MDB to NetView 162 asynchronous sending messages 122 command running 3 storage access 143

© Copyright IBM Corp. 1997, 2013 291 C examples (continued) CCNMI (CNMS4244) C sample 283 translating code points 158 CDOVSAM (CNMS4253) C sample 14, 284 VIEW command processor 136 CEEUOPT CSECT 50 VSAM access 149 CEXIT2A (CNMS4243) C sample 13, 283 waiting, trapping 125 CEXIT3 (CNMS4240) C sample 13, 282 C I/O considerations 113 CFLVIEW (CNMS4247) C sample 284 C include files character strings description 112 parsing 7 DSIC 112, 279 varying length 119 DSICCALL 113, 279 checking authorization 18 DSICCNM 113, 279 CHREGSTR (CNMS4266) C sample 285 DSICCONS 113, 279 CHSNDMU (CNMS4256) C sample 285 DSICHLB 113, 279 CKEYIO (CNMS4245) C sample 14, 283 DSICORIG 113, 279 client and server requests, response handling 3 DSICPRM 113, 279 CLOCK 218 DSICVARC 113, 279 close partitioned data set 231 C module, coding Cmdbuf 103 interfaces 103 description 103 restrictions 115 initial parameter in C 103 C program qualification, using DSIEX02A 103 installation exits, performance considerations 12 CMDBUF interfaces 103 initial parameter in PL/I 49 production environment 114 replace a message 12 restrictions 103 CMDDEF statement required to run HLL program 115 test environment 114 cmdstr operand 187 C programs, coding initial parameters 103 cndata operand 189 C runtime considerations 114 cndest operand 189 C runtime options 103 cnfunc operand 189 C sample template 117 CNM C samples data services 28 CACTLU (CNMS4248) 284 interface, sending and receiving data 6 CACTPIP (CNMS4405) 127, 286 request 22 CAUTOTB (CNMS4261) 285 CNM987I message 170 CCNMI (CNMS4244) 283 CNM988I message 170 CDOVSAM (CNMS4253) 14, 284 CNMALTD (CNMALTDATA) service routine CEXIT2A (CNMS4243) 13, 283 description 183 CEXIT3 (CNMS4240) 13, 282 syntax 183 CFLVIEW (CNMS4247) 284 CNMAUTO (CNMAUTOTAB) service routine 185 CHREGSTR (CNMS4266) 285 CNMC2T (CNMCODE2TXT) service routine 192 CHSNDMU (CNMS4256) 285 CNMCELL (CNMSTRCELL) service routine CKEYIO (CNMS4245) 14, 283 description 186, 237 CPRIME (CNMS4254) 14, 284 syntax 186 CPRSMDB (CMS4269) 286 CNMCMD (CNMCOMMAND) CREGISTR (CNMS4262) 285 issuing operator commands 175 CRODMCON (CMS4260) 285 CNMCMD (CNMCOMMAND) service routine CSCOPCK (CNMS4246) 283 description 187 CSENDMU (CNMS4263) 285 syntax 187 CSEQLOG (CNMS4249) 284 CNMCMD data set member 249 CSNDDAT (CNMS4241) 13, 282 CNMCMD service routine CSNDDST (CNMS4252) 284 excluding, installation exits 11 CTMPPLT (CNMS4201) 282 CNMCNMI (CNMI) service routine CWATDAT (CNMS4242) 13, 282 description 189 CXITDI (CNMS4250) 14, 284 example 81, 145 CXITVN (CNMS4251) 14, 284 excluding, installation exits 11 table of 281 syntax 189 c type specifier 247 CNMCPYS (CNMCOPYSTR) service routine C/C++ programs description 190 TRAP(OFF) option 104 example 106 C/C++programs CNMCSSIR 13 achieving optimum performance 104 CNMGETA (CNMGETATTR) service routine 193 CACTLU (CNMS4248) C sample 284 CNMGETD (CNMGETDATA) service routine CACTPIP (CNMS4405) C sample 127, 286 description 134, 204 cancelable, defining programs 39 example 145 cancelling a command procedure 179 syntax 204 cancelling and terminating HLL program 39 CNMGETD function 61 CART, CNMGETA attribute 195 CNMHRGS (CNMHREGIST) service routine 208 CAUTOTB (CNMS4261) C sample 285 CNMHSMU (CNMHSENDMU) service routine 212

292 Programming: PL/I and C CNMI coding DST installation exits (continued) building request units 119 concatenating 13 C example 145 PL/I example 85 interface required by DST 27 coding installation exits PL/I example 81 C example 152 CNMINFC (CNMINFOC) service routine PL/I example 86 description 69, 218 coding WAIT FOR DATA syntax 218 C example 153 CNMINFI (CNMINFOI) service routine PL/I example 87 description 69, 221 command authorization 75, 138, 249 syntax 221 command cancellation 179 CNMIPXL (CNMIPXLATE) service routine command line, Cmdbuf 103 description 224 command list variable, accessing 5, 130 syntax 224 command processor CNMIQ access queue 61, 121, 207 environment 223 CNMKIO (CNMKEYIO) service routine non-preinitialized environments, steps for description 227 implementing 34 excluding, installation exits 11 PL/I support 49 syntax 227 preinitialized environments, steps for implementing 34 CNMLK (CNMLOCK) service routine VIEW 136 description 57, 229 commands syntax 229 abbreviation 17 CNMMEMC (CNMCLOSMEM) service routine ALLOCATE 7 description 80, 144, 231 authorization 249 syntax 231 CNMSCOP service routine 249 CNMMEMO (CNMOPENMEM) service routine FREE 7 description 80, 144, 232 PIPE 177 syntax 232 sending with C 123 CNMMEMR (CNMREADMEM) service routine sending with PL/I 65 description 80, 144, 233 synchronous execution 123 syntax 233 synchronous invocation 65 CNMNAMS (CNMNAMESTR) service routine 234 synchronous running 3 Cnmnvlc C convert string 109, 111, 120 synonym 17 CNMPMDB (CNMPRSMDB) service routine 236 verifying authorization 16 CNMPNL1 data set 232 commands, HLL CNMPOOL (CNMSTRPOOL) service routine GLOBALV 175 description 237 overview 175 example 108 QUEUE 178 CNMQAPI (CNMOPREP) service routine 239 RESET 175, 179 CNMRGS (CNMREGIST) service routine 241 common global (CGLOBAL) CNMSCAN (CNMSSCAN) service routine 246 command list variable 5 CNMSCOP (CNMSCOPECK) service routine 249 pool 263, 265 CNMSMSG (CNMSENDMSG) service routine variables 70, 130, 133 description 17, 26, 251 common global pool 264 excluding, installation exits 11 common global variables 130 syntax 251 communicating with devices 81, 145 CNMSMU (CNMSENDMU) service routine 254 communications network management interface (CNMI) 189 CNMSUBS 261 completion code 58, 115 CNMSUBSYM 261 concatenate DST installation exits 13 CNMVARS (CNMVARPOOL) service routine 263 control blocks Cnmvlc C convert string 109, 110, 119 C 112, 279 cntimout operand 189 PL/I 55, 269 CNVTOHEX constant 111, 112 control line message 252 code controlling locks 229 C program conventions interfaces 103 typeface xviii restrictions 103 converting PL/I program DSICCONS 111, 112 environment 49 hexadecimal 111, 112 interfaces 49 initial parameters, sscanf 103 restrictions 49 copying storage 7 code points, translating correlarea operand 212 C example 158 CPRIME (CNMS4254) C sample 14, 284 PL/I example 91 CPRSMDB (CMS4269) C sample 286 code template 59, 117 CPU time (TOD Clock) 220 coding DST installation exits CREGISTR (CNMS4262) C sample 285 C example 151 critical preinitialized programs 40

Index 293 CRODMCON (CMS4260) C sample 285 device communications 81, 145 cross-domain directory names, notation xix alert 22 DISCORIG, mapping Origblck 103 command 17 DISPLAY, avoiding 58 traffic, monitor 17 domain ID 207, 219 CSCOPCK (CNMS4246) C sample 283 DSCP 28 CSENDMU (CNMS4263) C sample 285 DSIC C include file 109, 112, 279 CSEQLOG (CNMS4249) C sample 284 DSICCALL C include file 113, 279 csfrom operand 191 DSICCNM cslen operand 191 C include file 113, 279 CSNDDAT (CNMS4241) C sample 13, 282 resolving composite return codes 173 CSNDDST (CNMS4252) C sample 284 DSICCONS C include file 108, 113, 279 csto operand 191 DSICES macro 188 cstype operand 191 DSICHLB C include file 279 CTMPPLT (CNMS4201) C sample 282 DSICLD data set 232 CURCONID 219 DSICORIG C include file 113, 279 current date function 219 DSICPRM C include file 113, 279 CURSYS 219 DSICRTR subtask 22 customization, check 18 DSICVARC C include file 109, 113, 279 cvdata operand 263 DSIDKS macro 232 cvdatlen operand 263 DSIEX01 installation exit 13, 14 cvfunc operand 263 DSIEX02A installation exit 13, 14 cvname operand 264 DSIEX03 installation exit 13, 15 cvpool operand 264 DSIEX04 installation exit 13, 15, 16 CWATDAT (CNMS4242) C sample 13, 282 DSIEX05 installation exit 13, 16 CXITDI (CNMS4250) C sample 14, 284 DSIEX06 installation exit 13, 16 CXITVN (CNMS4251) C sample 14, 284 DSIEX07 installation exit 13, 17 DSIEX09 installation exit 13, 17 DSIEX10 installation exit 13, 17 D DSIEX11 installation exit 13, 17 DSIEX12 installation exit 13, 18 d type specifier 247 DSIEX13 installation exit 13, 19 data access 4 DSIEX14 installation exit 13, 19 data alteration 78, 141 DSIEX16 installation exit 13, 20 data definition (DD) statement 56, 113 DSIEX16B installation exit 13, 20 data queue 5 DSIEX17 installation exit 13, 20 data queue management 61, 121 DSIEX18 installation exit 13, 20 data set access DSIEX19 installation exit 13, 20 C example 144 DSIEX20 installation exit 13, 21 closing 231 DSIEX21 installation exit 13, 21 opening 232 DSIGET macro 178 PL/I example 80 DSILCS macro 188 data sets, access from HLL 7 DSILOG task 26 data, requesting DSILOGDS mapping function 26 C 154 DSIMQS macro 19, 178 PL/I 88 DSIMSG data set 232 data, sending DSIOPEN data set 232 C 156 DSIPARM data set 232 PL/I 89 DSIPCNM PL/I include file 56, 269 DATAQ access queue 61, 121, 207 DSIPCONS PL/I include file 55, 269 datatype operand 214 DSIPHLB PL/I include file 55, 269 DATE 219 DSIPHLLS PL/I include file 56, 269 DATETIM2 219 DSIPLI PL/I include file 55, 269 DATETIME 219 DSIPORIG PL/I include file 55, 269 deallocate files DSIPPRM PL/I include file 56, 269 deallocating files 56 DSIPRF data set 232 dynamically 7 DSIPSS macro 15 PL/I 56 DSIPUSH macro 236 debug support DSITIB control block 223 remote interactive debugger (RID) 8, 167 DSITRACE task 26 traces 8 DSITVB control block 222, 223 DELAY, avoiding 58 Dsivarch, varying length character string 106, 109, 119 deleting a message 12 DSIVTAM data set 232 deliver request unit (RU) 22 DSIWCS macro 17 DESC, CNMGETA attribute 195 DSIZCSMS macro 174 destappl operand 213 DSRBO keyword 29 destlu operand 213 destnet operand 213

294 Programming: PL/I and C DST (data services task) examples (continued) coding C (continued) C 151 VSAM access 149 PL/I 85 waiting, trapping 125 described 27 PL/I installation exit routine altering data 78 XITBN 13, 21 CNMI 81 XITBO 13, 22 code points, translating 91 XITCI 14, 22 coding 85, 86, 87 XITCO 14, 24 coding, template 59 XITDI 14, 25 command authorization checking 75 XITVI 14, 25 command list variable access 70 XITVN 14, 25 data queue management 61 XITVO 14, 26 data set access 80 XITXL 14, 26 invoking synchronous commands 65 installation of 27, 190 MDB, sending to NetView 97 run commands in C 123 message processing 74 run commands in PL/I 65 MSUs, automating 90 run HLL services 57 operator input 72 schedule commands under 29 parsing character strings 62, 63 DST installation exit routine 11 registering applications 92, 94 DSTINIT 27, 29 retrieving information 69 dynamic file allocation, deallocation 7 sending alerts 95, 96 sending commands 65 sending messages 61 E storage access 79 using locks 71 ECVTPSEQ 219 VIEW command processor 73 edit VSAM keyed file access 83 log information 15 waiting and trapping 66 system console messages 17 resolving composite return codes 173 education external C variable, HLLOPTS see Tivoli technical training xvii HLL_NO_CANCEL runtime option 39 ELBLENG external logging offset 26 HLL_QUEUED_INPUT runtime option 38 ELBLOG external logging offset 26 syntax 38 ELBRLENG external logging offset 26 external log (EXTLOG operand) 26, 251 ELBTYPE external logging offset 26 external logging exit (XITXL) 14, 26 empty data set 21, 25 external trace log 15 end of multiline message 252 end-of-string character (\0) 109 environment variables, notation xix environment, PL/I 49 F errors, PL/I runtime 57 file allocating or deallocating 7 examples file I/O capability 56, 113 C FILE option 57 accessing command list variables 130 first failure data capture trace 8 altering data 141 fixed-length character strings 54, 108 automating MSUs 157 fixed-length variable, PL/I example 54 CNMI 145 focal point transfer RU header 23 coding DST installation exits 151 fopen 113 coding installation exits 152 format specifications 111 coding WAIT FOR DATA 153 forward RU 24 command authorization checking 138 FREE command 7, 56, 113 data queue management 121 full-screen data set access 144 capability 136 DSIEX02A installation exit 14 input/output 4 invoking synchronous commands 123 FUNCT, DSTINIT keyword 27 keyed file access 149 message processing 137 operator input 134 G retrieving information 129 gadata operand 193 sending an MDB to NetView 162 gadatlen operand 194 sending commands 123 ganame operand 194 sending messages 122 gaqueue operand 204 storage access 143 gdbuf operand 205 translating code points 158 gdbuflen operand 205 using locks 133 gdindex operand 206 VIEW command processor 136

Index 295 gdorigin operand 54, 108, 206 HLL definition facilities gdqueue operand 206 HLLENV command GET statement 57 DEFAULT keyword 38 getchar routine 114, 115 preinitialized environments, defining 37 GETDATA function 121 REGENVS and CRITENVS keywords 37 global installation exit 11 storage keywords 37 global variables 176 HLL installation exit routines GLOBALV command 176 invocation restriction 3 GO command 4, 177 overview 11 HLL PL/I restrictions 58 HLL program H accepting queued input 38 end on cancel/reset 39 HAPIENTR debug option 168, 171 HLL runtime options HAPIEXIT debug option 168, 171 default values 38 hardcopy log 15, 219 specifying, HLLOPTS 38 HCOPY 219 HLL service routines HDRMTYPE field 187 CNMALTD (CNMALTDATA) 183 hexadecimal conversation 111 CNMAUTO (CNMAUTOTAB) 185 high performance transport CNMC2T (CNMCODE2TXT) 192 description 6 CNMCELL (CNMSTRCELL) 186 NetView bridge remote access 8 CNMCMD(CNMCOMMAND) 187 PHREGSTR sample 276 CNMCNMI (CNMI) 189 PHSNDMU sample 275 CNMCPYS (CNMCOPYSTR) 190 high-level language 3 CNMGETA (CNMGETATTR) 193 high-performance transport CNMGETD (CNMGETDATA) 204 API 208, 212 CNMHRGS (CNMHREGIST) 208 CNMGETD service routine 207 CNMHSMU (CNMHSENDMU) 212 CNMHRGS service routine 210 CNMINFC (CNMINFOC) 218 CNMHSMU service routine 212, 216 CNMINFI (CNMINFOI) 221 data queue management 61, 121 CNMIPXL (CNMIPXLATE) 224 registering applications CNMKIO(CNMKEYIO) 227 C example 159 CNMLK (CNMLOCK) 229 PL/I example 94 CNMMEMC (CNMCLOSMEM) 231 sending alerts CNMMEMO (CNMOPENMEM) 232 C example 161 CNMMEMR (CNMREADMEM) 233 PL/I example 96 CNMMMDB (CNMMMDBPRS) 236 sending data CNMNAMS (CNMNAMESTR) 234 C example 161 CNMPOOL (CNMSTRPOOL) 237 PL/I example 96 CNMQAPI (CNMOPREP) 239 HLB control block 58, 115 CNMRGS (CNMREGIST) 241 Hlbleng C storage field 194, 218, 228 CNMSCAN (CNMSSCAN) 246 HLBLENG PL/I storage field 194, 218, 228 CNMSCOP (CNMSCOPECK) 249 Hlbptr CNMSMSG (CNMSENDMSG) 251 C pointer field 106 CNMSMU (CNMSENDMU) 254 description 103 CNMVARS (CNMVARPOOL) 263 initial parameter in C 103 description 183 restrictions for Cnmcpys invocation 106 input parameters HLBPTR fixed-length character strings 54 initial parameter of PL/I program 49 integer variables 53 PL/I pointer field 52 pointer variables 52 restrictions with pointer variables 52 varying-length character strings 54 Hlbrc HLL_NO_CANCEL runtime option return code field in C 12 description 39 HLBRC HLL_QUEUED_INPUT runtime option 38 resolving composite return codes 173 HLL, description 3 return code field in PL/I 12, 58 HLLENV command HLL command processors REGENVS and CRITENVS keywords coding in C 103 critical programs 37 considerations for 57, 115 programs 37 HLL commands HLLOPTS external C variable GO 175, 177 HLL_NO_CANCEL runtime option 39 overview 175 HLL_QUEUED_INPUT runtime option 38 QUEUE 175, 178 syntax 38 RESET 179 hrapplname operand 208 TRAP 175, 182 hrcmdname operand 209 WAIT 175, 182 hrlogmod 209

296 Programming: PL/I and C hrreplvalue operand 210 installation exits (continued) hrtype operand 210 descriptions (continued) logon validation 13, 18 message output, cross-domain 13 I message output, this domain 13 OST/NNT message receiver 13, 19 I/O considerations, PL/I output, operator 14 sharing files, PL/I and C 57 output, system console 13, 17 writing files, multiple programs 57 RUNCMD authorization 13, 20 icdata operand 218 SAW filtering 21 icdatlen operand 218 solicited VTAM messages 13, 16 icname operand 218 unsolicited VTAM messages 13, 17 IDATAQ access queue VSAM empty file 14, 25 description 61, 207 VSAM input 14, 25 usage 103, 184 VSAM output 14, 26 IEL0872I message 53 DST IFRAUGMT, CNMGETA attribute 195 C 151 IFRAUI3X, CNMGETA attribute 196 PL/I 85 IFRAUIN3, CNMGETA attribute 196 for HLL 11 IFRAUIND, CNMGETA attribute 195 general return codes 12 IFRAUSB2, CNMGETA attribute 196 names 13 IFRAUSC2, CNMGETA attribute 196 BNJPALEX 13, 14 IFRAUSRB, CNMGETA attribute 196 DSIEX01 13, 14 IFRAUSRC, CNMGETA attribute 196 DSIEX02A 13, 14 IFRAUTA1, CNMGETA attribute 196 DSIEX03 13, 15 IFRAUWF1, CNMGETA attribute 197 DSIEX04 13, 15 iiname operand 222 DSIEX05 13, 16 iinumb operand 224 DSIEX06 13, 16 immediate command 58, 115, 188 DSIEX07 13, 17 include files - C 112, 279 DSIEX09 13, 17 include files - PL/I 55, 269 DSIEX10 13, 17 information retrieval DSIEX11 13, 17 C 69 DSIEX12 13, 18 PL/I 129 DSIEX13 13, 19 initial command 15 DSIEX14 13, 19 initial data queue (IDATAQ) 103 DSIEX16 13, 20 initial operands, PL/I 49 DSIEX16B 13, 20 initial parameters - C 103 DSIEX17 13, 20 input before command processing 13 DSIEX18 13, 20 input from the operator 14 DSIEX19 13, 20 input from the system console 17 DSIEX20 13, 21 input, line mode 4 DSIEX21 13, 21 input/output considerations XITBN 13, 21 full-screen 4 XITBO 13, 22 preinitialized environments 57 XITCI 14, 22 installation exits 13 XITCO 14, 24 C coding 103 XITDI 14, 25 coding 11, 152 XITVI 14, 25 coding restrictions 11 XITVN 14, 25 deleting messages 12 XITVO 14, 26 described 11 XITXL 14, 26 descriptions 13 non-preinitialized environments, steps for alert generation exit routine 14 implementing 34 before logging off 13, 19 overview 11 before VTAM command invocation 13, 16 performance degradation 12 BSAM empty file 13, 21 PL/I coding 86 BSAM output 13, 22 PL/I support 49 CNM input 14, 22 preinitialized environments, steps for implementing 34 CNM interface output 14, 24 replacing messages 12 cross-domain command send 13, 17 integer variable, PL/I example 53 DST initialization 14, 25 integer variables 53, 107 encryption key for DSITCPRF 21 interfaces external logging 14, 26 C program 103 input before command processing 13 PL/I program 49 input, command processing 15 internal function request (IFR) 19 input, operator 14 interruption request block (IRB) exit 11 input, system console 13, 17 log output 13, 15

Index 297 invoking synchronous commands MCSFLAG, CNMGETA attribute 198 C example 123 mctoken operand 231 PL/I example 65 MDB IPV6 219 C example 162 IPv6Env statement 219 PL/I example 97 IRB (interruption request block) exit 11 processing 236 ISASIZ PL/I runtime option mdb operand 237 displayed by RID 170 MDS-MUs 5 istring operand 111, 112 MDSMU keyword CNMHSMU statement 214 CNMSMU statement 254 J MDSMUQ access queue 61, 121, 207 member name 232 JOBNAME, CNMGETA attribute 197 message identifier 207 JOBNUM, CNMGETA attribute 197 message receiver 19 message text 207 messages K automation 4, 14 key-sequenced data set (KSDS) 25 buffer, sending copies 17 key-sequenced VSAM files 227 change VTAM message 16 KEY, CNMGETA attribute 198 editing system console 17 keyed file access logging 8 C example 149 multiline 4, 74 PL/I example 83 NetView, automating 4 under a DST 227 processing, C example 137 keyword authorization checking 249 processing, PL/I example 74 replace 12, 14 send to a specific log 15 L sending a single unit 4 sending with C 122 label line message 252 sending, PL/I 61 LEOPTS static external variable 51, 105 suppress logging 15 line mode trapping 4 input 4 using 12 link-edit messages (event type) 182 JCL 43 MLWTO 4 PL/I program 43 moddname operand 232 lkfunc operand 230 momemnam operand 232 lkname operand 230 monitor cross-domain traffic 17 lkoption operand 230 motoken operand 232 lkscope operand 230 mrdata operand 233 local pool 264 mrdatlen operand 233 lock management mrinclude operand 233 C example 133 mrtoken operand 234 controlling 229 MS Applications 6 PL/I example 71 MS transport user-defined locks 7 registering applications log output 15 C example 158 logging messages 8 PL/I example 92 logical unit name 219 sending alerts LOGOFF command 19 C example 160 LOGOFF routine 223 PL/I example 95 logon validation 13, 18 MS transport layer 6 long-running command 187 MSGAUTH, CNMGETA attribute 198 LOSTERM exit 19 MSGCATTR, CNMGETA attribute 198 LU 219 MSGCBGPA, CNMGETA attribute 200 LU 6.2 transport 6, 215, 258 MSGCMISC, CNMGETA attribute 198 MSGCMLVL, CNMGETA attribute 199 MSGCMSGT, CNMGETA attribute 199 M MSGCOJBN, CNMGETA attribute 199 MACRF keyword 29 MSGCPROD, CNMGETA attribute 199 main function in C 103 MSGCSPLX, CNMGETA attribute 200 major vector key 23 MSGCSYID, CNMGETA attribute 200 management services (MS) transport 6 MSGDOMFL, CNMGETA attribute 200 manuals MSGGDATE, CNMGETA attribute 200 see publications xiii MSGGFGPA, CNMGETA attribute 201 MCGASID, CNMGETA attribute 198 MSGGMFLG, CNMGETA attribute 201

298 Programming: PL/I and C MSGGMID, CNMGETA attribute 201 NONMDSMU keyword (continued) MSGGSEQ, CNMGETA attribute 201 CNMSMU statement 254 MSGGSYID, CNMGETA attribute 201 NOSPIE runtime option MSGGTIME, CNMGETA attribute 201 C program 103, 113, 114 MSGSRCNM, CNMGETA attribute 201 NOSTAE runtime option MSGSRCOB, CNMGETA attribute 202 C program 103, 114 MSGTOKEN, CNMGETA attribute 202 notation MSGTSTMP, CNMGETA attribute 202 environment variables xix MSGTYP, CNMGETA attribute 202 path names xix MSU automating typeface xix C example 157 nsclass operand 235 PL/I example 90 nsfunc operand 235 multiline messages 4, 137, 205 nsleng operand 235 MVS console 18 nsname operand 235 MVS console operator task 18 nsptr operand 235 MVS JOB name/number 197 null terminator (\0) 108, 110, 111 MVS system 204 NV 219 MVS system log 15 NVVER 219 MVSLEVEL 219 MVTUFLD control block 223 O ON FIXEDOVERFLOW, avoiding 58 N ON OVERFLOW, avoiding 58 n type specifier 247 ON UNDEFINEDFILE statement 56 named storage 7, 234 ON UNDERFLOW, avoiding 58 NETID 219 ON ZERODIVIDE, avoiding 58 NetView online publications data sets 80, 144 accessing xvi domain ID (DOMAIN) 218 open capability 80, 144 information query 5 operands passed to HLL service routines invoking HLL commands 3 fixed-length character strings 54, 108 message type 207 integer variables 53, 107 partitioned data sets 7 pointer variables 52, 106 start time (STARTTIME) 220 varying length characters 54, 108 version and release (NVVER) 219 operating remote systems 6 NetView automation table 4 operating system 220 NetView Bridge access 8 operations management NetView command list language 62, 264 registering applications NetView command list language variables C example 158 &HDRMTYPE 204 PL/I example 92 &LINETYPE 204 transport layer 6 &MSGID 204 operator &MSGORIGIN 204, 207 full-screen input/output 4 NetView message automation 4 GO command 4 NetView partitioned data sets, read access from HLL 7 ID 219, 249 NetView tasks 13 ID name (function) 18 network log 15, 251 input 182 network services request units 22 input queue (OPERQ) 61, 121, 207 NEVDELID, CNMGETA attribute 203 input to a command procedure 4 new password function 18 interaction 3 NMVT request 22 LU name (function) 18 NNT task 13, 18 station tasks (OST) 65, 123 NOHEXCNV constant 111, 112 terminal 219 non-cancelable, defining programs 39 operator input non-preinitialized environments 33 C example 134 advantages and disadvantages 33 PL/I example 72 command processors, steps for implementing 34 operators in group 251 examples 41 OPERQ input queue 61, 121, 207 HLL definition facilities 35 OPID 219 HLL definition facilities, interface modules 36 OPINPUT wait command 177 installation exits, steps for implementing 34 OPSYSTEM 220 PL/I runtime options options, runtime entry points 50 default values 38 specifying 50 specifying HLLOPTS 50 storage values for 50 specifying, HLLOPTS 38 NONMDSMU keyword origappl operand 214 CNMHSMU statement 214 Origblck initial parameter, C program 103

Index 299 ORIGBLCK initial parameter, PL/I program 49 PL/I examples (continued) origin blocks 108 coding, DST installation exit 85 origin of request, Origblck 103 coding, installation exit 86 OST (operator station task) 13, 18 coding, WAIT FOR DATA 87 OST/NNT message receiver 19 command authorization checking 75 output data set access 80 operator 14 high-performance transport 96 system console 17 HLBRC field 12 OVERRIDE command options, DSIEX02A 14 invoking synchronous commands 65 OWNER 220 keyed file access 83 MDB, sending to NetView 97 message processing 74 P MS transport 95 MSUs, automating 90 PACTLU (CNMS4218) PL/I sample 274 operator input 72 PACTPIP (CNMS4305) PL/I sample 67, 277 overriding PSTACK and PHEAP values 51 pafld1,...pafld10 operand 246 parsing character strings panumfld operand 246 CNMSCAN 63 parameters passed to HLL service routines NetView 62 C 105 REXX 63 PL/I 51 registering applications parsing character strings 7, 62, 246 high-performance transport 94 PARTID, CNMGETA attribute 203 MS transport 92 partitioned data sets 7, 231, 232 operations management 92 password function 18 retrieving information 69 pastring operand 247 sending commands 65 path names, notation xix sending messages 61 pattern operand 247 storage access 79 PAUTOTB (CNMS4231) PL/I sample 275 using locks 71 pcfunc operand 186 VIEW command processor 73 PCNMI (CNMS4214) PL/I sample 273 VSAM access 83 pcstrptr operand 186 waiting and trapping 66 pctoken operand 186 PL/I high-level language services 59 PDDNM keyword 29 PL/I include files PDOVSAM (CNMS4223) PL/I sample 14, 275 description 55 performance considerations, PL/I and C installation exits 12 DSIPCNM 56, 269 PEXIT2A (CNMS4213) PL/I sample 13, 273 DSIPCONS 55, 269 PEXIT3 (CNMS4210) PL/I sample 13, 272 DSIPHLB 55, 269 PFLVIEW (CNMS4217) PL/I sample 274 DSIPHLLS 56, 269 PHREGSTR (CNMS4236) PL/I sample 276 DSIPLI 55, 269 PHSNDMU (CNMS4226) PL/I sample 275 DSIPORIG 55, 269 PID 220 DSIPPRM 56, 269 PIPE command PL/I INCLUDE files, optional C examples DSIPCNM 56 accessing stem variables 131 DSIPCONS 55 trapping messages 125 PL/I INCLUDE files, required description 177 DSIPHLLS 56 online help 178 DSIPLI 55 PL/I examples DSIPORIG 55 accessing stem variables 70 DSIPPRM 56 trapping messages 67 PL/I installation exits, support for 49 PKEYIO (CNMS4215) PL/I sample 273 PL/I program PL/I coding template 59 control blocks 55 commands to avoid DSIPHLB 55 DELAY 58 INCLUDE files 55 DISPLAY 58 preinitialized environment ON FIXEDOVERFLOW 58 runtime options automatically set 50 ON OVERFLOW 58 runtime options ON UNDERFLOW 58 TRAP(OFF) 57 ON ZERODIVIDE 58 TRAP(ON) 57 PLIRETC 58 PL/I command processors, support for 49 PLIRETV 58 PL/I examples WAIT 58 access command list variables 70 compiling 43 altering data 78 ending normally 58 CNMI 81 environment 49 code points, translating 91 file I/O capability 56 coding template 59

300 Programming: PL/I and C PL/I program (continued) preinitialized environments (continued) FILE option, failure to code 57 advantages and disadvantages 33 I/O considerations command processors sharing files, PL/I and C 57 steps for implementing 34 writing files, multiple programs 57 critical programs 37 initial parameters debugging in non-preinitialized environments CMDBUF 49 PL/I 57 HLBPTR 49 PL/I V2R3M0 57 ORIGBLCK 49 DEFAULT keyword of HLLENV command 38 installation exits, performance considerations 12 defining 37 interfaces 49 examples 41 link-editing 43 HLL definition facilities 35 requesting data 88 HLL runtime options 38, 40 restrictions 49 HLLENV command 36 running 45 interface modules 36 runtime errors HLL programs NetView 57 restrictions 116 operating system 57 input/output considerations 57 sending data 89 installation exits translating code points 91 steps for implementing 34 PL/I runtime considerations 57 PL/I PL/I samples runtime options automatically set 50 PACTLU (CNMS4218) 274 PL/I program 49 PACTPIP (CNMS4305) 67, 277 PL/I runtime options PAUTOTB (CNMS4231) 275 entry points 50 PCNMI(CNMS4214) 273 specifying 50 PDOVSAM (CNMS4223) 14, 275 programs 37 PEXIT2A (CNMS4213) 13, 273 REGENVS and CRITENVS keywords 37 PEXIT3 (CNMS4210) 13, 272 restrictions 58 PFLVIEW (CNMS4217) 274 storage keywords 37 PHREGSTR (CNMS4236) 276 storage values for 51 PHSNDMU (CNMS4226) 275 primary POI task (PPT) 65, 71, 123 PKEYIO (CNMS4215) 273 printf function 111, 115 PPRIME (CNMS4224) 14, 275 process ID 220 PPRSMDBN (CNMS4239) 276 PRODMCON (CNMS4230) PL/I sample 275 PREGSTR (CNMS4232) 276 profile name (function) 18 PRODMCON (CNMS4230) 275 program, defining cancelable, non-cancelable 39 PSCOPCK (CNMS4216) 274 PRTY, CNMGETA attribute 203 PSENDMU (CNMS4233) 276 PSCOPCK (CNMS4216) PL/I sample 274 PSEQLOG (CNMS4219) 274 PSENDMU (CNMS4233) PL/I sample 276 PSNDDAT (CNMS4211) 13, 272 PSEQLOG (CNMS4219) PL/I sample 274 PSNDDST (CNMS4222) 275 PSNDDAT (CNMS4211) PL/I sample 13, 272 PTMPPLT (CNMS4200) 272 PSNDDST (CNMS4222) PL/I sample 275 PWATDAT (CNMS4212) 13, 273 PTMPPLT (CNMS4200) PL/I sample 272 PXITDI (CNMS4220) 14, 274 publications PXITVN (CNMS4221) 14, 274 accessing online xvi table of 271 NetView for z/OS xiii PLIOPTS PL/I runtime variable 170 ordering xvi PLIRETC, avoiding 58 PUT statement 57 PLIRETV, avoiding 58 putchar routine 114, 115 POI (program operator interface) PWATDAT (CNMS4212) PL/I sample 13, 273 DSIEX05 16 PXITDI (CNMS4220) PL/I sample 14, 274 DSIEX11 17 PXITVN (CNMS4221) PL/I sample 14, 274 pointer variables using with C programs 106 using with PL/I programs 52 Q post-message automation table exit 20 QUEUE command 178 PPASS keyword 29 queued input, HLL program 38 PPRIME (CNMS4224) PL/I sample 14, 275 PPRSMDBN (CNMS4239) PL/I sample 276 PPT (primary POI task) 13, 251 pragma variable 103 R PREGSTR (CNMS4232) PL/I sample 276 RECFMS 22 preinitialized environment RECMS 22 runtime options registering applications C programs 104, 105 high-performance transport preinitialized environments 33 C example 159

Index 301 registering applications (continued) RID (continued) high-performance transport (continued) description 167, 169 description 208 END 168 high-performance-transport MODNAME 168 PL/I example 94 OPTION 168 MS transport RUN 168 C example 158 STEP 168 description 241 ROUTCODE, CNMGETA attribute 203 PL/I example 92 ROUTE-INOP request 22 operations management RTM 6 C example 158 RU formats 22 PL/I example 92 runtime options regular command 15 default values 38 Remote NetView Bridge 8 specifying, HLLOPTS 38 remote systems, operating 6 replace messages 12 reply identifier 203 S reply RU 189 s type specifier 248 replycmd operand 215 sccmd operand 249 REPLYID, CNMGETA attribute 203 schedule commands under the DST 29 REPORT option 104 sckwd operand 249 request handling 3 SCNMMAC1 data set 269, 279 requesting data scvalue operand 249 C example 154 SDDNM keyword 29 PL/I example 88 sending alerts RESET command 179, 223 high-performance transport resetting and terminating HLL program 39 C example 161 response handling 3 PL/I example 96 restrictions MS transport C program 115 C example 160 PL/I program 58 PL/I example 95 RETCODE exit value 171 sending an MDB to NetView retrieving information C example 162 C example 129 PL/I example 97 PL/I example 69 sending commands return codes C example 123 C 115 PL/I example 65 composite sending data major and minor 173 C example 156 resolving 173 PL/I example 89 description 12 sending messages passed by installation exits 12 C example 122 passed in C HLBRC field 12 description 251 passed in PL/I HLBRC field 12 PL/I example 61 PL/I 58 serial number of screen update 223 simple 173 serialize access 229 USERASIS 12 service xvii USERDROP 11, 12 service management connect xvii USEREVNT 24 service routines, limitations, installation exits 11 USEREXLG 24 SESSID, CNMGETA attribute 203 USERHCL 16 signal function 114 USERHCLR 16 simulated terminal input 15 USERLOG 16 single line message 252 USERLOGR 16 SMC xvii USERNSL 16 smdestid operand 251 USERNSLR 16 smdestyp operand 251 USERSWAP 12 SMF 8 REXX language 264 smmsgtyp operand 220, 252 rgappl operand 242 SMSGID, CNMGETA attribute 203 rgcmd operand 243 smtext operand 252 rgfocpt operand 243 solicited VTAM messages 13, 16 rgfpcat operand 243 source operand 237 rgrepl operand 244 SPASS keyword 29 rgtype operand 244 spclass operand 238 RH header 189 spfunc operand 108, 238 RID SPIE runtime option CONTINUE 167 C program 103, 114

302 Programming: PL/I and C spleng operand 238 system symbolic substitution spname operand 238 access 5 sppricnt operand 238 spseccnt operand 238 sptoken operand 238 T srcptr pointer variable 106 TAF session ID 203 sscanf function 103 TARGET side 89 SSCANF function 63 TASK 220 sslen 261 task global sssource 262 command list variable 5 sstarget 262 description 70, 130, 264 sstype 262 pool 265 STAE runtime option variable 86, 152 C program 103, 114 TASKNAME 220 STARTIME 220 tasks 18 STCK instruction 218, 221 testing and debugging 167 stdin 114 TIBUFLD operand 223 stdout 114 TIME 220 storage timeout operand 215 copy 7 Tivoli named 7 training, technical xvii overlay 194, 218 user groups xvii pool Tivoli Software Information Center xvi ALLOC 237 token 186, 232 FREE 237 training, Tivoli technical xvii LOCATE 237 translating code points restriction 7 C example 158 storage access PL/I example 91 C example 143 transports PL/I example 79 between MVS NetView and non-NetView database 8 storage, managing 7 high performance 6 string 248 LU 6.2 6 substitute system symbolics 261 management services (MS) 6 sucorrar operand 255 TRAP command 66, 125, 182 sudata operand 255 TRAP(OFF) runtime option sudstapl operand 255 C program 114 sudstlu operand 256 PL/I 57 sudstnet operand 256 TRAP(ON) runtime option sudtype operand 256 C program 114 sumutype operand 257 PL/I 57 suoappl operand 257 trapping messages 4 SUPPCHAR 220 TRAPQ access queue 61, 121, 206 support xvii trcode operand 192 surplcmd operand 258 trdata operand 192 susupcor operand 258 trdatlen operand 192 susynch operand 258 trtable operand 192 sutimout operand 258 TSO 113 synchronous commands TVBUFLD operand 223 invoking, C 123 typeface conventions xviii invoking, PL/I 65 running 3 synchvalue operand 215 synonym, command 17 U SYSCONID, CNMGETA attribute 203 u type specifier 248 SYSID, CNMGETA attribute 204 unattended operator task 18 SYSIN, NetView 57 unsolicited VTAM messages 13, 17 SYSPLEX user groups CNMINFC service routine attribute 220 NetView, on Yahoo xviii identifying command list source 220 Tivoli xvii identifying message source 200 user-defined lock, managing 7 SYSPRINT, NetView 57 user-defined services 29 system USERASIS return code 12 message flags 198 USERDROP return code 11, 12 message type 202 USEREVNT return code 24 system ABEND 57, 114 USEREXLG return code 24 system console 251 USERHCL return code 16 USERHCLR return code 16

Index 303 USERLOG return code 16 waiting and trapping USERLOGR return code 16 C example 125 USERNSL return code 16 C example using PIPE 127 USERNSLR return code 16 PL/I example 66 USERSWAP return code 12 PL/I example using PIPE 67

V X value authorization checking 249 x type specifier 248 variables (command list language) XITBN installation exit 13, 21 &HDRMTYPE 207 XITBO installation exit 13, 22 &LINETYPE 207 XITCI installation exit 14, 22 &MSGID 207 XITCO installation exit 14, 24 &MSGORIGIN 207 XITDI installation exit 14, 25 access 5 XITVI installation exit 14, 25 variables, global 176 XITVI keyword 29 variables, notation for xix XITVN installation exit 14, 25 VARTOVAR constant 106 XITVN keyword 29 varying length character string XITVO installation exit 14, 26 Cnmnvlc 120 XITVO keyword 29 Cnmvlc 119 XITXL installation exit 14, 26 copying null-terminated text into 119 description 108, 119 verify operator authorization 16 Y VIEW command 73 Yahoo user group, NetView xviii VIEW command processor C example 136 description 4 PL/I example 73 Z virtual storage, managing 7 z/OS Language Environment libraries 50 VOST 220 VSAM access C example 149 PL/I example 83 data set 26 database 25 DST installation 27 empty file 14, 25 files 5, 229 I/O 25, 26, 149 input 14, 25 keyed file access 149 open failure 25 output 14, 26 services 29 vsdata operand 227 vsdatlen operand 227 vsfunc operand 228 vskey operand 228 vsoption operand 228 vstring operand 111, 112 VT 220 VTAM 220 command invocation 13, 16 component ID 221 level 220 messages, changing 16 VTCOMPID 221

W WAIT avoiding 58 command 182 data 57, 87, 153

304 Programming: PL/I and C

IBM®

Printed in USA

SC27-2860-01