IBM Tivoli NetView for z/OS Version 6 Release 2 Programming: PL/I and C 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 © Copyright IBM Corp. 1997, 2013 iii Debugging support ................................. 8 Remote Interactive Debugger (RID) ........................... 8 First Failure Data Capture Trace (FFDCT)......................... 9 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