IBM Tivoli NetView for z/OS Version 6 Release 1 Programming: Assembler SC27-2858-00 IBM Tivoli NetView for z/OS Version 6 Release 1 Programming: Assembler SC27-2858-00 Note Before using this information and the product it supports, read the information in “Notices” on page 293. This edition applies to version 6, release 1 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. © Copyright IBM Corporation 1997, 2011. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Figures ....................................ix About this publication .............................xi Intended audience .................................xi Publications ...................................xi IBM Tivoli NetView for z/OS library ..........................xi Related publications ...............................xiii Accessing terminology online ............................xiii Using NetView for z/OS online help .........................xiv Using LookAt to look up message explanations ......................xiv Accessing publications online ............................xv Ordering publications ...............................xv Accessibility ...................................xv Tivoli technical training ...............................xv Tivoli user groups .................................xvi Downloads ...................................xvi Support information ................................xvi Conventions used in this publication ..........................xvii Typeface conventions ..............................xvii Operating system-dependent variables and paths .....................xvii Syntax diagrams ................................xviii Part 1. Writing in Assembler Language.....................1 Chapter 1. Getting Started ............................3 The Benefits of Using Assembler Language .........................3 Testing Your Program ................................3 Chapter 2. Designing Assembler Modules .....................5 Task Structure ...................................5 General Coding Guidelines ..............................6 Processing Environment ..............................6 Coding Requirements ...............................7 Control Blocks ...................................9 Control Block Requirements .............................9 Establishing Addressability .............................11 Work Block Services ................................11 Basic Module Services ................................11 Standard NetView Buffer Structure ..........................11 Dynamic Storage Services..............................11 Releasing Queued Storage .............................12 Message Processing................................12 Calling Commands ................................16 Scheduling Commands in a Cross-Domain Environment ...................19 Additional Services .................................20 Loading and Deleting Modules in Virtual Storage .....................20 Posting and Waiting on Event Control Block (ECB) Services ..................20 Disk Services ..................................20 Parsing ....................................21 Command Authorization Checking ..........................21 Named Storage .................................21 Sending and Receiving Data Using the MS Transport ....................22 Sending and Receiving Data Using the High-Performance Transport ...............22 Passing an MSU through the NetView Automation Table ...................23 © Copyright IBM Corp. 1997, 2011 iii Numeric Code Point Translation ...........................23 Specifying Tokens in Alert Automation .........................23 Returning a Command to an Originating Domain .....................23 Resource Span Checking ..............................23 Data Services Task (DST) Unique Services ........................24 Chapter 3. Writing Installation Exit Routines ...................25 Overview of Installation Exit Routines ..........................25 Designing and Coding an Installation Exit Routine ......................27 Input ....................................27 Output ....................................27 Control Blocks .................................30 Summary of Installation Exits ............................31 Unused Installation Exits ..............................60 Installing an Installation Exit Routine...........................60 Template for an Installation Exit Routine .........................60 Chapter 4. Writing Command Processors .....................61 Overview of Command Processors ...........................61 Regular Command Processors ............................61 High-Priority Command Processors ..........................61 Immediate Command Processors ...........................61 Data Services Command Processors ..........................62 Combination Command Processors ..........................62 Long-Running Command Processors ..........................62 Unattended and Attended Operator Task Command Considerations ...............62 Designing and Coding a Command Processor ........................63 Input to the Command Processor ...........................63 Output from the Command Processor .........................64 Control Blocks .................................65 Writing a Full-Screen Command Processor ........................67 Writing a Long-Running Command Processor .......................70 Automation Task Command Processors ..........................78 Installing a Command Processor ............................78 Template for a Command Processor ...........................78 Chapter 5. Writing User Subtasks ........................81 Types of User Subtasks ...............................81 Optional Subtask Processing Overview ..........................81 Installation of User Subtasks.............................82 Initialization of the OPT ..............................83 TVBMEMNM Field ................................84 Processing ...................................84 Termination ..................................87 Additional Considerations .............................88 Data Services Task (DST) ...............................88 Installation of a DST ...............................89 Initialization of a DST ...............................89 Data Services Command Processor ..........................90 CNM Data Services................................90 VSAM Service Interface ..............................93 Example of DSCP Design..............................95 User-Defined Services ...............................98 Chapter 6. Writing User Function Directories ...................99 Overview of User-Written Functions ...........................99 Interface to Functions ...............................100 Entry Specifications ...............................100 External Function Parameter List ...........................100 Argument List .................................101 iv Programming: Assembler Evaluation Block ................................101 Directory for Function Packages ............................102 Format of the Entry in the Directory..........................103 Example of a User Function Directory .........................104 Part 2. Reference ..............................105 Chapter 7. Control Blocks ...........................107 BUFHDR: Buffer Header ..............................107 Values for HDRIND Fields .............................110 Values for HDRMTYPE Fields ............................110 BUFHDR Presentation Extension ...........................113 Example Scenario of BUFHDR Usage .........................115 DSIAIFRO: Automation Vector Extensions .........................115 Modifications of the AIFR Format ..........................115 Format of the Message Control Object .........................116 Format of the Source Object ............................118 DSICBH: Control Block Header ............................118 DSICWB: Command Work Block ............................119 DSIDSB: Data Services Block .............................120 DSIDSRB: Data Services Request Block ..........................121 DSIDTR: Data Transport Request ............................123 DSIELB: External Logging Block ............................123 DSIIFR: Internal Function Request ...........................123 AIFR–Automation Internal Function Request .......................124 Automation Internal Function Request Routing List ....................139 DSILOGDS: NetView Log ..............................140 DSIMVT: Main Vector Table .............................140 MVTAIDFT–DSIEX16 Interface Data..........................143 DSIPDB: Parse Descriptor Block ............................144 DSISCE: System Command Entry ...........................145 DSISCT: System Command Table ............................146 DSISVL: Service Routine Vector List ...........................146 DSISWB: Service Work Block .............................146 DSITECBR: Branch Table of ECB Processor Load Modules ...................147 DSITIB: Task Information Block ............................147 DSITVB: Task Vector Block ..............................149 DSIUSE: Installation Exit Parameter List .........................153 DSIXRCMD: RUNCMD Installation Exit Buffer .......................156 Chapter 8. Macros ..............................157 DSIAUTO: Invoke Automation Services .........................157 Return Codes in Register 15 ............................158 DSIBAM: Build Automation Message