IBM Tivoli NetView for z/OS

Version 6 Release 2 Modification 1

Programming: Assembler

IBM

SC27-2858-03
IBM Tivoli NetView for z/OS
Version 6 Release 2 Modification 1

Programming: Assembler

IBM

SC27-2858-03
 Note
Before using this information and the product it supports, read the information in “Notices” on page 295.

This edition applies to version 6, release 2, modification 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.
This edition replaces SC27-2858-02.
© Copyright IBM Corporation 1997, 2015.
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
Accessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Ordering publications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Service Management Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Tivoli technical training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Tivoli user groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Downloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Support information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Conventions used in this publication . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Revision codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Operating system-dependent variables and paths . . . . . . . . . . . . . . . . . . . . . xvii
Syntax diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Chapter 1. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Benefits of Using Assembler Language. . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Testing Your Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 2. Designing Assembler Modules . . . . . . . . . . . . . . . . . . . . . 3

Task Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
General Coding Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Processing Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Coding Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Control Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Control Block Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Establishing Addressability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Work Block Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Basic Module Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Standard NetView Buffer Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Dynamic Storage Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Releasing Queued Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Message Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Calling Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Scheduling Commands in a Cross-Domain Environment . . . . . . . . . . . . . . . . . . . 17
Additional Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Loading and Deleting Modules in Virtual Storage . . . . . . . . . . . . . . . . . . . . . 18
Posting and Waiting on Event Control Block (ECB) Services . . . . . . . . . . . . . . . . . . 18
Disk Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Command Authorization Checking . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Named Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Sending and Receiving Data Using the MS Transport . . . . . . . . . . . . . . . . . . . . 20
Sending and Receiving Data Using the High-Performance Transport . . . . . . . . . . . . . . . 21
Passing an MSU through the NetView Automation Table . . . . . . . . . . . . . . . . . . . 21
Numeric Code Point Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Specifying Tokens in Alert Automation . . . . . . . . . . . . . . . . . . . . . . . . . 21

© Copyright IBM Corp. 1997, 2015 iii

 Returning a Command to an Originating Domain . . . . . . . . . . . . . . . . . . . . . 21
Resource Span Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Data Services Task (DST) Unique Services . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 3. Writing Installation Exit Routines . . . . . . . . . . . . . . . . . . . 23

Overview of Installation Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Designing and Coding an Installation Exit Routine . . . . . . . . . . . . . . . . . . . . . . 25
Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Control Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Summary of Installation Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Unused Installation Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Installing an Installation Exit Routine. . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Template for an Installation Exit Routine . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 4. Writing Command Processors . . . . . . . . . . . . . . . . . . . . . 59

Types of Command Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Regular Command Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
High-Priority Command Processors . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Immediate Command Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Data Services Command Processors . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Combination Command Processors . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Long-Running Command Processors . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Unattended and Attended Operator Task Command Considerations . . . . . . . . . . . . . . . 61
Designing and Coding a Command Processor . . . . . . . . . . . . . . . . . . . . . . . . 61
Input to the Command Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Output from the Command Processor . . . . . . . . . . . . . . . . . . . . . . . . . 62
Control Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Writing a Full-Screen Command Processor . . . . . . . . . . . . . . . . . . . . . . . . 65
Writing a Long-Running Command Processor . . . . . . . . . . . . . . . . . . . . . . . 68
Automation Task Command Processors . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Installing a Command Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Template for a Command Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Chapter 5. Writing User Subtasks . . . . . . . . . . . . . . . . . . . . . . . . 79

Types of User Subtasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Optional Subtask Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Installation of User Subtasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Initialization of the OPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
TVBMEMNM Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Terminating the OPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Additional Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Data Services Task (DST) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Installation of a DST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Initialization of a DST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Data Services Command Processor . . . . . . . . . . . . . . . . . . . . . . . . . . 88
CNM Data Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
VSAM Service Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Example of DSCP Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
User-Defined Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Chapter 6. Writing User Function Directories . . . . . . . . . . . . . . . . . . . 97

Overview of User-Written Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Interface to Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Entry Specifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
External Function Parameter List . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Argument List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Evaluation Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Directory for Function Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

iv Programming: Assembler
 Format of the Entry in the Directory. . . . . . . . . . . . . . . . . . . . . . . . . . 101
Example of a User Function Directory . . . . . . . . . . . . . . . . . . . . . . . . . 102

Chapter 7. Control Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

BUFHDR: Buffer Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Values for HDRIND Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Values for HDRMTYPE Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
BUFHDR Presentation Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Example Scenario of BUFHDR Usage . . . . . . . . . . . . . . . . . . . . . . . . . 111
DSIAIFRO: Automation Vector Extensions . . . . . . . . . . . . . . . . . . . . . . . . . 111
Modifications of the AIFR Format . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Format of the Message Control Object . . . . . . . . . . . . . . . . . . . . . . . . . 113
Format of the Source Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
DSICBH: Control Block Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
DSICWB: Command Work Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
DSIDSB: Data Services Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
DSIDSRB: Data Services Request Block . . . . . . . . . . . . . . . . . . . . . . . . . . 118
DSIDTR: Data Transport Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
DSIELB: External Logging Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
DSIIFR: Internal Function Request . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
AIFR–Automation Internal Function Request . . . . . . . . . . . . . . . . . . . . . . . 121
Automation Internal Function Request Routing List . . . . . . . . . . . . . . . . . . . . 137
DSILOGDS: NetView Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
DSIMVT: Main Vector Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
DSIPDB: Parse Descriptor Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
DSISCE: System Command Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
DSISCT: System Command Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
DSISVL: Service Routine Vector List . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
DSISWB: Service Work Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
DSITECBR: Branch Table of ECB Processor Load Modules . . . . . . . . . . . . . . . . . . . 145
DSITIB: Task Information Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
DSITVB: Task Vector Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
DSIUSE: Installation Exit Parameter List . . . . . . . . . . . . . . . . . . . . . . . . . 151
DSIXRCMD: RUNCMD Installation Exit Buffer . . . . . . . . . . . . . . . . . . . . . . . 154

Chapter 8. Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

DSIAUTO: Invoke Automation Services . . . . . . . . . . . . . . . . . . . . . . . . . 155
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
DSIBAM: Build Automation Message . . . . . . . . . . . . . . . . . . . . . . . . . . 156
DSIBAMKW: Build Automation Message Keyword . . . . . . . . . . . . . . . . . . . . . . 158
DSICBS: Control Block Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
DSICES: Command Entry Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
DSICVTHE: Convert to Hexadecimal . . . . . . . . . . . . . . . . . . . . . . . . . . 163
DSIC2T: Code Point Translation Service Reference . . . . . . . . . . . . . . . . . . . . . . 163
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
DSIDATIM: Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
DSIDEL: Delete User-Defined Module . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
DSIDKS: Disk Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
DSIFIND: Find Long-Running Command Storage . . . . . . . . . . . . . . . . . . . . . . 170
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
DSIFRE: Free Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
DSIFREBS: Call DSIFREBS Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
DSIGET: Get Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
DSIGETDS: Data Queue Manipulation Service . . . . . . . . . . . . . . . . . . . . . . . 177
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Contents v
DSIHREGS: High-Performance Transport Application Registration. . . . . . . . . . . . . . . . . 179
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
DSIHSNDS: Send High-Performance Message Unit . . . . . . . . . . . . . . . . . . . . . . 183
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
DSIID: Store SYSMOD Level in CSECT . . . . . . . . . . . . . . . . . . . . . . . . . . 190
DSIKVS: Keyword/Value Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
DSILCS: Obtain/Release Control Blocks . . . . . . . . . . . . . . . . . . . . . . . . . 192
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
DSILOD: Load User-Defined Module . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
DSIMBS: Message Build Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
DSIMDS: Message Definition Services . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Defining Messages on Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
User Message Definition Module Examples . . . . . . . . . . . . . . . . . . . . . . . 202
DSIMMDBS: Call DSIMMDB Service . . . . . . . . . . . . . . . . . . . . . . . . . . 202
DSIMQS: Message Queuing Services . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Return Codes in Register 0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
DSINOR: Resource Object Data Manager . . . . . . . . . . . . . . . . . . . . . . . . . 208
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
DSIPAS: Parameter Alias Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
DSIPOP: Remove Long-Running Command . . . . . . . . . . . . . . . . . . . . . . . . 211
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
DSIPOS: ECB Post Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
DSIPRS: Parsing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Parsing Services Module Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 216
DSIPSS: Presentation Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
DSIPUSH: Establish Long-Running Command . . . . . . . . . . . . . . . . . . . . . . . 223
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
DSIQOS: Query Operator Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
DSIQRS: Query Resource Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
MNOTES Issued . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
DSIRDS: Resource Definition Services . . . . . . . . . . . . . . . . . . . . . . . . . . 232
DSIRXEBS: Get an EVALBLOK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
DSISRCMV: Search for Subvector or Subfield . . . . . . . . . . . . . . . . . . . . . . . . 233
DSISYS: Operating System Indicator. . . . . . . . . . . . . . . . . . . . . . . . . . . 235
DSITECBS: Manage a Dynamic ECB List for DSTs . . . . . . . . . . . . . . . . . . . . . . 235
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
DSIVARS: Variable Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
DSIWAT: ECB Wait Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
DSIWCS: Write Console Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Return Code in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
DSIWLS: Write Log Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
DSIZCSMS: CNM Data Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Minor Return Codes in Register 0 . . . . . . . . . . . . . . . . . . . . . . . . . . 248
CNM Data Services Module Examples . . . . . . . . . . . . . . . . . . . . . . . . . 248
DSIZVSMS: VSAM Data Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Minor Return Codes in Register 0 . . . . . . . . . . . . . . . . . . . . . . . . . . 251
DSI6REGS: LU 6.2 Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

vi Programming: Assembler
 Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
DSI6SNDS: Send a Message Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Return Codes in Register 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Chapter 9. Called Service Routines . . . . . . . . . . . . . . . . . . . . . . . 267

Overview of Called Service Routines . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Free NetView Buffers Service Routine (DSIFREBF) . . . . . . . . . . . . . . . . . . . . . . 267
Return Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Abend Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Process Message Data Block Routine (DSIMMDB) . . . . . . . . . . . . . . . . . . . . . . 268
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Appendix A. Assembler Samples . . . . . . . . . . . . . . . . . . . . . . . . 271

Assembler Samples Reference Table . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Assembler Samples Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Appendix B. MDB Field to AIFR Cross-Reference Table . . . . . . . . . . . . . . 279

Appendix C. Writing an Automation Table Function . . . . . . . . . . . . . . . . 287

Overview of Automation Table Function . . . . . . . . . . . . . . . . . . . . . . . . . 287
Designing and Coding an ATF Module . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Input to and Output from the ATF . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Control Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Installing an ATF module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Points to Remember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Appendix D. Assembler Macros and HLL Service Routine Interfaces . . . . . . . . 293

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Programming Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Privacy policy considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Contents vii
viii Programming: Assembler
Figures
1. Overview of Control Block Interconnections for User-Written Programming . . . . . . . . . . . . 8
2. Using Macros to Communicate from an OST . . . . . . . . . . . . . . . . . . . . . . 11
3. Example of Title-Line Output . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4. DSIEX02A, DSIEX16, DSIEX16B, and DSIEX17 Interface . . . . . . . . . . . . . . . . . . . 42
5. Automation Internal Function Request . . . . . . . . . . . . . . . . . . . . . . . . 62
6. Example of Control Blocks Used by Command Processors . . . . . . . . . . . . . . . . . . 64
7. Sample Code to Access a Command Buffer . . . . . . . . . . . . . . . . . . . . . . . 65
8. Subtask Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9. Structure of a Data Services Command Processor . . . . . . . . . . . . . . . . . . . . . 94
10. Example of Program Design for Data Services Requests . . . . . . . . . . . . . . . . . . . 95
11. Example of a Function Package Directory . . . . . . . . . . . . . . . . . . . . . . . 102
12. Buffer Header (BUFHDR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
13. DSIAIFRO Chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
14. Example of an AIFR Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
15. Source Object Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
16. Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
17. Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
18. Control Blocks Used by ATF Modules . . . . . . . . . . . . . . . . . . . . . . . . 290

© Copyright IBM Corp. 1997, 2015 ix

x Programming: Assembler
About this publication
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: Assembler, describes the
ways that you can tailor or supplement the NetView program to satisfy unique
requirements or operating procedures. It describes the uses and advantages of
user-written programs (exit routines, command processors, and subtasks). It
provides instructions that guide the programmer through the mechanics of
designing, writing, and installing these programs.

Intended audience
This publication is for system programmers who are knowledgeable about
assembler language and familiar with the functions provided by the NetView
program. This publication is also useful for 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 NetView Enterprise Management Agent, GC27-2853,
describes how to install and configure the NetView for z/OS Enterprise
Management Agent.
v Installation: Getting Started, GI11-9443, describes how to install and configure the
base NetView program.

© Copyright IBM Corp. 1997, 2015 xi

 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.
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.

xii Programming: Assembler

 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.

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 modification 1
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
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:

About this publication xiii

 v IBM Tivoli Netcool/OMNIbus
v IBM Tivoli OMNIbus and Network Manager
GDPS® Metro HyperSwap® Manager
For all the NetView for z/OS V6.2.1 books, NetView Monitoring for GDPS
V6.2.1 book, and IBM Tivoli System Automation for GDPS/PPRC
HyperSwap Manager with NetView book.

Note: The former name of GDPS Metro HyperSwap Manager is

GDPS/PPRC HyperSwap Manager.
GDPS Continuous Availability
For all the NetView for z/OS V6.2.1 books, NetView Monitoring for GDPS
V6.2.1 book, and IBM Tivoli System Automation for GDPS/PPRC
HyperSwap Manager with NetView book.

Note: The former name of GDPS Continuous Availability is

GDPS/Active-Active.

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

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

xiv Programming: Assembler

 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.
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, 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

About this publication xv

 After you open the Support Portal page, perform the following steps:
1. Scroll down to the Downloads section and click the view all link.
2. On the Downloads for NetView for z/OS page, check the Tool/Utility box in
the Filter by topic section on the left side.
3. Download the items based on your requirements.

These applications can help with the following tasks:

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.

xvi Programming: Assembler

Revision codes
This publication uses the following revision codes, which are located in the left
margins:
| The pipe character | is used to indicate changes made for the December,
2014 modifications to the document.

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:)
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.

About this publication xvii

 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”
v “Punctuation and parentheses”
v “Abbreviations” on page xix
For examples of syntax, see “Syntax examples” on page xix.

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.

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.

xviii Programming: Assembler

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 xx.

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.

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” on page xx
v “Multiple operands or values” on page xx
v “Syntax that is longer than one line” on page xx
v “Syntax fragments” on page xx

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.

About this publication xix

 ►► ►◄
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.

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.

xx Programming: Assembler
►► COMMAND_NAME Fragment1 ►◄
Fragment2

Fragment1

KEYWORD_A=valueA KEYWORD_B KEYWORD_C

Fragment2

KEYWORD_D KEYWORD_E=valueE KEYWORD_F

About this publication xxi

xxii Programming: Assembler
Chapter 1. Getting Started
With Tivoli NetView for z/OS, you can manage complex, multivendor networks
and systems from a single point. Before reading this chapter, refer to the
information about NetView customization facilities and designing user-written
functions in the IBM Tivoli NetView for z/OS Customization Guide.

If you write assembler language subroutines for your high-level language

command processors, be aware of the requirements and environments of command
processors at the assembler level.

Benefits of Using Assembler Language

Although coding in assembler language requires more effort, this language has
greater flexibility than other supported languages. The advantages of assembler
language include:
v Display flexibility. Although full-screen display support is provided to all
languages through the VIEW command, you can take advantage of special
features of your workstation, such as wide screens or cursor-dependent
functions. By writing in assembler language, you gain direct access to the 3270
data-stream commands.
v Special data handling. The following are an example:
– Reentrant updates to a global data structure
– Complex functions at operator logoff or abend-reinstatement
v Privileged functions. Access to all system functions and macros.
v Interaction with other commands. You can examine the status of, or wait on,
asynchronous events other than the standard set that the VIEW command
provides. These include timed events or completion of commands under another
task.
v Performance. While supported high-level language routines usually run faster
than interpreted command lists, some types of data manipulation are faster with
assembler language.

Testing Your Program

Before putting your program into production, develop test scenarios for the major
functions. Use the NetView trace facility when testing to analyze errors or abends
that the code generates. The format of the TRACE command is found in the
NetView online help. Running a trace is particularly helpful for verifying input to
installation exit routines, DSIPSS, and DSIMQS. A trace also verifies that your
storage is balanced, that is, all the storage your code gets (using DSIGET) is also
freed by your code (using DSIFRE).

When testing new command processors, use RES=N in the CMDDEF definition
statement to replace the object code without recycling the NetView program. You
can use the ADDCMD and DELCMD commands to dynamically add or delete
command definitions.

To avoid possible conflict between your code and NetView services currently in
use, consider running the code on a separate NetView program in a test
environment, or during a time of day when the NetView program is not used

© Copyright IBM Corp. 1997, 2015 1

Application Program Interfaces

heavily. To test code, you must restart the NetView program, except for predefined
nonresident command processors. If there is little risk of conflict, you can simply
add code to the NetView production library currently in use.

When the test system is running, perform the test scenarios and verify that the
results and output of your code are correct. If they are correct, put the code into
production and begin using it normally.

Note: For information on methods of testing automation, refer to IBM Tivoli

NetView for z/OS Automation Guide.

2 Programming: Assembler
Chapter 2. Designing Assembler Modules
This section reviews NetView services available for user-coded command
processors, installation exits, and user subtasks. See Chapter 8, “Macros,” on page
155 for more information about the NetView service macros described in this
chapter. See Appendix A, “Assembler Samples,” on page 271 for assembler coding
samples using these macros.

Most NetView service macros can be used only under tasks attached by the
NetView program using facilities such as the START, AUTOTASK, and ATTACH
commands. If you attach a subtask by other means, such as by using the MVS
attach macros or the REXX ADDRESS ATTCHPGM, then the programs running on
the attached task cannot use any NetView service requiring a Service Work Block
(SWB) or a Task Vector Block (TVB). Two NetView service macros that are available
under any subtask in the NetView address space are Control Block Services
(DSICBS) and the Locate Control Block Service (DSILCS). For all NetView service
macros requiring an SWB, the SWBTIB field must contain the address of the
DSITIB control block dedicated to the particular task (TCB) at the time the
NetView program performed the attach. Note that this control block contains a
pointer (TIBTVB) to the TVB that governs operation of the subtask. In all cases
where the NetView program calls assembler customization, a reference to the TVB
or TIB is provided:
v USERTVB for user exits; see “DSIUSE: Installation Exit Parameter List” on page
151 for additional information about user exits.
v CWBTIB for commands; see “DSICWB: Command Work Block” on page 116 for
additional information about commands.
v Register 1 (TVB) for optional tasks.

Task Structure
The NetView task environment consists of a main task (MNT) and six types of
subtasks.

The main task initializes the NetView program. It provides an environment for the
subtasks and oversees their creation and cleanup. The main task also provides
limited installation exits that can be used to modify processing under the main
task.

The following list shows the subtasks:

v Operator station task (OST)
An operator uses an operator station task to enter commands and receive
messages. An OST is started for each operator at logon.
An OST is also started for each automated operator (autotask). Autotasks are
independent of VTAM and terminals. Only line-mode commands (no full-screen
commands) can be run by autotasks, which are started with the AUTOTASK
command and the RMTCMD command.
A VOST (virtual OST) is similar to an autotask, except that in addition to being
independent of VTAM and terminals, it is used for full-screen automation.
v NetView-NetView task (NNT)

© Copyright IBM Corp. 1997, 2015 3

Designing Assembler Modules

With a NetView-NetView task, an operator can access another NetView program,

usually in another domain. With the task, an operator can also send commands
and receive messages from the NetView program. The START DOMAIN
command creates an NNT in the other domain.
v Hardcopy task (HCT)
A hardcopy task logs the activity of one or more OSTs using 328x printers. The
START HCL command starts an HCT.
v Primary program operator interface task (PPT)
The primary program operator interface task, receives unsolicited messages from
VTAM and message traffic exchanged between the system console and VTAM.
The PPT opens a (primary) programmed operator interface to VTAM to receive
these messages. Each NetView program has one PPT. The PPT is started when
the NetView program starts. When more than one NetView program is running
in the same system, the PPT is normally made a secondary POI receiver in all but
one of the NetView versions. Timing is no longer done by the PPT, but is now
done by the DSITIMMT task.
v Optional tasks (OPT)
Optional tasks are user-defined subtasks that can provide increased flexibility
beyond the subtasks that the NetView program provides. For example, you can
use an OPT to provide unique command interfaces or more precise control of
work dispatching than the standard command processors running under a
DST-based task can provide. You can define the OPT to start when the NetView
program starts or when you issue a START TASK command.
v Data services task (DST)
Data services tasks provide command, message, and exit functions. In addition,
DSTs can manage VSAM or communication network management (CNM)
facilities. You can create new subtasks to perform any or all of these functions.
The DST can be started when NetView program starts or when you issue a
START TASK command.
A DST is a subset of an optional task (OPT). If you write code to check the
CBHTYPE of a control block under a DST, you find an X'05', which is an OPT.

For more information about the NetView task structure, see the IBM Tivoli NetView
for z/OS Troubleshooting Guide.

General Coding Guidelines

This section contains some general guidelines to follow when coding in the
NetView program.

Processing Environment
NetView code and user-written code have control in a problem program state. Both
types of code also have control with a user memory protection key. Unless your
system programmers set up special provisions, this is key 8. NetView and all
user-written code given control under the NetView program are authorized. You
have the option of calling privileged system services, entering supervisor state, or
changing the memory protection key. However, return control to the NetView
program in the same program state and memory protection key as when you
entered the user code.

4 Programming: Assembler
 Designing Assembler Modules

Except as noted in Chapter 7, “Control Blocks,” on page 103, all NetView control
blocks are accessible with the user key. Unless Chapter 8, “Macros,” on page 155
specifically notes otherwise, call all NetView services in problem program state and
the user key.

When the NetView program calls user-written code, the TVBINXIT bit can be
tested to determine the environment under which the user-written code is
processing. When a NetView task is initially dispatched, the TVBINXIT bit is off. If
the task calls user-written code at this time, the code processes under the mainline
environment.

When the operating system interrupts mainline processing, the NetView program
sets the TVBINXIT bit on in the DSITVB control block of the processing task. Any
user-written code called at this time is processed under the TVBINXIT=ON
environment.

Each task has unique restrictions that limit the types of user-written code it can
process. Table 1 indicates the types of code that can run under each task in the
mainline environment. The figure also indicates the types of code that can run
when the TVBINXIT bit in the TVB is set on. Because you define the commands
and functions that run under an OPT, that subtask is not included in Table 1.
Table 1. Task Environment for User-Written Programming
Main TVBINXIT
Task OST NNT HCT PPT DST Set On
Installation exit routines v v v v v v
Regular command v v v
processors
Immediate command v v v
processors
Data services command v
processors

Coding Requirements
This section describes the general guidelines to consider when writing your code.
Control blocks and macros in this section are described in more detail in Chapter 7,
“Control Blocks,” on page 103, and in Chapter 8, “Macros,” on page 155.

Limitations When TVBINXIT Is Active

See Table 3 on page 23 to determine the installation exits that must query the
TVBINXIT bit. Do not change the value of TVBINXIT with an installation exit.
When your code receives control with the TVBINXIT bit set to on, the following
limitations apply:
v As a general coding guideline, your installation exits can check the TVBINXIT
bit and return with a return code of 0, if the installation exit is called with
TVBINXIT set to on.
v Do not code your program to cause a system wait state. A system wait can
produce an interlock. For example, if an interruption request block (IRB) exit
waits for a resource being used by the mainline routine, the resource is not
released, because the IRB exit is interrupting the mainline routine.
To avoid causing a system wait state:
– Do not issue the DSIWAT macro.

Chapter 2. Designing Assembler Modules 5

Designing Assembler Modules

– Do not issue the DSIDKS macro or any other disk services macros.
v Only immediate commands can be called directly. Use the DSIMQS macro to run
regular commands. For more information, see “Calling Commands” on page 15.

Names of Variables
Do not use the following prefixes for any variable or message you name in your
code:
v Any NetView component prefix, for example:
AAU BNT EGV EZL FLB
BNH CNM EKG FKB FLC
BNI DSI EUY FKV FMG
BNJ DUI EXQ FKW FNA
BNK DWO EYV FKX IHS
v Any NetView control block suffix, such as SWB or PDB

Macro Use
When a NetView macro and an operating system macro perform equivalent
services, use the NetView macro. This ensures that the source code for your
program can be transported across NetView operating systems. If you use an
operating system macro, be careful that its function does not conflict with a
function the NetView program might be performing. For example, if the operating
system macro STIMER is issued under the DSITIMMT, NetView timer services are
disrupted.

Register Use
Use the following guidelines when using registers for installation exit routines,
command processors, and subtasks:
0–15 Save all registers at entry to the user code, and restore them before
returning control to the NetView program.
0, 2–12
Do not rely on the contents of these registers for constant values as entry
to the user code. Their contents vary.
0, 1, 14, 15
Do not rely on these registers after issuing a NetView macro. These
registers are used during macro expansion.
13 Ensure that this register contains the address of a standard 72-byte save
area.
14 Use this register to specify the location in the NetView program to return
control to.
15 Set this register with your return code when exiting from your program.

Reentrant Code
Ensure that your code is reentrant to enable the one copy of the program to be
used concurrently by more than one task. For example, a command processor can
be called from two or more tasks simultaneously and run simultaneously under
multiple tasks.

Reentrant code is not required for certain installation exits or for optional tasks.
See Table 3 on page 23 for more information.

Addressing and Residency Mode Considerations

The NetView program supports any valid combination of addressing mode
(AMODE) and residency mode (RMODE). The NetView program provides the

6 Programming: Assembler
 Designing Assembler Modules

appropriate services, depending on the current mode of your code. In addition, the
NetView program provides macro parameters where necessary that you can use to
specify 24-bit or 31-bit addressing for your special requirements. (New
called-assembler services require 31-bit addressing, as described in Chapter 9,
“Called Service Routines,” on page 267.) The NetView program also provides
appropriate residency for the control blocks your code accesses, such as USE, CWB,
and BUFHDR. For example, if your command processor is loaded with
AMODE=24, the CWB passed to it resides below 16 megabytes (MB). The Message
Queueing Service (DSIMQS) ensures only that the message buffers are below the
16 MB line if a user-optional task is link-edited with RMODE(24) and AMODE(24).

To conserve storage below the 16 MB line and therefore minimize the resources
needed to copy buffers, use 31-bit residency except when limited by your use of
interfaces.

Control Blocks
Your code must include the necessary control block mappings for the module you
are writing and establish addressability to each of the control blocks. For the
specific information you want written to these modules, see one of the following
chapters:
v Chapter 3, “Writing Installation Exit Routines,” on page 23
v Chapter 4, “Writing Command Processors,” on page 59
v Chapter 5, “Writing User Subtasks,” on page 79

For supported control blocks and corresponding fields, see Chapter 7, “Control
Blocks,” on page 103. Fields not described in that section are not part of the
programming interface.

Control Block Requirements

At source program assembly, include DSECTs for the NetView control blocks that
have fields used by the program. The program uses the following control blocks:
v For installation exit routines, include the installation exit parameter list
(DSIUSE). Because the installation exit parameter list (USE) contains the
addresses of the task vector block (TVB), service work block (SWB), parse
descriptor block (PDB), and buffer header (BUFHDR) (defined with the DSITIB
DSECT), you include these control blocks.

Note: Each TVB addresses an associated task information block (TIB) and the
main vector table (MVT).
v For command processors, include the command work block (CWB). Include
these control blocks because the CWB contains the addresses of an associated
SWB, PDB, and BUFHDR (defined with the TIB DSECT). In addition, data
services command processors (DSCPs) require the data services request block
(DSRB).
v For user subtasks, include the TVB and any other control blocks necessary for
your user-defined task.

Depending on the particular service facilities your program uses, you might need
to include other control blocks.

Figure 1 on page 8 illustrates the interconnections among the control blocks. The
field displacements suggested in this figure are not representative of the field
displacements. The subtasks diagram in this figure shows that for each type of

Chapter 2. Designing Assembler Modules 7

Designing Assembler Modules

user-written code, the TVB provides access to the MVT and to the SVL.

User Exit USE

Routines

BUFHDR
USERMSG SWB

USERSWB TVB SWBTIB

USERTVB

USERPDB TVBTIB
TIB

PDB
TVBMVT
TIBTVB

MVT

Command CWB
Processors

CWBBUF
PDB
CWBPDB
SWB BUFHDR
CWBSWB
TIB PDBBUFA
CWBTIB
SWBTIB PDBCMDA

TIBTVB
SCE

TVB

MVT
TVBTIB

Subtasks TVB TVBMVT

TIB
TVBTIB

MVT
TIBTVB
TVBMVT

MVTSVL

TVBMPUBQ BUFHDR SVL

HDRNEXTM
BUFHDR

Figure 1. Overview of Control Block Interconnections for User-Written Programming

Use the DSICBS macro to include DSECTs for the appropriate control blocks. For
example, you can code the DSICBS macro in a command processor as follows:
DSICBS DSICWB,DSISWB,DSIMVT,DSIPDB,DSITVB,PRINT=NO

8 Programming: Assembler
 Designing Assembler Modules

This instruction includes the CWB, SWB, MVT, PDB, and TVB. This instruction
also specifies, with PRINT=NO, that control block expansions cannot be printed.

Establishing Addressability
Establish addressability to a control block before referencing fields within that
control block. The following example shows how you can establish addressability
to the MVT for a command processor:
USING DSICWB,1
L REG10,CWBTIB
USING DSITIB,REG10
L REG11,TIBTVB
USING DSITVB,REG11
L REG12,TVBMVT
USING DSIMVT,REG12

Work Block Services

You need the service work block (SWB) when your code calls NetView service
facilities. The CWB is used as command processor input. The DSILCS macro
obtains and releases SWBs or CWBs, as shown in the following example:
DSILCS CBADDR=MYSWBPTR,SWB=GET ▌1▐
LTR REG15,REG15 ▌2▐
BNZ ERRORSWB ▌3▐
L REG2,TVBTIB ▌4▐
L REG3,MYSWBPTR ▌4▐
ST
. REG2,SWBTIB-DSISWB(REG3) ▌4▐
.
.
DSILCS CBADDR=MYSWBPTR,SWB=FREE ▌5▐
Key Explanation
▌1▐ This statement obtains an SWB and assigns its address to be placed in
MYSWBPTR.
▌2▐ This statement tests for a good return code in register 15.
▌3▐ This statement branches to the ERRORSWB error routine if the return code
is not 0.
▌4▐ If the macro is successful, these three statements initialize the SWBTIB field
to your TIB address before you use the SWB.
▌5▐ This statement releases the SWB using DSILCS after use.

Basic Module Services

This section contains information about the module services provided with the
NetView program.

Standard NetView Buffer Structure

All message and command buffers require an initialized buffer header (BUFHDR)
structure preceding the message data or command text. BUFHDR is a separate
DSECT contained in the task information block (DSITIB) control block. Use DSICBS
to include DSITIB when your module references BUFHDR fields. Chapter 7,
“Control Blocks,” on page 103, illustrates the structure of a buffer header. Figure 12
on page 104 presents an overview of the BUFHDR fields.

Chapter 2. Designing Assembler Modules 9

Designing Assembler Modules

Dynamic Storage Services

Storage services can be used to get and free storage for your program. Use the
DSIGET macro to get storage and the DSIFRE macro to free storage, as shown in
the following example:
DSIGET LV=4088,A=STORPTR,TASKA=(MYTVBREG),Q=NO
LTR REG15,REG15
BNZ
. ERRORGET
.
.
DSIFRE LV=4088,A=STORPTR,TASKA=(MYTVBREG),Q=NO

The preceding example requests that 4088 bytes of storage be obtained. The
address of the storage is placed in the fullword named STORPTR. The second and
third statements test for a good return code in register 15 before you use the
storage. When the storage is obtained, it is cleared to binary zeros. Except when it
causes a new page to be gotten, DSIGET obtains an additional 8 bytes of storage
that are used by the NetView program to detect storage overlay conditions.

After use, free the storage using the same value for the Q option as you used
previously to get the storage. Also, free non-queued storage; specify the same size
that you specified to get the storage (as shown in the example above where
DSIGET and DSIFRE both specify LV=4088). If you do not specify the same size on
DSIGET and DSIFRE, the NetView program assumes that a storage overlay
condition exists and can cause a memory dump.

Note: Specify the TASKA keyword because it can help you avoid addressing the
wrong TVB. TASKA contains the address of the TVB for the subtask where the
code is running. Use the TASKA parameter for both non-queued (Q=NO) and
queued (Q=YES) storage.

Releasing Queued Storage

You can also use the DSIGET Q=YES option to enable the NetView program to
release queued storage at logoff or task termination, which facilitates error
recovery. The following example illustrates this use:
DSIGET LV=4096,A=STORPTR,TASKA=(MYTVBREG),Q=YES,BNDRY=PAGE
LTR REG15,REG15
BNZ
. ERRORGET
.
.
DSIFRE A=STORPTR,TASKA=(MYTVBREG),Q=YES

In this example, Q=YES indicates that the NetView program tracks the 4096 bytes
of storage in an internal queue. To support this internal queue, Q=YES gets 16
more bytes of storage than requested. (Q=NO gets 8 more bytes of storage than
requested for storage overlay checking.) If you specify BNDRY=PAGE, the extra
bytes are not received, and page alignment is not affected.

Note: The NetView program ignores any storage length indicated by DSIFRE
when you specify Q=YES.

Message Processing
Message processing in the NetView program includes:
v Creating messages
v Displaying messages to operators
v Displaying messages to the console
v Logging messages

10 Programming: Assembler
 Designing Assembler Modules

Figure 2 shows how these macros communicate with the operator. The logging and
system console services are invocations of the DSIWLS and DSIWCS macros. For
more information about the DSIWCS macro, see “DSIWCS: Write Console Services”
on page 242. For more information about the DSIWLS macro, see “DSIWLS: Write
Log Services” on page 242.

Terminal for
this Operator Domain Boundary
Station
DSIPSS TYPE=OUTPUT
IMMED
ASYPANEL

DSIPSS

TYPE=XSEND
DSIWCS NetView Operator
System NetView-to-NetView
Operator's Task (NNT)
Console Operator Station
Task (OST)

DSIPSS
TYPE=OUTPUT
IMMED
DSIWLS DSIMQS

Network Log or
Hardcopy Log
for this
Operator Station

Another Subtask
in this Domain

Figure 2. Using Macros to Communicate from an OST

Creating Messages
The message definition service (DSIMDS) macro provides you with a chance to
create a load module of user-defined message skeletons. Each defined message
skeleton can contain up to nine variable-length text inserts.

The message building service (DSIMBS) macro combines message insert text with
the specified message skeleton and returns a completed message buffer, which can
be used for displaying the message.

For more information about message macros, see the following references:
v The introductory section of Chapter 8, “Macros,” on page 155, for conditions that
apply to all NetView macros
v “DSIMBS: Message Build Services” on page 196, for details on using the DSIMBS
macro
v “DSIMDS: Message Definition Services” on page 198, for details on using the
DSIMDS macro
v The sample library on the product tape for examples of creating user-defined
messages with DSIMDS and DSIMBS

Chapter 2. Designing Assembler Modules 11

Designing Assembler Modules

Displaying Information to NetView Operators

The following list shows the primary channels for presenting information to the
operator:
v The terminal screen using the DSIPSS macro
v The network log, system log, sequential log, and hardcopy log using the
DSIWLS macro

Message presentation using the DSIPSS and DSIMQS macros is more complex. The
DSIPSS macro can present information in any of the following three screen modes.
DSIMQS is limited to standard mode and title-line mode.
Standard Mode
NetView messages are sent to the screen with a user-definable prefix
followed by data. The prefix includes fields such as the NetView message
type (HDRMTYPE), and the NetView domain name (HDRDOMID),
indicating the domain that sent the message. If the message is wider than
the screen, it is split between words. The message is continued on the next
line, and is indented by a user-customized amount.
A variation on standard mode output is the immediate message. It appears
at the bottom of the panel as a single 71 character message with neither
prefix nor continuation lines.
To present a message in standard mode, you can use any of these methods:
v Issue DSIPSS TYPE=OUTPUT
v Issue DSIPSS TYPE=IMMED
v Issue DSIMQS to queue a HDRTYPEU message buffer to the OST
v Issue DSIPSS TYPE=FLASH
Refer to sample ADATTIM (CNMS4274) in CNMSAMP for an example of
standard mode output.
Title-line Mode
Title-line presentation services send sequences of messages to the operator
without allowing other messages to be interspersed. The messages are
displayed on the panel in a tabular format, with one or more title lines.
Title-line messages have no prefix and can use the full width of the panel.
Messages longer than panel width are truncated.
Title-line mode messages and system multiline write-to-operator (MLWTO)
messages are treated as a single message by:
v DSIEX02A, DSIEX16, and &WAIT in NetView command list language
v TRAP and WAIT in REXX and high-level language command procedures
v The NetView automation table
v The ASSIGN command
When creating your title-line mode messages, ensure that the first line does
not conflict with any message number supplied by IBM. A message
number format similar to the IBM message number format can be helpful
when you use these facilities with your messages.
Refer to sample AMLWTO (CNMS4273) in CNMSAMP for an example of
title-line output.
Full-Screen Mode
You can present a full panel of information using 3270 data streams.
Full-panel command processors, which run under an OST, are the only

12 Programming: Assembler
 Designing Assembler Modules

type of user-written code (except for installation exit DSIEX12) that can use
full-screen mode. This topic is addressed in “Writing a Full-Screen
Command Processor” on page 65.
Refer to sample APSSFULL (CNMS4279) in CNMSAMP for an example of
full-screen output.
Title-Line Output
Title-line output is best suited to message groups that can be presented on
a single panel. Figure 3 shows an example of title-line output.

NETVIEW 06/16/99 09:35:20

=NETV1
NCP LINE PU/CLUSTER LU/TERMINAL TYPE LOCATION
----- ---- ----------- ------------ ----- ----------

NCPA 3725 MACH. ROOM

NCPA A01 SDLC SATELLITE
NCPA A01 A01A 3274 ANCHORAGE
NCPA A01 A01A A01A01 3279 ANCHORAGE
NCPA A01 A01A A01A02 3279 ANCHORAGE
NCPA A01 A01A A01A03 3279 ANCHORAGE
NCPA A01 A01B 3274 NOME
NCPA A01 A01B A01B01 3279 NOME
NCPA A01 A01B A01B02 3279 NOME
NCPA A01 A01B A01B03 3279 NOME
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .

Figure 3. Example of Title-Line Output

The first line that the NetView program generates is a user-customized

NetView message prefix on a line by itself. This prefix is the same as the
one defined under Standard Mode. In Figure 3, the equal sign (=) in =NETV1
is the message type and NETV1 is the domain ID. The separator is followed
by the title, which can be 1 - 6 lines. The title is followed by the data lines.
The panel wraps around until all the data is displayed. The title is
redisplayed at the top of each new panel.
Using Title-line Output
To use title-line output, format and send one message buffer for each line
of information as follows:
v Set the HDRMTYPE field in BUFHDR to HDRTYPEL (=). See “Values for
HDRMTYPE Fields” on page 106 for instructions.
v As you build each message buffer, perform the following steps:
– For a line that is part of the title, set HDRIND to HDRLNLBL. Your
title can contain from one to six lines.
– For a data line, set HDRIND to HDRLNDAT.
– For the last line of data, set HDRIND to HDRLNEND.
v When the message buffer is ready for presentation, do one of the
following steps:
– From any NetView subtask, use the DSIMQS macro to queue the
message buffer to the preferred OST. This method is appropriate to
use from the destination OST. However, the output is not displayed
until you return control to the OST.

Chapter 2. Designing Assembler Modules 13

Designing Assembler Modules

– From an OST or NNT, issue the DSIPSS TYPE=OUTPUT macro to

send the message buffer. You cannot issue this macro to send a
multiline message from a routine running with TVBINXIT set to on.
In either case, the output is not displayed until the data-end line is sent.
The NetView program groups all title-line buffers at the OST until a buffer
marked as data end (HDRLNEND) is received. Upon receipt of the end
message, the title lines are sent to the panel. These lines are listed directly
under the previous message. Each data line appears one line at a time. If
the message sequence fills one panel and begins another, the title lines are
repositioned at the top of the panel, followed by the next data lines. This
process continues until all the messages are displayed on the panel.
Each buffer sent to the panel contains at least one character. To print a
blank line, place a blank character (X'40') in the buffer. If a line of title-line
output is longer than the width of the panel, the line is truncated to panel
width.

Displaying Messages to the System Console

The write-to-console service (DSIWCS) macro displays a message buffer at the
system console. The message buffer requires an initialized NetView buffer header
(BUFHDR). The route code that is used is the value specified on the ROUTECDE
statement in the CNMSTYLE member.

Logging Messages
The write-to-log service (DSIWLS) macro records information in the network log,
the system log, a hardcopy log, an external log, or a sequential log.

Network Log, the System Log, and Hardcopy Task: DSIWLS logs data to the
network log, the system log, and the hardcopy task. The DEFAULTS and
OVERRIDE commands determine the general logging environment. The current
logging actions are applied to the message buffer passed to the DSIWLS macro. If
the message is passed in an AIFR buffer, the system checks the AIFR setting to
determine which logs contain the messages.

External Logging: DSIWLS provides for the logging of data to the external
logging task (DSIELTSK). You can define the external logging task at installation to
record to the system management facilities (SMF) log or to a user-defined data set.
If you use a user-defined data set, you must code the XITXL exit to actually
perform the logging of the data.

External logging is a data services task (DST). See Chapter 8, “Macros,” on page
155 for information about DSTs. The XITXL exit is described in “XITXL: External
Logging” on page 56.

Sequential Logging: DSIWLS also provides for logging of data to a sequential

logging task. The sequential logging task records the data using the basic
sequential access method (BSAM). You can define multiple sequential logging tasks
at installation.
Table 2. Sequential logging examples. Examples of sequential logging
Task Reference
Writing to a sequential log CNMS4275 sample in Appendix A,
“Assembler Samples,” on page 271
Writing to the logs Sample library on the product tape

14 Programming: Assembler
 Designing Assembler Modules

Table 2. Sequential logging examples (continued). Examples of sequential logging

Task Reference
Installing the external logging task IBM Tivoli NetView for z/OS Installation:
Configuring Additional Components
Installing sequential logs IBM Tivoli NetView for z/OS Application
Programmer's Guide

Calling Commands
You can call commands directly, or you can schedule them. Calling a command
directly requires the following steps:
v Initialize the command environment (required control blocks must be acquired,
and so on).
v Call the command entry service (DSICES) macro to look up the address of the
command processor in the NetView command table. Then a branch is performed
to the command processor.

To schedule a command, you must use the message queuing service (DSIMQS)
macro. Scheduling a command under a task places a command buffer on one of
the message queues of the task. Other command buffers can be ahead of the buffer
of the scheduled command. When the buffer is processed off the message queue,
the command processor is called.

Calling a Command Directly

All of the following steps in this section are required to directly call a command
processor or command list.

Obtaining a Command Work Block (CWB): A command processor requires a

CWB for use as a parameter list, a save area, and a work area. You can build your
own CWB or you can obtain a CWB by issuing the DSILCS macro. Before calling
the command processor, store the TIB address in the CWBTIB field of the
associated CWB.

Obtaining a Service Work Block (SWB): The routine that calls a command
processor provides an SWB. You can preallocate or obtain the SWB with the
DSILCS macro, or the SWB can be one the caller has passed. This control block
must also have its SWBTIB field pointing to the TIB of the task. The SWB address
must be stored in CWBSWB.

Building a Command Buffer: A command buffer containing a verb and optional

operands calls each command. The command buffer is prefixed with the BUFHDR
field. Each BUFHDR field must be initialized except the HDRMCEXT message
command extension. The address of this command buffer is stored in CWBBUF.

Obtaining a Parse Descriptor Block (PDB) and Parsing the Command: The
routine obtains storage for a PDB so the command processor can parse the
command. You can obtain the size of the storage for the PDB by issuing the
DSIPRS macro with the PDBSIZE option in the program. See “Parsing” on page 19
for more information.

Identifying the Command Processor Address: After the command is parsed, you
can find the command in the NetView system command table (SCT). You can look
up the command using DSICES in one of three ways:

Chapter 2. Designing Assembler Modules 15

Designing Assembler Modules

v With the parsed command in the PDB

v With the unparsed command in the command buffer (CWBBUF)
v By command processor module name (the module name is known but the verb
name can change, as in a synonym)

The DSICES macro returns the address of the system command table entry. The
macro returns the address in an area passed on the DSICES macro as the
SCTADDR parameter. This address points to an SCT entry, mapped by the system
command entry (SCE), and the address is stored in the PDBCMDA field.

When the DSICES macro returns to the caller, the return code indicates whether
the command is immediate, regular, or both. When TVBINXIT is on, the
PDBIMMED bit must be set on if the DSICES return code indicates that the
command to be called was defined as TYPE=I (immediate) or TYPE=B (both).

You can call regular commands only when TVBINXIT is off and only from task
types OST, NNT, and PPT. You can call immediate commands only when
TVBINXIT is on and only from task types OST and NNT. Unless otherwise noted
in this book, do not call NetView-written TYPE=D commands.

Calling the Command Processor: When calling the command processor, some of
the registers can have the following assignments:
1 Points to the CWB, which next points to the PDB, SWB, TIB, and the
command buffer.
13 Points to a save area. It is probably already set there, because a save area is
required for the service macros.
14 Contains the return point address.
15 Contains the entry point address (found in SCE) of the command
processor.

The command processor entry point address is stored in the SCECADDR field of
the SCE entry pointed to by the PDBCMDA field. SCECADDR contains the
address of the linkage assist routine called DSICMDLD. Branch to DSICMDLD
with a branch and set mode (BSM) or a branch and save and set mode (BASSM).
DSICMDLD resolves any residency requirements for data areas being passed. For
example, if the caller is in AMODE=31, passes data areas (command buffer, CWB,
and so forth) above-the-line, and is calling a command processor which resides
below-the-line, DSICMDLD copies all the needed areas into below-the-line storage
before calling the target command processor.

For example, to pass a command to VTAM while running under an OST, NNT, or
PPT, prepare the input. Call the NetView command processor identified by DSICES
for your VTAM command.

See sample CNMS4280 in Appendix A, “Assembler Samples,” on page 271 for an

example of calling a command directly.

Scheduling Commands Using DSIMQS

You use the DSIMQS macro to schedule the invocation of commands. The simplest
way for user-written code to call regular commands to run under an OST or NNT
is to simulate commands entered from a terminal. Include the command in the text
of a standard buffer with an initialized buffer header, as described in “BUFHDR:

16 Programming: Assembler
 Designing Assembler Modules

Buffer Header” on page 103. In BUFHDR, set HDRMTYPE to HDRTYPET. You can
use HDRTYPEB as well, but commands with a HDRMTYPE set to HDRTYPEB are
not logged or echoed.

Use the DSIMQS macro to queue the buffer to the preferred OST or NNT, where
the command is processed as though it had been entered from a terminal.

Choosing Command Priority: You can schedule commands as high priority. This
enables the command to preempt any existing queued messages or other work that
is scheduled at lower priority. Commands scheduled with high priority also
pre-empt command procedures that are already running. If you do not want to
pre-empt work that might already be queued, including command procedures that
are already running, schedule your command at low priority. See “DSIMQS:
Message Queuing Services” on page 202 for more information about priority.

Passing Commands to a Subtask in the Same Domain: To pass commands to a

subtask in the same domain, build an IFRCODCR and queue it to the preferred
subtask. An IFRCODCR (see “DSIIFR: Internal Function Request” on page 120) is
an internal function request (IFR) to call a command. IFRCODCR is intended for
requesting or conveying data. The command driven by this type of buffer does not
present data to the operator by full-screen or line mode, and it does not create or
remove a long-running command. These actions can be disruptive because the
operator can be engaged in unrelated activity.

The IFR requires:

v An initialized BUFHDR with command extension
v An IFRCODE set to IFRCODCR

The command and its operands follow the IFRCODE.

In BUFHDR, HDRMLENG must reflect the length of the command and its
parameters, and the length of the IFRCODE field. Set HDRTDISP to the offset of
the IFRCODE field, which must be X'24', the offset of the HDRMSG field in the
BUFHDR. Set HDRMTYPE to HDRTYPEI.

Use the DSIMQS macro to send the buffer to any subtask that can process a
command. When the buffer is received, the NetView program increases HDRTDISP
by 2 to address the command and its parameters. The NetView program decreases
HDRMLENG by 2, because the IFRCODE is not included in the command text.

For more details about the fields and settings of BUFHDR and IFR, see “BUFHDR:
Buffer Header” on page 103 and “DSIIFR: Internal Function Request” on page 120.

See sample CNMS4283 in Appendix A, “Assembler Samples,” on page 271 for an

example of scheduling a command.

Scheduling Commands in a Cross-Domain Environment

You can schedule commands on a remote system using the RMTCMD command.
You can enhance the power of this cross-domain scheduling by using NetView
pipelines with the RMTCMD command.

The DSIPSS macro also provides for the scheduling of commands in a

cross-domain (OST or NNT) environment.

Chapter 2. Designing Assembler Modules 17

Designing Assembler Modules

You can forward a command from one domain to another by doing either of the
following steps (providing the route has been previously established using the
START DOMAIN command):
v Building a buffer with the preferred command and issuing the DSIPSS macro
with TYPE=XSEND to transmit the command to the cross-domain task (NNT) in
another NetView program.
v Calling the ROUTE command. (See “Scheduling Commands Using DSIMQS” on
page 16) The ROUTE command routes a command to a specified NetView
domain. For more information, refer to the NetView online help.

The commands you call can return data to the originating domain by issuing
DSIPSS TYPE=OUTPUT for a buffer with HDRMTYPE=HDRTYPEU or
HDRMTYPE=HDRTYPEL.

The maximum length of text that you can send as a cross-domain command is 240
bytes, which corresponds to three 80 character input lines. Use multiple commands
to chain data for applications that require a larger data transfer.

Additional Services
The following sections describe other services provided by the NetView program.

Loading and Deleting Modules in Virtual Storage

You can dynamically load and delete modules that are used infrequently by using
the DSILOD and DSIDEL macros. Use DSILOD to load the module and DSIDEL to
delete the module.

See sample CNMS4271 in Appendix A, “Assembler Samples,” on page 271 for an

example of using DSILOD and DSIDEL.

Posting and Waiting on Event Control Block (ECB) Services

You can post and wait on ECBs using the DSIPOS (post) and DSIWAT (wait)
macros. With DSIWAT, you can wait on a single ECB or on a list of ECBs.

See the optional task template (CNMS4277) in Appendix A, “Assembler Samples,”

on page 271 for an example of waiting on an ECB list.

Disk Services
The disk services (DSIDKS) macro retrieves data from partitioned data sets. The
DSIDKS macro is linked to a data set. This macro locates a specific member or file
and reads the records there, as illustrated in the following example:
DSIDKS
. SWB=(REG2),DSBWORD=DISKADDR,TYPE=CONN,NAME=DSIPRF▌1▐
.
.
DSIDKS
. SWB=(REG2),DSBWORD=DISKADDR,TYPE=FIND,NAME=MEMNAME▌2▐
.
.
DSIDKS
. SWB=(REG2),DSBWORD=DISKADDR,TYPE=READ▌3▐
.
.
DSIDKS
. SWB=(REG2),DSBWORD=DISKADDR,TYPE=READ,INCL=YES▌3▐
.
.
DSIDKS
. SWB=(REG2),DSBWORD=DISKADDR,TYPE=DISC,NAME=DSIPRF▌4▐
.
.
DSIPRF
. DC CL8’DSIPRF ’
.
.
MEMNAME DC CL8’MEMNAME ’

18 Programming: Assembler
 Designing Assembler Modules

Key Explanation
▌1▐ This statement initializes the disk service control blocks and input buffer,
returning the address of the DSB in DISKADDR. The NAME parameter
specifies the DDNAME (DSIPRF in this example).
▌2▐ This statement finds the member name MEMNAME and reads the first
record using the returned DSBWORD. Because FIND reads the first record
of the file, you can code INCL=YES on a FIND request to indicate that if
the first record is a %INCLUDE statement, it is to be processed. INCL=YES
is required for Data REXX.
▌3▐ These two statements read the next two sequential records. INCL=YES
specifies that %INCLUDE statements are to be processed.
▌4▐ This statement frees the control blocks and the input buffer.

See sample CNMS4276 in Appendix A, “Assembler Samples,” on page 271 for an

example of using DSIDKS to read a NetView initialization file.

Parsing
You can parse NetView command and message buffers (containing the standard
NetView BUFHDR structure) using the DSIPRS macro. The DSIPRS macro requires
a parse descriptor block (PDB). The returned PDB includes the PDBBUFA pointer
to the command buffer, the parse elements, and the number of parse elements.

Do the following to determine the size of the PDB and parse a buffer:
1. Issue the DSIPRS macro with the PDBSIZE option specified. This returns the
required size of the block.
2. Build the control block header (CBH) and set CBHID to the value defined by
symbol CBHPDB after you obtain the storage (from preallocated storage or
with DSIGET).
3. Set CBHTYPE to 0.
4. Store the PDB length in the CBHLENG field.
5. Call DSIPRS with the supplied PDB to parse the buffer. DSIPRS fills in the PDB
with the delimiter and parse information. The DSIPRS macros are issued in
pairs.

See sample CNMS4280 in Appendix A, “Assembler Samples,” on page 271 for an

example of using DSIPRS to calculate the size and initialize a parse descriptor
block.

Command Authorization Checking

Command authorization checking verifies that a command or operand is available
to an operator or group of operators.

You can use the command entry services (DSICES) macro to determine whether an
operator is authorized to use a given command, and you can use the keyword and
value service (DSIKVS) macro to determine whether an operator is authorized to
use a given keyword or keyword and value combination.

You can use the parameter alias service (DSIPAS) macro to derive the original
keyword and value for a command that is entered with parameter aliases.
Parameter aliases are defined with the CMDDEF PARMSYN statement in
DSIPARM member CNMCMD or its included members.

Chapter 2. Designing Assembler Modules 19

Designing Assembler Modules

Note: Refer to the IBM Tivoli NetView for z/OS Security Reference for more
information about command authorization checking.

Named Storage
You can create and retrieve a storage environment across multiple command
processor calls using named storage.

You can use the DSIPUSH macro to create a named storage pointer, as shown in
the following code segment:
.
.
.
L R3,LOCLSTOR BUFFER AREA FOR PUSH LIST
USING SWBLRCPL,R3
XC 0(SWBLRCPU,R3),0(R3)
MVC SWBLRCLN(4),=A(SWBLRCPU) LENGTH OF PUSH LIST
MVC SWBLRCNM(16),MYNAME UNIQUE NAME OF LRC
MVC SWBLRCST(4),DYNASTOR QUEUED STORAGE OBTAINED FOR LRC
MVC SWBLRCRE(8),ZEROS NO RESUME FOR NAMED STORAGE
MVC SWBLRCAB(8),MYABEND ADD ABEND MODULE NAME
MVC SWBLRCLG(8),=C’DSILRCR8’ (FOR EXAMPLE)
* SWBLRCFG (FLAGBITS) IGNORED FOR NAMED STORAGE
L R4,CWBSWB AVAILABLE SWB
. DSIPUSH SWB=(R4),LIST=(R3),ROLL=NO
.
.

Then you can use the DSIFIND macro to retrieve the named storage pointer, as
shown in the following code segment:
.
.
.
L R3,LOCLSTOR BUFFER AREA FOR PUSH LIST
USING SWBLRCPL,R3
XC 0(SWBLRCFI,R3),0(R3)
MVC SWBLRCLN(4),=A(SWBLRCFI) LENGTH OF FIND LIST
MVC SWBLRCNM(16),MYNAME UNIQUE NAME OF LRC
L R4,CWBSWB AVAILABLE SWB
DSIFIND SWB=(R4),LIST=(R3)
LR R3,R1 ADDRESS OF MY NAMED STORAGE
USING
. MYDSECT,R3
.
.

For more details on the coding of these macros, see “DSIPUSH: Establish
Long-Running Command” on page 223 and “DSIFIND: Find Long-Running
Command Storage” on page 170.

Sending and Receiving Data Using the MS Transport

The following macros send and receive data using the MS transport:
DSIGETDS
Retrieves messages or management services units (MSUs) on the initial
data queue when the assembler command processor is driven from the
automation table.
DSI6REGS
Registers an MSU application with the MS transport, or a served
application with operations management.
DSI6SNDS
Enables MS applications or operations management served applications on
the NetView program to send data to a specified target in the same
domain, or to a logical unit (LU) or VTAM CP name in any domain.

20 Programming: Assembler
 Designing Assembler Modules

Sending and Receiving Data Using the High-Performance

Transport
The following macros send and receive data using the high-performance transport:
DSIHREGS
Registers an application that wants to send data to or receive data from
another application using the high-performance transport. This macro also
deregisters applications.
DSIHSNDS
Enables NetView applications to send data to a specified target using the
high-performance transport. These applications must be registered through
DSIHREGS.

Passing an MSU through the NetView Automation Table

The DSIAUTO macro provides a way for a program, running within the NetView
address space, to pass an MSU directly to the active automation table. For details
about DSIAUTO, see “DSIAUTO: Invoke Automation Services” on page 155.

Numeric Code Point Translation

You can use the DSIC2T macro for numeric code point translation. The code point
translation service routine is available to the NetView program in REXX, PL/I, C,
and assembler languages. The function performed is the same, regardless of the
language you choose.

Use the NetView code point translation service to translate the numeric code
points received in alerts into readable text. With this, you can use NetView Bridge
with a problem-management database to open problem records when NetView
alerts are received.

Specifying Tokens in Alert Automation

The DSIBAM macro specifies the keyword=data tokens included in the alert
automation message generated by CNMS4284.

Note: Issue this macro only from CNMS4284.

Returning a Command to an Originating Domain

For a command running under an NNT to call a command in the originating
domain, the command must issue DSIPSS TYPE=OUTPUT for a buffer with
HDRMTYPE=HDRTYPEX. The buffer must contain the preferred command verb
and parameters. The verb must be delimited from the data or parameters with a
blank and must be a defined command in the receiving domain.

For example, if data formatting is required, you can build a buffer with
HDRMTYPE=HDRTYPEX and a command in the buffer text. In this case, the
command verb identifies a user-defined presentation services command processor
and the parameters are the data to be presented. When the receiver of the
cross-domain message of the OST gets the command buffer, the OST calls the
command processor with the data.

Applications are limited to sending 256 bytes of data. Use multiple commands to
chain data for applications that require a larger data transfer.

Chapter 2. Designing Assembler Modules 21

Designing Assembler Modules

Resource Span Checking

You might want a command processor to use NetView span checking facilities to
limit operators to particular sets of resources. For more information about span
checking, refer to the IBM Tivoli NetView for z/OS Security Reference.

The DSIQRS macro simplifies the implementation of resource span checking. Use
DSIQRS to determine whether a resource is in an operator's span of control and
whether an operator is allowed access to a particular resource. For example, if you
want to determine whether a particular operator is authorized to issue commands
for a particular resource, DSIQRS might be specified as follows:
DSIQRS SWB=(REG2),OPID=OPERID,RESOURCE=RESNAME

Applications supply the operator ID and the VTAM resource name to the DSIQRS
macro. DSIQRS issues one of the following return codes:
Code Meaning
0 The NetView operator has access to the resource
64 The NetView operator does not have access to the resource
101 RODM query failure

Data Services Task (DST) Unique Services

Access to communication network management (CNM) data and VSAM files is
provided by the CNM service (DSIZCSMS) and VSAM service (DSIZVSMS)
macros. You can use these macro services only under DSTs. DSTs and their macro
services are described in Chapter 8, “Macros,” on page 155.

22 Programming: Assembler
Chapter 3. Writing Installation Exit Routines
This section illustrates how to design, code, and install installation exit routines
that take advantage of NetView exits.

Overview of Installation Exit Routines

You can write installation exit routines to view, delete, or replace data flowing to,
from, or through the NetView program. You can also write installation exit routines
to perform special functions. With the NetView program, you can code installation
exits for your specific processing needs. Some examples of specific processing
needs include accounting, routine processing, security verification, and any data
manipulation requirements. Installation exit routines handle a specific event with
nonstandard processing and automate processes based on message and
management services unit (MSU) information. For example, your code can examine
the messages and MSUs passing through the NetView program, record relevant
data, and initiate work requests based on the data.

The NetView program provides 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.
v Data services task (DST) installation exits (XITnn and BNJPALEX), which apply
only to DSTs. The DST installation exit routines are loaded when the associated
DST starts. Each DST can have its own set of installation exit routines.

Each installation exit handles a particular event, such as the reception of data from
the system console. When that event occurs, the NetView program passes control
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, you can concatenate up to ten DST exit routines. If you
concatenate routines, the first DST exit routine returns control to the NetView
program. If the first exit does not indicate USERDROP, the NetView program calls
the next exit in the sequence. This process continues until the last DST exit has
returned control to the NetView program or USERDROP is indicated.

Writing a routine for each installation exit is not necessary. Installation exits written
to process frequently run functions degrade performance. See Table 3 for a list of
installation exits and their sample numbers. These samples are meant to be used as
examples of how to code a NetView installation exit. You can customize them for
your individual needs.
Table 3. Installation Exit Environments. Superscript numbers refer to the corresponding notes at the end of the table.
NetView
Exit Description Applicable Tasks TVBINXIT REENT Samples
DSIEX01 Input from the operator OST with VTAM On Yes
terminal
DSIEX02A Message output this domain or NNT, OST, PPT NNT, On or Off Yes CNMS4271
message output cross-domain OST, CNMCSSIR CNMS4283
DSIEX03 Input before command processing NNT, OST, PPT Off Yes

© Copyright IBM Corp. 1997, 2015 23

Writing Installation Exit Routines

Table 3. Installation Exit Environments (continued). Superscript numbers refer to the corresponding notes at the end
of the table.
NetView
Exit Description Applicable Tasks TVBINXIT REENT Samples
DSIEX04 Log output for buffers not Main task or any On or Off Yes
processed by DSIEX02A subtask
DSIEX05 Before VTAM command invocation NNT, OST, PPT Off Yes
DSIEX06 Solicited VTAM messages NNT, OST, PPT Off Yes
DSIEX07 Cross-domain command send NNT, OST Off Yes
DSIEX09 Output to the system console Main task or any On or Off Yes
subtask
DSIEX10 Input from the system console DSIWTOMT Off No
DSIEX11 Unsolicited VTAM messages PPT Off No
DSIEX12 Logon validation NNT, OST Off Yes
DSIEX13 OST/NNT message receiver NNT, OST, PPT Off Yes
DSIEX14 Before logoff NNT, OST Off Yes
DSIEX16 Post-NetView automation table exit NNT, OST, PPT On or Off Yes
for messages CNMCSSIR
DSIEX16B Post-NetView automation table exit DST, OST, PPT, NNT On or Off Yes
for MSUs
DSIEX17 Monitors MVS system messages NNT, OST, PPT Off Yes CNMS4297
and delete operator messages CNMCSSIR
(DOMs)
DSIEX18 Network LOG BROWSE installation LOG BROWSE TASK On No CNMS4298
exit (domidBRW)
DSIEX19 Service point application NNT, OST, PPT Off Yes CNMS4307
authorization checking during
RUNCMD processing
DSIEX20 SAW record filtering DST (AAUTSKLP) Off Yes CNMS4308
DSIEX21 DSITCPRF encryption CNMTAMEL, TCP/IP No Yes
OST
XITBN BSAM empty file DST Off No
XITBO BSAM output DST Off No
XITCI CNM data input DST Off No CNMS4284
XITCO CNM interface output DST Off No
XITDI DST initialization DST Off No
XITVI VSAM input DST Off No
XITVN VSAM empty file DST Off No CNMS4270
XITVO VSAM output DST Off No
XITXL External logging DST Off No

24 Programming: Assembler
 Writing Installation Exit Routines

Table 3. Installation Exit Environments (continued). Superscript numbers refer to the corresponding notes at the end
of the table.
NetView
Exit Description Applicable Tasks TVBINXIT REENT Samples
Note:
1. Does not apply to the AUTOTASK command and MVS console task.
2. This exit applies to the NetView program operator interface (POI) only. Does not include messages from the
subsystem interface. You can process these messages in DSIEX02A.
3. If used by more than one DST, they must be reentrant.
4. Do not use DST installation exits under the network product support (NPS) task named DSIGDS.
5. Refer to the IBM Tivoli NetView for z/OS Security Reference for more information.

Designing and Coding an Installation Exit Routine

Installation exit routines must adhere to the guidelines for user-written
programming described in “General Coding Guidelines” on page 4. In addition,
installation exit routines needs to conform to the special requirements described in
this section. After coding your installation exit routine, follow the instructions in
“Installing an Installation Exit Routine” on page 56.

Input
When you enter the installation exit routine, the registers contain the following
information:

Register Contents
1 The address of the installation exit parameter list (USE control block). The
USE contains the following address:
v Service work block (SWB) to be used as a work area or to request
services from the NetView program (USERSWB). If you use the SWB for
your save area or for dynamic variables, you must obtain another SWB
when invoking NetView macros.
v Message buffer USERMSG
v Task vector block (TVB)
13 The address of a standard 72-byte save area used to store the caller's
registers.
14 The return address.
15 The entry address of the installation exit.
0, 2-12 Unspecified.

Do not change any input, particularly the USERMSG buffer in the USE control
block.

In general, the installation exits process data as it is received. That is, no specific
translation to uppercase is performed.

When data is entered on the command facility screen, the NetView program calls
the DSIEX01 exit.
v At entry to the DSIEX01 exit, no translation to uppercase is performed on the
message buffer.

Chapter 3. Writing Installation Exit Routines 25

Writing Installation Exit Routines

v Upon exit from the DSIEX01 exit, the message buffer is translated to uppercase if
the data does not contain the characters NETVASIS at the beginning of the text
and the OVERRIDE NETVASIS condition is not in effect.
All subsequent installation exits that process this message buffer process the buffer
in uppercase unless it was not translated because of the NETVASIS characters.

Output
Most installation exit routines pass the following return codes to the NetView
program in register 15 to indicate that the messages or MSUs are to be unchanged,
deleted, or replaced. Exceptions to the following return codes are noted with the
specific exits. The registers are restored without change, except for register 15 (and
register zero (0) if USERSWAP is returned).
USERASIS (0)
Use the message or MSU as presented to the installation exit; do not delete
or replace it.
USERDROP (4)
Delete the message or MSU from the terminal and from the network log,
system log, and hardcopy log; stop processing before the message or MSU
appears on the screen.
USERSWAP (8)
Replace the message or MSU with the message or MSU addressed in
register zero (0).

See specific installation exit descriptions in “Summary of Installation Exits” on

page 29 for additional return code considerations.

Deleting Messages and MSUs

To delete a message or MSU entirely, use return code USERDROP. The NetView
program frees the buffers using DSIFRE. Therefore, the installation exit should not
free the buffers.

When the NetView program receives a USERDROP return code, no further exit
routines are called. If you have concatenated DST exit routines, a USERDROP
return code prevents the next exit routine from being called.

When processing a single line of a title-line message (HDRTYPEJ, HDRTYPEK, or

HDRTYPEL), do not delete a CONTROL, LABEL, or END line unless the entire
message is deleted. When processing a title-line message formatted as an
IFRCODAI, you can delete any line. For example, if DSIEX06 deletes message
IST314I END, processing of the entire title-line message (of which this is the END
line) is disrupted. However, if DSIEX02A deletes IST314I END, the remainder of
the title-line message is displayed normally.

Replacing Messages and MSUs

If you want to replace a message or MSU, the new message or MSU must be one
of the following types:
v A static message
v An MSU
v A buffer in a reentrant storage area, such as the SWBADATD or SWBPLIST areas
of the USERSWB of the USE control block.

26 Programming: Assembler
 Writing Installation Exit Routines

Only the text portion of the buffer is swapped. Also, ensure that the HDRMLENG
of the new message or MSU is less than or equal to HDRMLENG of the original
message or MSU, unless the message or MSU is formatted as an IFRCODAI.

If you want to replace a title-line message, do not change the HDRMTYPE or

HDRIND fields in the buffer header.

When processing a single line of a title-line message (HDRTYPEJ, HDRTYPEK, or

HDRTYPEL), do not replace any lines because the sequence and format might be
lost. When processing a title-line message formatted as an IFRCODAI, you can
replace any line.

The DSIEX02A installation exit provides a more flexible interface for replacing
messages including title-line and MLWTO (multiline write-to-operator) type
messages. See “DSIEX02A: Output to the Operator” on page 30.

You can concatenate DST installation exit routines when replacing messages. In this
case, the buffer containing the replacement message or MSU becomes the input for
the subsequent DST installation exit routine.

Considerations for IFRCODAI

If you want a message or MSU logged but not displayed, you can set the
appropriate display and logging flags in the IFRCODAI. See “DSIIFR: Internal
Function Request” on page 120 in the appropriate installation exit (for example,
DSIEX16 and DSIEX16B).

Several NetView installation exits are called to process automation internal

function requests (function requests with the IFR code IFRCODAI). The IFRCODAI
buffers chain other buffers off them. If your installation exit replaces any of these
buffers, use separate DSIGETs for each buffer. For each DSIGET, specify
non-queued subpool zero storage.

Note: Subdivision of storage into multiple buffers results in storage management

problems such as lost storage or an abend.

Message Flow and Interception Points

The following topics summarize the sequence of decisions made by the NetView
program in handling messages. This information can be useful in determining
what forms of message processing are most efficient to meet your performance
objectives.

The NetView automation table cannot automate messages that are written only to
the network log.

Message Handling by OST/NNT:

1. A message is solicited from VTAM through the program operator interface
(POI). The following actions are taken:
v If the DSIEX06 (solicited access method message input) exit exists, the exit is
called. Deleted messages are not processed further.
v IST608I and IST1274I messages are used to update network status. Other
VTAM messages are not processed by the status monitor.
2. If the DSIEX02A exit exists, it is called. If the exit indicates that the message is
to be deleted, it is deleted.

Chapter 3. Writing Installation Exit Routines 27

Writing Installation Exit Routines

3. The message is checked to see if it satisfies an &WAIT condition in a NetView

command list or a TRAP condition in a REXX or high-level language command
procedure. With the SUPPRESS option, the message is marked for deletion
unless DSIEX16 specifies otherwise.
4. The NetView automation table begins processing. Table actions are reflected in
the buffer structure given to DSIEX16. The automation internal function request
(AIFR) buffers have fields that are set to indicate what actions the automation
table has scheduled. These actions are carried out after the DSIEX16 exit returns
to the NetView program.
5. DSIEX16 is called.
6. Logging, display, routing, and command actions are processed as specified in
the buffer in combination with the current DEFAULTS and OVERRIDE settings.
7. If the message is displayed and copies have been assigned by the ASSIGN
command with the COPY option, a copy is sent to each assigned operator. The
NetView automation table cannot automate the copied messages.

Note: The NetView automation table and DSIEX16 are called only once for each
unique message in a NetView domain. Any copies of the message made by the
ASSIGN command or the NetView automation table do not result in a call to the
NetView automation table or DSIEX16 in this NetView domain.

Note: Refer to the IBM Tivoli NetView for z/OS Automation Guide for more
information about message handling by the OST/NNT.

Message Handling by the PPT Including Messages to the Authorized Receiver:

1. When the message is from VTAM through the POI:
a. If this is one of the messages that the status monitor uses to update
network status, it is processed by the status monitor.
b. If there is an unsolicited message installation exit (DSIEX11) or an exit for a
message solicited by a VTAM command issued under the primary POI task
(DSIEX06), the proper exit is called. Deleted messages are not processed
further.
c. VTAM commands and messages received under the VTAM start option
PPOLOG=YES (such as those entered from the system console and echoed
to the NetView program) are only logged. They are not automated.
2. When the message has been assigned using the ASSIGN command with the
PRI and SEC options, each assigned operator is sent a copy of the message (if
an operator was logged on in the PRI list). These messages then proceed
through the OST/NNT flow for those particular operators, but the secondary
(SEC) copies are not processed by the NetView automation table or DSIEX16.
3. When the message has not been assigned, it is sent to the authorized message
receiver and proceeds through the OST/NNT flow for that operator.
4. When the message has not been assigned and no authorized message receiver
is logged on to the NetView program, the flow continues as follows:
a. Exit DSIEX02A is called, if one exists. If the exit specifies that the message is
to be deleted, it is deleted.
b. The NetView automation table begins processing. Table actions are reflected
in the buffer structure given to DSIEX16. The AIFR buffers have fields that
are set to indicate what actions the automation table has scheduled. These
actions are carried out after the DSIEX16 exit returns to the NetView
program.
c. DSIEX16 is called. The NetView automation table and DSIEX16 are called
only once for each unique message in a NetView domain. Any copies of the
28 Programming: Assembler
 Writing Installation Exit Routines

message made by the ASSIGN command or the NetView automation table

do not result in a call to the NetView automation table or DSIEX16 in this
NetView domain.
d. Logging, routing, and command actions are processed as specified in the
buffer in combination with the current DEFAULTS and OVERRIDE settings.
e. If the message is to be displayed, it is written to the system console.

Note: Refer to the IBM Tivoli NetView for z/OS Administration Reference for
information about determining the authorized message receiver. Refer to the IBM
Tivoli NetView for z/OS Automation Guide for more information about message
handling by the PPT.

Control Blocks
The service facilities used in your installation exit routine dictate the control blocks
you must include in your routine. However, the following control blocks are
required:
v The installation exit parameter list (USE)
v The main vector table (MVT)
v The service work block (SWB)

Use macro DSICBS to include these and any additional control blocks your routine
needs. For more information, see “DSICBS: Control Block Services” on page 159
and the control block descriptions in Chapter 7, “Control Blocks,” on page 103.

Summary of Installation Exits

The following sections describe each installation exit provided by the NetView
program, including examples of use and coding requirements.

DSIEX01: Input from the Operator

The NetView program calls the DSIEX01 exit when an operator provides
standard-mode input to an OST or when an NNT receives cross-domain input. The
DSIEX01 exit runs after device-dependent data has been removed from the input
buffer but before syntax or command verbs are analyzed and before the message is
logged. All commands issued under an operator OST task, regardless of type, that
are issued from the command facility command line are passed to the DSIEX01
exit. The exception to this is when certain error conditions occur such as a failure
to parse the command. For an NNT, the DSIEX01 exit is called when a command is
routed from the owning task.

The exit is not called if any of the following actions occur:

v Commands are issued under an autotask or a RMTCMD distributed autotask.
v The Enter key is pressed with no data.
v The Clear key is pressed.
If a PF or PA key is pressed, the key definition is resolved first, then DSIEX01 is
called.

All regular (TYPE=R) commands, including those from the command facility, the
hardware monitor, or the threshold analysis and remote access feature, are also
passed to DSIEX03.

Example of Use: You can use DSIEX01 to support short cut commands by
translating an operator’s single character entries into extended command strings.

Chapter 3. Writing Installation Exit Routines 29

Writing Installation Exit Routines

Coding Considerations: DSIEX01 follows the coding guidelines given in

“Limitations When TVBINXIT Is Active” on page 5. DSIEX01 does not apply to
unattended or attended operator tasks.

Return Codes: The following list contains return codes for OST input:
USERASIS (0)
The original command is processed and added to the RETRIEVE stack.
USERDROP (4)
The original command is not processed and is not added to the RETRIEVE
stack.
USERSWAP (8)
The command buffer returned by the exit pointed to by register 0 is
processed. The original command is added to the RETRIEVE stack.

DSIEX02A: Output to the Operator

DSIEX02A is called under the OST, NNT, PPT, or CNMCSSIR task. The NetView
program calls DSIEX02A for standard output to an operator's terminal (DSIPSS
TYPE=OUTPUT, DSIPSS TYPE=IMMED, or FLASH) before &WAIT and WAIT
message processing, and before the NetView automation table is scanned to
determine processing actions. For example, messages from user-written command
processors that issue DSIPSS TYPE(OUTPUT) result in calls to DSIEX02A.
DSIEX02A processes a single message or multiline message at a time.

NetView automation table processing occurs before DSIEX16 is called, and the
resultant actions are scheduled immediately after this exit.

The single message that was processed by DSIEX02A can become a chain of
messages representing the actions that the NetView automation table produced.

Example of Use: DSIEX02A provides you with an exit that can process the
messages before &WAIT (or WAIT) and the NetView automation table take effect.

You can use this exit to modify the processing options for a message and specify or
substitute new logging, display, command, or routing actions independently of one
another.

DSIEX02A can reformat messages by removing buffers, changing buffers, and

adding new buffers to the original message. The exit can prevent OVERRIDE
command options from taking effect for messages.

Note: If your messages are to be translated to Japanese, for example, changes to

the message text can affect the translations. Refer to the IBM Tivoli NetView for z/OS
Installation: Configuring Additional Components for more information.

Coding Considerations: TVBINXIT is on when called for DSIPSS TYPE=IMMED.

If TVBINXIT is on, DSIEX02A follows the coding guidelines given under
“Limitations When TVBINXIT Is Active” on page 5.

Do not use the DSIPSS macro in this installation exit routine. If a message is
required, use the DSIMQS macro to queue the message to the subtask.

Because the NetView program does not check the syntax of messages that are sent
to a terminal, DSIEX02A does not receive a PDB.

30 Programming: Assembler
 Writing Installation Exit Routines

NetView automation is called after this exit routine is 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 exit routine.

DSIEX02A provides the following additional features not available in other exits:
v The NetView buffer passed to this exit is an AIFR. You need to reference the IFR
control block rather than the BUFHDR.
v For single-line messages, multiline messages, and title-line messages, this buffer
points to the entire chain of buffers that contain the message.

You can replace all chained buffers by using DSIGET for non-queued subpool zero
storage for new buffers and copying or replacing all the data in the old buffers.
Separate DSIGET invocations can be used for each buffer chained off the
IFRCODAI internal function request buffer. Any original buffers passed to the exit
can be either freed or passed back to the NetView program on the return. You
must free the unused buffers using DSIFRE for nonqueued subpool zero storage.
Initialize all necessary fields in all buffers and copy any reserved or unused header
information from each of the buffers.

Notes:
1. The NetView program frees only those buffers that are returned in the
IFRCODAI format.
2. For information about freeing NetView buffers see “Free NetView Buffers
Service Routine (DSIFREBF)” on page 267.
3. Messages issued by DSIPSS with TYPE=FLASH cannot be processed by user
exit DSIEX02A because the exit is not called for FLASH messages.

The IFRCODAI contains control information and system data that can be accessed
only through the provided NetView automation table and command list interfaces.
Unauthorized modification of these fields can cause processing, logging, or display
loops.

Return Codes: In DSIEX02A, you can swap or delete messages by direct

manipulation of the buffers that are located by the USERMSG field of the DSIUSE
parameter list. When the return code is USERASIS, the NetView program uses the
AIFR that is returned in the USERMSG field.

Use the DSIGET macro to obtain new buffers and the DSIFRE macro to release
buffers you have removed. To release all the buffers and the AIFR buffer, use the
DSIFREBF callable service and set USERMSG to zero.

The return codes are as follows:

USERASIS (0)
The NetView program continues processing with the AIFR found in the
USERMSG field. If you return a zero in the USERMSG field, you are
responsible for freeing the AIFR and all associated buffers.
USERDROP (4)
The NetView program frees the AIFR in the USERMSG field.
USERSWAP (8)
The NetView program continues processing on the AIFR found in register
zero (0). This is similar to USERASIS, except that you return the AIFR in
register zero (0) instead of USERMSG.

Chapter 3. Writing Installation Exit Routines 31

Writing Installation Exit Routines

The AIFR that is originally passed to the exit in the USERMSG field becomes the
responsibility of the exit. If the same AIFR is not passed back to the NetView
program in register zero (0), the exit is responsible for freeing the original AIFR.

General Notes® for DSIEX02A: When IFRCODAI buffers have commands, the
DISPLAY, logging, BEEP, and HOLD options are not referenced during the
command run.

DSIEX02A has access to user bit and character fields in the IFRCODAI structure
that enable signaling between DSIEX02A, DSIEX03, DSIEX16, user-written tasks, or
user-written commands. Actions (including HOLD and BEEP) specified in the
IFRCODAI structure supersede the DSIMVT defaults. DSIEX02A cannot determine
the overrides but can mark buffers that are not affected by the overrides. When
DEFAULT BEEP=DISABLE or HOLD=DISABLE, the option is not processed by the
NetView program when specified by DSIEX02A, DSIEX16, or the NetView
automation table, unless the IFRCODAI buffer has the corresponding force flag in
IFRAUTA4 set to on and the action flags in IFRAUTA1 or IFRAUTA2 contain a
nondefault value.

If a force flag in IFRAUTA4 is set to on before NetView automation table

processing (such as in DSIEX02A or before), the corresponding action is not
considered by the NetView automation table processing even if the NetView
automation table specifies a value for it. This enables the DSIEX02A exit or the
NetView program to define buffers that represent a subset of the logging or
display actions without accidental reversals within the table processing.

Because the force action bits specify display and logging actions, their presence
implies that no command action processing occurs when the NetView automation
table is searched. On the other hand, buffers that contain commands
(IFRAUCMD=ON) cause the NetView program to ignore the display and logging
action indicators, including the action force flags.

Because logging actions are serviced under the task under which the NetView
automation table is called, buffers marked as forced non-display are not routed to
other tasks by a matching NetView automation table entry.

DSIEX03: Input Before Command Processing

DSIEX03 is called for all regular commands. Regular commands include the
following 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 Resulting from the NetView automation table
v Entered for an attended operator task
v Entered from a terminal
v Received as HDRTYPEX messages from an NNT
v Queued with EXCMD
v Run by a PIPE stage

Before running, all regular commands are passed to DSIEX03. Regular commands
(TYPE=R) entered from the command facility command line are passed to both
DSIEX01 and DSIEX03. DSIEX03 is also called for TYPE=B commands that are not
entered from the command facility command line. Note that a TYPE=B command

32 Programming: Assembler
 Writing Installation Exit Routines

can requeue itself and therefore seem to drive both DSIEX01 and DSIEX03.
Commands running under the PPT that are entered as responses to messages
DSI802A and DSI803A are not passed to any installation-defined exit.

Example of Use: You can use DSIEX03 to restrict use of particular regular
commands if your conditions are more complex than those provided for by
command authorization checking.

Coding Considerations: NetView OST task processing, including autotasks,

removes any suppression characters before invoking DSIEX03. If the command
buffer presented to DSIEX03 has a suppression character removed, the
HDRMTYPE of the command buffer is HDRTYPEB.

If two suppression characters precede the command (for example, a “quiet”

command), the HDRMTYPE is HDRTYPQC.

If a command buffer is swapped by DSIEX03, HDRMTYPE is set to HDRTYPES

when the buffer is swapped by the exit, as described in “Replacing Messages and
MSUs” on page 26.

Return Codes: DSIEX03 can pass the following return codes:

USERASIS (0)
The original command is processed.
USERDROP (4)
The original command is not processed.
USERSWAP (8)
The command buffer whose address was returned by the exit in register
zero (0) is processed.

DSIEX04: Log Output

The NetView program calls DSIEX04 during the logging process. DSIEX04 is
located within log services and applies to messages logged in the network log, the
system log, and the hardcopy log. DSIEX04 runs before the message is reformatted
and sent to the log.

DSIEX04 is not called for messages logged to the external trace data set
(DSITRACE).

DSIEX04 is not called if DSIEX02A and DSIEX16 are called, because you can
specify logging options in these exits and in the NetView automation table. For
example, in a user-written command, if the macro DSIWLS is issued for a buffer
that has not been automated, DSIEX04 is called. In contrast, the same buffer sent to
the terminal with DSIPSS is also logged, but DSIEX02A, the NetView automation
table, and DSIEX16 are called.

Note: DSIEX16 is generally a better exit to reformat log buffers than exit
DSIEX02A because the NetView table options are already processed and can be
analyzed in DSIEX16. DSIEX16 enables creation of logging buffers that are separate
from the display buffers. DSIEX04 is used only for messages not processed by
DSIEX16 (messages not subject to automation).

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

Chapter 3. Writing Installation Exit Routines 33

Writing Installation Exit Routines

Coding Considerations: If TVBINXIT is on, DSIEX04 follows the coding

guidelines given under “Limitations When TVBINXIT Is Active” on page 5.

Do not use macro DSIWCS or DSIWLS in this installation exit routine.

Because DSIEX04 can run under any subtask that issues macro DSIWLS, be sure
that any service facilities you request are supported by the subtask under which
the routine is running. For example, DST is limited to VSAM or CNM interface
services.

Because the NetView program does not check the syntax of messages that are sent
to a log, DSIEX04 does not receive a PDB. See “DSIPDB: Parse Descriptor Block”
on page 142 for information about how to parse the messages in DSIEX04.

If USERPDB is not 0, a PDB is available for the installation exit. When USERPDB is
0, the installation exit must obtain its own PDB (using DSIGET) if a PDB is
preferred, and release it (using DSIFRE) before returning to the NetView program
from the installation exit.

Return Codes: DSIEX04 can pass the following return codes:

USERASIS (0)
Log the original message.
USERDROP (4)
Do not log the message in any of the available logs (network, hardcopy, or
system).
USERSWAP (8)
Log the message whose address was returned by the exit in register zero
(0) in the available logs.
USERLOG (12)
Write the message to the network or system log only.
USERLOGR (16)
Write the substituted message to the network or system log only. The
address of the buffer containing the new message is in register zero (0).
USERHCL (20)
Write the message to the hardcopy log only.
USERHCLR (24)
Write the substituted message to the hardcopy log only. The address of the
buffer containing the new message is in register zero (0).
USERNSL (28)
Do not write to the system log.
USERNSLR (32)
Do not write to the system log. Use the substituted message to write to the
other logs. The address of the buffer containing the new message is in
register zero (0).

DSIEX05: Before VTAM Command Invocation

The NetView program calls DSIEX05 when preparing to pass a command to VTAM
through the 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.

34 Programming: Assembler
 Writing Installation Exit Routines

Coding Considerations: Code the routine to handle both the OST and PPT
control block structures.

This exit applies only to commands entered directly (not using the MVS prefix)
that are passed through the NetView POI.

Note: Commands passed to DSIEX05 have already been processed under DSIEX03
and, possibly, DSIEX01.

Return Codes: DSIEX05 can pass the following return codes:

USERASIS (0)
Pass the original command to VTAM.
USERDROP (4)
Do not pass the command to VTAM.
USERSWAP (8)
Pass the command whose address was returned by the exit in register zero
(0) to VTAM.

DSIEX06: Solicited VTAM Messages

The NetView program calls DSIEX06 when it receives a solicited VTAM message
through the POI, which is generated in response to a VTAM command the user
issued or the PPT issued. The message is not 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.

Coding Considerations: Code the routine to handle both the OST and PPT
control block structures.

This exit applies only to messages received through the NetView POI in response
to commands entered directly (not using the MVS prefix).

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

Note: Messages processed (and not deleted) by DSIEX06 are then processed by
DSIEX02A.

Return Codes: DSIEX06 can pass the following return codes:

USERASIS (0)
Process the message returned by VTAM.
USERDROP (4)
Do not process the message returned by VTAM.
USERSWAP (8)
Process the message whose address was returned by the exit in register
zero (0).

DSIEX07: Cross-Domain Command Send

The NetView program calls DSIEX07 before commands are sent cross-domain to an
NNT (DSIPSS TYPE=XSEND).

Chapter 3. Writing Installation Exit Routines 35

Writing Installation Exit Routines

Example of Use: You can use DSIEX07 to monitor cross-domain traffic through
the network.

Coding Considerations: Do not use DSIPSS TYPE=XSEND in this installation exit

routine. Also, avoid directly calling commands that route a command to another
domain, such as ROUTE, DISPLAY, or VARY. If necessary, you can queue such
commands for execution. Refer to “Scheduling Commands Using DSIMQS” on
page 16 and “Passing Commands to a Subtask in the Same Domain” on page 17
for more information.

DSIEX07 does not receive a PDB. The cross-domain NetView program parses the
messages after they are received. Refer to “DSIPDB: Parse Descriptor Block” on
page 142 for more information about parsing the messages in DSIEX07.

Return Codes: DSIEX07 can pass the following return codes:

USERASIS (0)
Send the message to the NNT.
USERDROP (4)
Do not send the message to the NNT.
USERSWAP (8)
Send to the NNT the message whose address was returned by the exit in
register zero (0).

DSIEX09: Output to the System Console

The NetView program calls DSIEX09 when a message is written to the system
console operator using macro DSIWCS. The message has not been formatted for
transmission.

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

Coding Considerations: If TVBINXIT is on, the DSIEX09 exit follows the coding
guidelines given in “Limitations When TVBINXIT Is Active” on page 5.

The DSIEX09 exit is called as a result of DSIWCS macro calls. The output of the
attended operator task OST task is processed in the DSIEX02A exit instead of the
DSIEX09 exit.

Do not use macros DSIWCS or DSIMQS in this installation exit routine. If you
need to send a message to the system console from this exit routine, use system
macros instead.

Because the NetView program does not check the syntax of messages that are sent
to the system console, the DSIEX09 exit does not receive a PDB. Refer to “DSIPDB:
Parse Descriptor Block” on page 142 for more information about parsing messages
in the DSIEX09 exit.

Return Codes: DSIEX09 can pass the following return codes:

USERASIS (0)
Send the message to the system console.
USERDROP (4)
Do not send the message to the system console.

36 Programming: Assembler
 Writing Installation Exit Routines

USERSWAP (8)
Send to the system console the message whose address was returned by
the exit in register zero (0).

DSIEX10: Input from the System Console

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 started or logged.

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

Coding Considerations: DSIEX10 is called only from task DSIWTOMT, not from a
subtask.

DSIEX10 does not receive a PDB. Refer to “DSIPDB: Parse Descriptor Block” on
page 142 for information about parsing the messages in DSIEX10.

DSIEX10 is not called for commands that an operator enters using an MVS console
OST. DSIEX03 is called instead.

Return Codes: DSIEX10 can pass the following return codes:

USERASIS (0)
Process the command from the system console.
USERDROP (4)
Do not process the command from the system console.
USERSWAP (8)
Process the command whose address was returned by the exit in register
zero (0).

DSIEX11: Unsolicited VTAM Messages

The NetView program calls DSIEX11 when an unsolicited VTAM message is
received through the POI. In addition, when the VTAM PPOLOG=YES modify or
start option is used, copies are presented to DSIEX11. This installation exit is called
before the resource name is analyzed and before the message is logged.

Example of Use: The DSIEX11 exit can issue the DSIMQS macro to send a copy of
the message buffer before processing by the NetView program. If you want to send
unsolicited messages to all operators, the DSIEX11 exit can transform the messages
into MSG ALL commands.

Coding Considerations: If DSIEX11 calls a command or a command procedure,

the command restrictions for the PPT apply.

NetView automation is started 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 started for a message that has
been deleted by this installation exit routine.

Return Codes: DSIEX11 can pass the following return codes:

USERASIS (0)
Process the message from VTAM.

Chapter 3. Writing Installation Exit Routines 37

Writing Installation Exit Routines

USERDROP (4)
Do not process the message from VTAM.
USERSWAP (8)
Process the message whose address was returned by the exit in register
zero (0).

DSIEX12: Logon Validation

The NetView program calls DSIEX12 at the completion of the logon process after
accepting the logon.

Example of Use: You can use DSIEX12 to check 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 USERTVB (address of the session TVB) and the USETOTVB (address
of the TVB being taken over) fields. If the task is a non-takeover operator task, the
USETOTVB field is 0. If the task is a takeover operator task, the USETOTVB field
is set to the actual address of the TVB that is being taken over.

For a takeover operator task, DSIEX12 is called mainly to validate the operator ID
and password. Therefore, consider using the USETOTVB field in DSIEX12 to
determine if this exit was called for a takeover operator task.

Coding Considerations: If you require output to the screen, use only the
following DSIPSS types:
v SCRSIZE
v WINDOW
v ASYPANEL
v CANCEL
v PSSWAIT
v TESTWAIT

Return Codes: 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 installation exit is called under all OSTs and NNTs, including
unattended-operator tasks.

DSIEX13: OST/NNT/PPT Message Receiver

The NetView program calls DSIEX13 upon receipt of certain subtask-subtask
communication buffers received on a subtask as a result of the use of the DSIMQS
macro on another task. The NetView program calls DSIEX13 when:
v A user-defined IFRCODUS is received by way of macro DSIMQS for an OST, an
NNT, or the PPT.
v A message buffer (with HDRMTYPE=HDRTYPEM) is received by way of macro
DSIMQS on an OST or NNT.

Note: The DSI039I message is an example of a HDRTYPEM message received by

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

38 Programming: Assembler
 Writing Installation Exit Routines

HDRTYPEM messages and IFRCODUS buffers are treated differently:

v The NetView program does not process IFRCODUS buffers after DSIEX13 is
called. It frees the buffer using DSIFRE, which is consistent with other buffers
received by way of DSIMQS. For information about freeing NetView buffers, see
“Free NetView Buffers Service Routine (DSIFREBF)” on page 267.
v HDRTYPEM buffers are displayed unless the return code USERDROP is used.
Displayed messages are processed like typical NetView messages, including
calling DSIEX02A and DSIEX16 exits, invoking NetView automation table
processing, and logging the messages.

Example of Use: You can use DSIEX13 with IFRCODUS to initiate a user function
with a buffer. Code DSIEX13 to perform the user function specified by IFRCODUS.
You can send the IFRCODUS message buffer to another task or you can queue it to
the task in which your program (such as a command processor) is running using
the DSIMQS macro. You can also use DSIEX13 to monitor DSI039I messages
received on an OST or NNT.

Coding Considerations: DSIEX13 does not free (using DSIFRE) the IFRCODUS or
HDRTYPEM buffers. For information about freeing NetView buffers, see “Free
NetView Buffers Service Routine (DSIFREBF)” on page 267.

Return Codes: DSIEX13 can pass the following return codes:

USERASIS (0)
Process the message.
USERDROP (4)
Do not process the message.
USERSWAP (8)
Process the message whose address was returned by the exit in register
zero (0).

Note: An incorrect return code causes a user abend code 262 (X'106').

DSIEX14: Before Logoff

The NetView program calls DSIEX14 when an OST or NNT is preparing to end for
any of these reasons:
v The operator enters LOGOFF.
v The subtask LOSTERM exit is driven (VTAM).
v The subtask is posted to end.

The subtask cannot communicate with the operator's terminal. However, you can
issue macro DSIWCS to write to the system console and macro DSIWLS to write
entries to the log.

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

Non-Takeover and Takeover Operator Task Processing: For a non-takeover

operator task (when Takeover is not specified on the Logon screen), the NetView
program calls the DSIEX12 exit 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 the DSIEX12 exit. For this
type of task, the DSIEX12 exit is called mainly to validate the operator ID and
password. When the takeover processing completes, the task for the session that is

Chapter 3. Writing Installation Exit Routines 39

Writing Installation Exit Routines

being taken over is the task used for the session, and the task is cleaned up. For
takeover task processing, the NetView program does not call the DSIEX14 exit.

Coding Considerations: Because no buffer is associated with logoff processing,

DSIEX14 receives neither an input buffer nor a PDB.

Return Codes: The NetView program ignores any return code received from this
installation exit routine.

DSIEX16: Post-NetView Automation Table Exit

When a message is considered for automation under the display services (DSIPSS
macro), the NetView program immediately calls DSIEX16. DSIEX16 runs under the
OST, NNT, PPT, or CNMCSSIR task.

NetView automation table processing occurs before DSIEX16 is called (DSIEX16

processing is separate and not dependent on NetView automation table
processing), and the resulting actions are scheduled immediately after this exit.
DSIEX16 is called just before logging, display, routing, or command actions are
processed. DSIEX16 receives a description of the total processing to be performed
on the message.

DSIEX16 is called for everything DSIEX02A is called for, except messages that are
deleted by DSIEX02A through USERDROP or zeroing IFRAUTBA. This provides
for the monitoring of message deletion.

It is possible to have more than one distinct message chained together. The
message that was processed by DSIEX02A can become a chain of messages
representing the actions that the NetView automation table produced. Each
element of the chain is a complete buffer structure similar to the one given to
DSIEX02A, and they are chained together using the HDRNEXTM field in the
buffer header (BUFHDR) of each buffer on the chain. Message buffers are followed
by action buffers. The last buffer has a zero in its HDRNEXTM field.

If you establish cross-domain sessions to the same domain and you want these
messages automated on the receiving or OST side, you can set the IFRAUMTB bit
off in this exit on the sending or NNT side. The IFRAUMTB bit is normally set on
by the NNT because all messages sent from an NNT have had an opportunity to
call the NetView automation table on the sending or NNT side. The NetView
program changes this bit to zero when received in a new domain for all cases
except when the originating domain name is equal to the receiving domain.

Example of Use: DSIEX16 provides an opportunity to modify the effects of

&WAIT (or WAIT) and the NetViewautomation table after they are determined but
before the automation actions take effect. If an &WAIT or WAIT suppresses a
message, it does not undergo automation table processing. It is sent to DSIEX16.

Use this exit to modify the processing options for a message and specify or
substitute new logging, display, command, or routing actions independently of one
another.

DSIEX16 can reformat messages by removing buffers, changing buffers, and adding
entirely new buffers to the original message. The exit can prevent OVERRIDE
command options from taking effect for messages.

40 Programming: Assembler
 Writing Installation Exit Routines

DSIEX16 provides for different editing of the text for each group of destinations
specified by the results of NetView automation table or default message processing
options. This exit can also help monitor the effectiveness of message suppression
and automation.

Coding Considerations: TVBINXIT is on when called for DSIPSS TYPE=IMMED.

For more information, see “Limitations When TVBINXIT Is Active” on page 5.

Do not use DSIPSS in this exit routine. You can issue new messages by chaining
them to the original message structure.

DSIEX16 does not receive a PDB. DSIEX16 uses the IFRCODAI internal function
requestlike DSIEX02A does. However, DSIEX16 is written to run in 31-bit
addressing mode exclusively.

DSIEX16 does not use DSIMQS on any part of the IFRCODAI structures when it is
in the form given to DSIEX16. The routing list buffers whose addresses are in
IFRAURTL are only used during the DSIEX16 interface. To issue DSIMQS for an
IFRCODAI structure, ensure that HDRNEXTM is zero (there is only one
IFRCODAI structure) and that IFRAURTL is zero. Use care in manipulating the
HDRNEXTM fields and IFRAURTL fields to prevent accidental loss of buffers.

Return Codes: DSIEX16 differs from the other installation exits in that it ignores
the return code, but it expects a zero. In the other NetView exits, these return
codes indicate that messages are to be deleted or a new message is to be swapped
for the original one.

In DSIEX16, you can swap or delete messages by direct manipulation of the buffers
that are located by the USERMSG field of the DSIUSE parameter list. The NetView
program uses whatever structure the USERMSG field refers to on return and
performs the actions that are indicated.

Use the DSIGET macro to get new buffers and the DSIFRE macro to release buffers
you have removed. Use the Q=NO option and specify subpool 0 on these DSIGET
and DSIFRE requests. If you release all the buffers, you set the USERMSG field to
zero to indicate that there are no buffers when you return.

Additional DSIEX16 Features Not Found In DSIEX02A: DSIEX16 specifies

multiple IFRCODAI buffer structures chained with the HDRNEXTM buffer
chaining field. The first such buffer is the representation of the original message,
including display and actions before DEFAULTS and OVERRIDE options are
considered. See Figure 4 on page 42.

Chapter 3. Writing Installation Exit Routines 41

Writing Installation Exit Routines

Register 1: Address of DSIUSE control block

Register 13: Standard 72 byte save area
Register 14: Return address
Register 15: Address of exit

DSIUSE

USERCBH - Control block header

USERMSG - Address of IFRCODAI Structure Chain
USERLU - Address of 8 byte TVBLUNAM
USEROPID - Address of 8 byte TVBOPID
USERSWB - Address of DSISWB for use by the exit
USERTVB - Address of this task's DSITVB
USERPDB - 0 (Not used by DSIPSS)

IFRCODAI
Chain
IFRCODAI
IFR
BUFHDR IFRCODAI
HDRNEXTM BUFHDR
* HDRNEXTM 0
* *
IFRAUTBA BFR1 BFR2 IFRAUTBA BFR1 BFR2
*
IFRAUTBL IFRAUTBL
AIFR * Message * Message buffers
Detail * buffers *
Data IFRAUCMB IFRAUCMB Command buffers
Mapping * *
IFRAUVPT Obj1 Obj2 * Routing List
* IFRAURTL
IFRAURTL DSIAIFRO Chain BUFHDR
*
HDRMCEXT
*
IFRAURTB Routing
IFRAURCC List
IFRAURCL (1) Mapping
IFRAURCL (2)
*
*
*
IFRAURCL (IFRAURCC)

Figure 4. DSIEX02A, DSIEX16, DSIEX16B, and DSIEX17 Interface. IFRAURCL(n) is a notation to indicate that there
are as many IFRAURCL entries as the value of IFRAURCC.

Each EXEC action, specified on the NetView automation table statements that
match the message, creates an additional IFR-type IFRCODAI chained using the
HDRNEXTM field. An exception is for multiple EXEC actions that have only a
ROUTE keyword. EXEC actions with only ROUTE keywords combine with
existing IFRCODAI route lists, if the same type (ONE or ALL) of ROUTE-only
buffer exists. Each of the IFR-type IFRCODAIs contains its own set of message
buffers.

If a command keyword is specified, the corresponding IFR-type IFRCODAI has the

IFRAUCMD bit on and contains the address of the command buffer in
IFRAUCMB.

If the command buffer originated in the local domain, IFRAUCMB points to a

IFRCODCR internal function request buffer (DSIIFR). If DSIPSS sends the
command from an NNT task, the command buffer is an HDRTYPEX, not an
HDRTYPEI (DSIIFR).

42 Programming: Assembler
 Writing Installation Exit Routines

If a route keyword is specified, the corresponding IFR-type IFRCODAI has the

IFRAURTL field set to the address of a routing list buffer, as mapped by the
IFRAURTB map within DSIIFR. The IFRAURTL field contains the address of a
standard NetView buffer that must contain a standard BUFHDR and extension
HDRMCEXT. You need to set buffer fields HDRBLENG, HDRMLENG, and
HDRTDISP. The NetView program does not use other header fields for this buffer.
HDRTDISP is the offset into the buffer at which the field IFRAURTB is located.

For all buffers processed within the NetView program and prefixed with a
BUFHDR, HDRTDISP is set to a value greater than the last buffer header field. The
value can change from one release of the NetView program to another. For
references to specific data in buffers, use HDRTDISP as the starting index instead
of assuming the data has a specific value. The value is based on the currently
defined buffer headers, and is typically a 24, 36, or 46 decimal. Other values occur
when commands are called (for example, when the IFRCODCR is skipped over
calling a command processor).

On entry to DSIEX16, the DISPLAY, BEEP, HOLD, and HCYLOG actions are the
same in each IFR-type IFRCODAI on the chain pointed to by the HDRNEXTM
field of the original AIFR. However, the original AIFR can be different from those
on the chain. SYSLOG and NETLOG actions are indicated in the original (first)
buffer, and the additional EXEC action buffers indicate that logging is suppressed
with overrides not available. This ensures that a message is logged only once,
unless the DSIEX16 exit directs otherwise.

The NetView program uses the USERMSG field on return as the chain of IFR type
IFRCODAIs to be processed. If USERMSG is set to zero by DSIEX16, the
installation exit frees all buffers passed. These buffers are non-queued, subpool
zero storage. These buffers are 31-bit addressable buffers. When USERMSG is
nonzero, it points to the chain of IFRCODAI buffers. The installation exit can
return multiple IFR-type IFRCODAIs without routing lists (with or without
commands), and multiple IFR-type IFRCODAIs with routing lists or commands or
both.

Buffers with no routing list or commands are processed as display or logging

buffers or both, depending on the settings of action flags in the IFR-type
IFRCODAI. For example, independent structures can be returned with only a
display action in one structure, and logging actions in the other structure to enable
independent processing of logged and displayed buffers. In this case, use the flags
specifying that overrides are to be ignored to prevent accidental display of log-only
buffers. The NetView program sets logging actions only in the original IFR-type
IFRCODAI to ensure that the message is logged only once. Display of the buffers
is inline as if the DSIPSS macro is issued originally for all the buffers.

Buffers that have no routing list but contain a command are queued to the task
that is processing the message using DSIMQS. This causes the command to be run
when the task processes the message queue.

Buffers with routing lists are queued to the specified tasks using DSIMQS. The
routing lists are generated exactly as specified by the AUTOMSG definitions and
can include both active and inactive tasks. Any tasks that are inactive do not
receive the buffers.

DSIEX16 can determine the current defaults by checking the bits in the MVTAIDFT
field in the DSIMVT.

Chapter 3. Writing Installation Exit Routines 43

Writing Installation Exit Routines

Note: When IFRCODAI buffers have commands, the DISPLAY, logging, BEEP, and
HOLD options are not referenced during the command execution.

DSIEX16 has access to user bit and character fields in the IFR-type IFRCODAI that
enable signaling between DSIEX02A, DSIEX03, DSIEX16, DSIEX17, user-written
tasks, or user-written commands. Actions (including HOLD and BEEP) specified in
the IFR-type IFRCODAI supersede the DSIMVT defaults. DSIEX16 cannot
determine the overrides but can mark buffers that are not affected by the
overrides. The NetView program does not process the default options
BEEP=DISABLE or HOLD=DISABLE when specified by DSIEX02A, DSIEX16, or
the NetView automation table, unless the IFRCODAI buffer has the corresponding
force flag on in IFRAUTA4 and the action flags in IFRAUTA1 or IFRAUTA2
contain a nondefault value.

When a force flag is set on in IFRAUTA4 before NetView automation table

processing (such as in DSIEX02A or before), NetView automation processing does
not consider the corresponding action, even if the NetView automation table
specifies a value for it.

Because the force action bits specify display and logging actions, their presence
implies that no command action processing occurs when the NetView automation
table is searched. Conversely, buffers that contain commands (IFRAUCMD=ON)
cause the NetView program to ignore the display and logging action indicators,
including the action force flags.

Because logging actions are serviced under the task under which the NetView
automation table is called, buffers marked as forced nondisplay are not routed to
other tasks by a matching NetView automation table entry.

You can pass information from your NetView automation table to DSIEX16. For
example, you can direct what DSIEX16 does for a class of messages or MSUs that
the automation table has identified. Use the CMD() part of the IF statement to send
data to the DSIEX16, marked by using a dummy command name. To do this, first
define a dummy command with a name (for example, CMDEX16) in the CMDDEF
definitions in CNMCMD or its included members. You can then code this in an
automation table, even though you do not intend to run it. For example:
EXEC(CMD(’CMDEX16 ’ PARM1 PARM2))

DSIEX16 then looks at the command buffer chained from IFRAUCMB for the
dummy command name, and uses the PARM1 and PARM2 set by the automation
table. If the dummy command name is present, DSIEX16 does what PARM1 and
PARM2 indicate. DSIEX16 dechains and frees the IFRAUCMB buffer with the
dummy command name command buffer before returning to the NetView
program. This prevents the program from actually running the command.

To edit or create log buffers, set the appropriate logging options in a separate copy
of the original IFRCODAI with its own data buffer chain. If you chain the new
IFRCODAI with the appropriate logging flags or OVERRIDE suppressing flags, or
both, to the original IFRCODAI buffer chain, the edited data is logged to the
specified logs. You can set the IFRAUDIS flag off, and set the DISPLAY override
suppressed flags on, to prevent accidental display of the log buffers if the task
specifies override DISPLAY=YES.

DSIEX16 also provides for message processing accounting. The IFR-type

IFRCODAI provides indicators that show a record of processing of a particular
message, such as whether the message is solicited, came from the PPT, was an

44 Programming: Assembler
 Writing Installation Exit Routines

authorized-receiver routed message, satisfied an &WAIT or a WAIT, or was

suppressed or processed by the NetView automation table.

Note: DSIEX02A has only one IFR-type IFRCODAI and its HDRNEXTM is zero.
The command and routing buffers created by the NetView automation table first
appear in DSIEX16. See Figure 4 on page 42 for an illustration of the DSIEX16
interface.

DSIEX16B: Post-Automation Table Exit for MSUs

This installation exit is called for MSUs subject to automation table processing.
This installation exit is called after automation actions, such as commands to be
scheduled, and hardware monitor filter settings have been determined and are
accessible in the AIFR, but before the actual actions are taken. DSIEX16B is loaded
during NetView initialization.

Example of Use: DSIEX16B provides an opportunity to modify the effects of the

hardware monitor SRFILTER command and the automation table, after they are
determined but before automation actions take effect.

Use this exit to modify the filter settings, color, and other presentation attributes,
and to change or substitute the command buffers to be run. You can also use this
exit to help monitor the effectiveness of filtering and automation.

Coding Considerations: Installation exit DSIEX16B is called when the AIFR

driving the exit contains MSU data instead of standard message data. The AIFR is
passed to the exit through the standard installation exit parameter list (DSIUSE)
whose address is passed in register 1. You can customize the exit programs based
on the type of AIFR data to be processed, or you can code a single program to be
used for both message AIFRs and MSU AIFRs.

A buffer containing the MSU automated data is present. Other buffers containing
the following can also be present:
v HIER information
v EXEC CMD actions

Return Codes: DSIEX16B handles return codes the same way as DSIEX16. Like
DSIEX16, it ignores the return code, but it expects a zero. Only register 15 can be
used to pass the return code.

DSIEX17: MVS Message and DOM Receive

The NetView program calls DSIEX17 upon receipt of MVS messages and delete
operator messages (DOMs).

The NetView program tracks action messages in order to process DOMs as they
arrive from MVS. The NetView program considers a message to be an action
message if any of the following are true:
v IFRAUWWR (or CPOMLR) is on.
v A descriptor code in the IFRAUWDS field (or the CPOCDESC field, if it exists)
is one of the values specified on the MVSPARM.ActionDescCodes CNMSTYLE
statement.

When the DSIEX17 exit returns control, the NetView program determines whether
these conditions are true. If any are true, the NetView program activates
IFRAUACN to indicate that the message is an action message. If the value of the

Chapter 3. Writing Installation Exit Routines 45

Writing Installation Exit Routines

ifrauMTB flag is set to off (0), the NetView program also submits the message to
the message automation tables. If the flag is set to on (1), the message is assumed
already to be automated.

The DSIEX17 exit is called by the CNMCSSIR subsystem router task for unsolicited
messages marked for automation in either the MPF table or the Message Revision
table. The DSIEX17 exit is also called under any NetView task having an EMCS
console for messages directed to that console by the system.

Notes:
1. Typically, the MVS system does not generate DOMs for messages that are not
considered action messages. If the DSIEX17 exit changes a non-action message
to an action message, a DOM can never be generated by MVS. Because storage
is needed to track action messages, storage growth can occur if the NetView
program processes an action message for which no DOM is forthcoming. The
DSIEX17 exit is also called for user messages that originated with the
DSIMMDB or CNMPMDB services on any operating system. DSIEX17 runs
under the OST, PPT, NNT, and CNMCSSIR tasks. For messages, this exit is
called before automation or ASSIGN processing.
2. The interface that is used is similar to the DSIEX02A exit, but the DSIEX17 exit
is called with TVBINXIT off and must be written in assembler language.
3. The DSIEX17 exit can set IFRAUDMA on to indicate that the deletion events for
this message can be automated. This is the same as using DOMACTION(A) in
the automation table. The DSIEX17 exit can set IFRAUACT on, if IFRAUDMA
is set on.
When IFRAUDMA is on, the message being deleted drives the automation
table a second time. No user exits are driven by the delete action. The
automation table then has the opportunity to issue a REXX (or other) procedure
to react to the message deletion. The automation table is driven once per copy
of the message being deleted on each task that has a held copy of the message.
4. The DSIEX17 exit can set IFRAUDMN on to indicate that the deletion events
for this message can be ignored. This is the same as using DOMACTION(N) in
the automation table.
This option prevents the CNMCSSIR task from queuing data to remember
messages requiring deletion. It does not prevent messages from being held on
operator screens or from being retained by autotasks.
5. The DSIEX17 exit can test IFRAUDTO to determine whether the MVS DOM
was DOM-by-TOKEN.
6. The DSIEX17 exit does not see the IFRAUDLO bit set, and cannot alter the
setting.

Example of Use: You can use DSIEX17 to process DOMs for action messages that
you convert into other action messages (with a new DOM identification value).
This processing is helpful when you reformat messages such as tape mount
requests.

To avoid storage growth when the NetView program processes an action message
for which no DOM is forthcoming, set the IFRAUDMN bit on to indicate that a
DOM for this message will not be received. For example, suppose DSIEX17 creates
a table of message IDs. The table designates action messages for which no DOM is
generated. Assume that the NetView program receives a message that matches one
in the table, the exit might contain the following code:
OI IFRAUI33,IFRAUDMN INDICATE NO DOM IS EXPECTED

46 Programming: Assembler
 Writing Installation Exit Routines

This code tells the main line code that no DOM is issued for this message, which
prevents unnecessary storage growth.

Coding Considerations: DSIEX17 is supported only in 31-bit addressing mode.

An AIFR is the buffer structure given to DSIEX17.

Return Codes: DSIEX17 can pass the following return codes:

USERASIS (0)
The NetView program continues processing with the AIFR found in the
USERMSG field. You can modify the AIFR directly as in DSIEX02A. If you
return a zero in the USERMSG field, you are responsible for freeing the
AIFR and all associated buffers.
USERDROP (4)
The NetView program frees the AIFR in the USERMSG field.
USERSWAP (8)
The NetView program continues processing on the AIFR found in register
zero (0). This is similar to USERASIS, except that you return the AIFR in
register zero (0) instead of USERMSG.

Note: The AIFR that is originally passed to the exit in the USERMSG field
becomes the responsibility of the exit. If the same AIFR is not passed back
to the NetView program in register zero (0), the exit is responsible for
freeing the original AIFR.

DSIEX18: Network LOG BROWSE Exit

The NetView LOG BROWSE function passes all network log entry records (which
are normally displayed on an operator's screen) to installation exit DSIEX18.
DSIEX18 decides whether to display the records by setting return codes.

When DSIEX18 is given control, register 1 points to the USE control block DSIUSE.
DSIUSE contains USERMSG, which points to a message buffer. This message buffer
contains the following data:

Data type Description

CHAR(8) Operator ID that issued the request
CHAR(248) (for future use)
CHAR(6) Message sequence number
CHAR(1) Blank
CHAR(8) Operator ID
CHAR(1) Blank
CHAR(5) Domain ID
CHAR(1) Blank
CHAR(2) Message code
CHAR(1) Blank
CHAR(8) Time of day (HH:MM:SS)
CHAR(1) Blank
CHAR(1) Important message indicator
CHAR(1) Blank
CHAR(220) Message text

Example of Use: You can use DSIEX18 to suppress certain log records from being
displayed on an operator's terminal.

Chapter 3. Writing Installation Exit Routines 47

Writing Installation Exit Routines

Coding Considerations: DSIEX18 is a global exit routine. It is written in

assembler language, not in HLL (PL/I or C). DSIEX18 is also written to run in a
31-bit addressing mode exclusively. It receives one record at a time from LOG
BROWSE.

When a user issues the BLOG command, filtering occurs based first on the BLOG
specification. Records that are not filtered by BLOG are then passed to the
DSIEX18 exit for processing.

Return Codes: DSIEX18 can pass the following return codes:

USERASIS (0)
LOG BROWSE displays the record.
USERDROP (4)
LOG BROWSE suppresses the record.

DSIEX19: RUNCMD Exit

The NetView RUNCMD exit DSIEX19 is called after normal enterprise security
checking has authorized the use of the RUNCMD command. The exit is passed the
text following the RUNCMD command verb.

Example of Use: You can use DSIEX19 to provide security checking at the service
point command level. You can do this security checking by calling DSICES or
DSIKVS or writing your own command and keyword checking code. To use
DSICES or DSIKVS for security checking, you can define a model CMDDEF
statement specifying DSISPCMD. You can then define command, keyword, and
value authorization checking based on the model CMDDEF statement.

Coding Considerations: The following input is provided upon invocation of

DSIEX19 in the DSIUSE control block:
v DSIEX19 is passed a read-only copy of the command buffer in the USERMSG
field. See “DSIXRCMD: RUNCMD Installation Exit Buffer” on page 154 for a
description of the command buffer pointed to by USERMSG.
v The following fields are other DSIUSE fields that are passed: USERLU,
USEROPID, USERSWB, and USERTVB. USERPDB is 0.
v This user exit must be linked as AMODE=31, RMODE=ANY.

The NetView program provides the CNMS4307 exit as an example. This sample
shows an example of authority checking various commands that are embedded
within a RUNCMD command. The sample uses the DSICES and DSIKVS macros
for authority checking. The command and keyword names are translated by the
sample to alternate names, so that the names are acceptable to the DSICES and
DSIKVS macros.

Return Codes: DSIEX19 can pass the following return codes:

USERASIS (0)
Continue RUNCMD processing to send the command to the service point.
Any return code other than USERASIS
Discontinue RUNCMD processing. This causes message BNH192E to be
issued indicating that processing of the RUNCMD has stopped.

DSIEX20: SAW Exit

The NetView session awareness exit DSIEX20, or SAW exit, is called each time the
session monitor receives a SAW record from VTAM. The SAW record is converted
into a NetView-specific representation called an internal SAW, or ISAW, record. The

48 Programming: Assembler
 Writing Installation Exit Routines

DSIEX20 exit is called after the SAW record is converted into an ISAW record and
before the NetView SAW filtering processing begins.

When DSIEX20 processing starts, register 1 points to control block DSIUSE. The
USERMSG field of DSIUSE points to the message buffer containing a standard
NetView buffer header, as defined by BUFHDR, followed by the ISAW. The
AAUTISAW control block can be used to parse the ISAW, which begins at the
offset indicated by BUFHDR HDRTDISP field.

The message buffer includes workspace after the ISAW. The workspace can be
passed from one DSIEX20 invocation to the next. This workspace is at least 1000
bytes long. The exact amount of workspace can be calculated by the following
formula:
workspace = HDRBLENG - HDRMLENG - HDRTDISP

See “BUFHDR: Buffer Header” on page 103 and “DSIUSE: Installation Exit
Parameter List” on page 151 for more information.

Example of Use: The ISAW records cannot be changed, but they can be kept or
discarded. The DSIEX20 exit provides the functions for more granular filtering of
SAW records than that provided by the VTAM or NetView program. For more
information about record filtering, refer to the KCLASS and MAPSESS statements
in the IBM Tivoli NetView for z/OS Administration Reference.

You can use DSIEX20 to access session data such as the primary and secondary
session endpoint names, PCID, session type (for example, LU-LU and SSCP-PU),
sense code, reason code, and notification type (for example, session start and bind
pending) to determine whether to keep or discard the SAW record. This data is
described in the AAUTISAW control block.

Coding Considerations: DSIEX20 has the following coding considerations:

v To minimize performance impacts, the path length of DSIEX20 can be as short as
possible.
v DSIEX20 must be run in 31-bit addressing mode.
v AAUTISAW defines the format of the ISAW record. The DSECT comments
describe the ISAW record fields.
v All AAUTISAW name fields are coded in EBCDIC. If VTAM does not provide
information for a name field, the field is blank. The following list contains the
name fields:
ISAWCOSS
ISAWCOSA
ISAWLOGM
ISAWFQCP
ISAWPNAM
ISAWSNAM
ISAWPNET
ISAWSNET
ISAWPALI
ISAWSALI

Chapter 3. Writing Installation Exit Routines 49

Writing Installation Exit Routines

v Because there is no PDB, the USERPDB pointer is used to address an 8 byte field
that is initialized to zeros. If DSIEX20 changes this 8-byte field, the field is
treated as the KCLASS name by session monitor, overriding MAPSESS
statements.

Return Codes: DSIEX20 can pass the following return codes:

USERASIS (0)
Exit has no effect. System-defined SAW filtering determines the disposition
of the SAW record.
USERDROP (4)
The SAW record is discarded.
USERKEEP (8)
System defined SAW filtering is bypassed and the SAW record is kept.
Other return code
The exit has no effect. System-defined SAW filtering determines the
disposition of the SAW record. Message DWO050E is logged.

The return codes only affect the session types and SAW types supported by SAW
filtering. Examples of supported types are session-start and init-pending for
SSCP-LU and LU-LU sessions. Session-end is treated the same as its associated
session-start.

DSIEX21: DSITCPRF Encryption

Refer to the IBM Tivoli NetView for z/OS Security Reference for more information
about DSIEX21 encryption code and messages.

XITBN: BSAM Empty File

The DST calls XITBN if the DST encounters aBSAM 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. The exit cannot issue the macros DSIZVSMS and DSIZCSMS.

Return Codes: XITBN can pass the following return codes:

USERASIS (0)
Use th NetView sequential log initialization buffer.
USERSWAP (8)
Use the sequential log initialization buffer whose address was returned by
the exit in register zero (0).

A return code other than USERSWAP or USERASIS is treated as if the return code
was USERASIS and message CNM474I is issued.

XITBO: BSAM Output

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.

50 Programming: Assembler
 Writing Installation Exit Routines

Coding Considerations: XITBO can use only the service facilities available to the
DST. The exit cannot issue the macros DSIZVSMS and DSIZCSMS.

Avoid coding installation exits for frequently run functions, such as BSAM input or
BSAM output, because they can significantly degrade performance.

Return Codes: XITBO can pass the following return codes:

USERASIS (0)
Log the record.
USERDROP (4)
Do not log the record.
USERSWAP (8)
Log the record in the buffer whose address was returned by the exit in
register zero (0).

XITCI: CNM Data Input

The DST calls XITCI after communication network management (CNM) data is
received through the communication network management interface (CNMI) or the
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. The exit cannot issue the macros DSIZVSMS and DSIZCSMS.

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 NetView routing.

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.

Do not use DST installation exits under the network product support (NPS) task
named DSIGDS.

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

Chapter 3. Writing Installation Exit Routines 51

Writing Installation Exit Routines

Table 4. Routing of Network Services Request Units (continued)

Request Header Value Receiving Subtask
CP-MSU X'1212' BNJDSERV, DSIGDS
MDS-MU X'1310' BNJDSERV, DSIGDS
Cross-Domain Alert X'1040' BNJDSERV

For the various receiving subtasks, 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 Receiving
Key Description 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 request unit (RU) header is part of the 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 the NetView program 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 the NetView program 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

52 Programming: Assembler
 Writing Installation Exit Routines

and the remainder of the data is the actual 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 X'1040'. The 16th byte contains the
length of the originating domain ID, and the 17th–24th bytes contain the actual
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.

For more information about the format for a specific RU and how to access data
within the RU, refer to the SNA library, NCP and EP Reference Summary and Data
Areas, and information about flows and control blocks in the IBM Tivoli NetView for
z/OS Troubleshooting Guide.

Return Codes: XITCI can pass the following return codes:

USERASIS (0)
Pass the buffer with the CNM data.
USERDROP (4)
Do not pass the buffer with the CNM data.
USERSWAP (8)
Substitute the CNM data buffer whose address was returned by the exit in
register zero (0).
USEREXLG (252)
Stands for external log only. The hardware monitor, executing under task
BNJDSERV, records the message to the system management facilities (SMF)
only 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 an explanation of 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 MSU. The
hardware monitor recording filters are not applied to the message as they
normally are. Instead, the ESREC filter is set to PASS and all other
recording filters are set to BLOCK.
For NV-UNIQ/LUC alert forwarding protocol forwarded alerts and
SNA-MDS forwarded alerts that are entry points not from a NetView
program, only event data is recorded to the database. For SNA-MDS
forwarded alerts from an entry point NetView program, 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.

If the USEREXLG (252) or USEREVNT (253) return code 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 automation.

Chapter 3. Writing Installation Exit Routines 53

Writing Installation Exit Routines

Refer to the RATE and AUTORATE statements in the IBM Tivoli NetView for z/OS
Administration Reference for more information about these statements.

XITCO: CNM Interface Output

The DST calls XITCO before 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. The exit cannot issue the DSIZVSMS and DSIZCSMS macros.

Do not use DST installation exits under the network product support (NPS) task
named DSIGDS.

If a substitute buffer is returned in register zero (0), the data is a valid SNA RU.
Refer to the SNA library for a description of RU formats.

Return Codes: XITCO can pass the following return codes:

USERASIS (0)
Send the original CNM data.
USERDROP (4)
Do not send the original CNM data.
USERSWAP (8)
Send the CNM data in the buffer whose address was returned by the exit
in register zero (0).

XITDI: Data Services Task (DST) Initialization

The DST calls XITDI for each statement that the DST reads during initialization.
When the end of the file is reached, this installation exit is entered and two
DSIUSE fields, USERMSG and USERPDB, are set to 0, indicating that there is no
more data. You can code up to 10 module names per DST for each user-written
exit routine.

Refer to the IBM Tivoli NetView for z/OS Administration Reference for more
information about XITDI during DST initialization. Also, see “Data Services Task
(DST)” on page 86.

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

Coding Considerations: XITDI can use only the service facilities available to the
DST. The exit cannot issue the macros DSIZVSMS and DSIZCSMS. XITDI cannot
refer to DSRB fields.

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 control the processing of an initialization statement by

the DST by returning the following values:
USERASIS (0)
Process the original DST initialization statement.

54 Programming: Assembler
 Writing Installation Exit Routines

USERDROP (4)
Do not process the original DST initialization statement.
USERSWAP (8)
Process the DST initialization statement in the buffer whose address was
returned by the exit in register zero (0).

When called for an end-of-file situation, a nonzero return code in register 15

indicates that the DST can be stopped.

XITVI: VSAM Input

The DST calls XITVI after a DSIZVSMS macro is issued. The record is 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 is retrieved from
a VSAM data set or file.

Coding Considerations: XITVI can use only the service facilities available to the
DST. The exit cannot issue the macros, DSIZVSMS and DSIZCSMS.

Avoid coding installation exits for functions that can cause a wait, such as VSAM
input or VSAM output, because the wait can significantly degrade performance.

Return Codes: XITVI can pass the following return codes:

USERASIS (0)
Process the original data read from the VSAM file.
USERDROP (4)
Do not process the original data read from the VSAM file.
USERSWAP (8)
Process the data in the buffer whose address was returned by the exit in
register zero (0).

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 the XITVN exit to place a record in the empty data
set. The NetView program provides its own XITVN exit for VSAM logs generated
under the DST task. You can code this installation exit to write your own VSAM
subtask using the DST task as a base.

Coding Considerations: XITVN can use only the service facilities available to the
DST, excluding macros DSIZVSMS and DSIZCSMS. Only VSAM key-sequenced
data sets (KSDS) are supported. Do not replace the XITVN exits provided by the
NetView product for the DSILOG and DSITRACE subtasks.

Return Codes: To initialize the VSAM data set or file, return the USERSWAP
return code and have register zero (0) point to a buffer that contains the record to
be used. A return code other than USERSWAP causes the DST to end.

XITVO: VSAM Output

The DST calls XITVO immediately before the record is written to the VSAM
database.

Chapter 3. Writing Installation Exit Routines 55

Writing Installation Exit Routines

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 exit cannot issue the macros DSIZVSMS and DSIZCSMS.

Avoid coding installation exits for frequently run functions, such as VSAM input
or VSAM output, because the functions can significantly degrade performance.

Return Codes: XITVO can pass the following return codes:

USERASIS (0)
Write the original data in the VSAM file.
USERDROP (4)
Do not write the original data in the VSAM file.
USERSWAP (8)
Write (in the VSAM file) the data in the buffer whose address was returned
by the exit in register zero (0).

XITXL: External Logging

The DST calls XITXL whenever data can be sent to an external log using DSIWLS
with EXTLOG parameter. For example, the session monitor performs external
logging of response time and configuration data.

Coding Considerations: XITXL can use only the service facilities available to the
DST. The buffer passed to the installation exit contains the standard header, with
HDRTDISP pointing to control block DSIELB. The data that is to be logged follows
DSIELB.

Return Codes: XITXL can pass the following return codes:

USERASIS (0)
Write the original SMF record.
USERDROP (4)
Do not write the original SMF record.
USERSWAP (8)
Write the SMF record in the buffer whose address was returned by the exit
in register zero (0).

Unused Installation Exits

The NetView program attempts to load the global exits (DSIEXnn) and the DST
exits (XITnn) specified with DSTINIT statements. If a load attempt fails, the
NetView program issues the following message:
DSI090I LOAD FAILED FOR NCCF MODULE exitname

This message is a not a cause for concern for DSIEXnn exits unless you expect a
particular exit to load that did not load.

Installing an Installation Exit Routine

Link edit the installation exit routine load module into the NetView load library.
For global installation exits, use the appropriate DSIEXnn name. For DST
installation exits, use a name that you select. Use only one load module for each
routine. Conditional selection upon exiting is not valid.

56 Programming: Assembler
 Writing Installation Exit Routines

Global installation exit routines are automatically loaded when the NetView
program starts. DST installation exit routines are loaded when the DST starts,
provided you have specified them on the DSTINIT statement.

See “Testing Your Program” on page 1 for information about testing your exit
routine before use.

Template for an Installation Exit Routine

The basic structure of an installation exit routine, including standard entry and exit
linkage, is available in a template as part of the NetView sample library. This
template runs as written for any of the NetView installation exits. However, no
functions are performed until you add your code at the designated place in the
template. The template can be found as member CNMS4282 of the CNMSAMP
data set.

Chapter 3. Writing Installation Exit Routines 57

58 Programming: Assembler
Chapter 4. Writing Command Processors
This section describes designing, coding, and installing the assembler language
command processors for the NetView program. Command processors perform a
particular service or function, such as extracting relevant data from a control block
and presenting the data to an operator.

Types of Command Processors

Command processors run in any of several execution environments, determined by
the command processor's type, defined by the CMDDEF statement in CNMCMD or
its included members. The CMDDEF statement identifies the command processor
as one of the following types:
TYPE=R
Regular commands
TYPE=H
High-priority commands
TYPE=I
Immediate commands
TYPE=D
Data services commands
TYPE=B
Regular and immediate commands combined
TYPE=RD
Regular and data services commands combined

In addition, long-running commands are composed of regular (or type RD or type

B) commands. Parts of long-running commands are coupled by their internal
processing.

Regular Command Processors

A regular command runs under the operator station task (OST), NetView-NetView
task (NNT), or primary program operator interface task (PPT). A regular command
receives control with the TVBINXIT bit set off. This means that the NetView
program and VTAM exit routines, and immediate command processors, can
interrupt the processing of a regular command.

For specific coding instructions, see “Writing a Full-Screen Command Processor”

on page 65 and “Calling the Command Processor” on page 16.

High-Priority Command Processors

A high-priority command processor is the same as a regular command processor
except that type H commands are queued at high priority regardless of the setting
of CMD priority on the DEFAULTS and OVERRIDE commands.

© Copyright IBM Corp. 1997, 2015 59

Writing Command Processors

Immediate Command Processors

An immediate command runs under the OST and NNT environments. Unlike
regular commands, immediate commands receive control with the TVBINXIT bit
set to on. This means that they interrupt mainline processing and cannot be
interrupted by another command.

An immediate command starts processing as soon as an operator enters the

command, regardless of any regular command currently running. The requested
function is performed, even if the task is in the middle of a large queue of work.

Data Services Command Processors

A data services command processor (DSCP) runs under the data services task
(DST) environment. DSCPs perform communication network management (CNM)
data services using the DSIZCSMS macro, VSAM data services using the
DSIZVSMS macro, or both services. DSCPs are also appropriate for centralized or
serialized user-defined functions that do not use CNM or VSAM services. See
“Data Services Command Processor” on page 88 for details.

Combination Command Processors

One type of combination command processor runs as a regular or immediate
command, depending on its environment. This command processor checks the
TVBINXIT bit and processes the command as an immediate command if the bit is
on or as a regular command if the bit is off.

Another type of combination command processor runs as a regular or data services

command, depending on the task type indicated in the task vector block (TVB). If
the task type is DST, the command runs as a data services command. Otherwise,
the command runs as a regular command.

Long-Running Command Processors

A long-running command (LRC) processor enables other processing to continue
after a command begins processing. The DSIPUSH macro provides for continuation
by the same or another processor under varying conditions. The caller of the
original command can run after that command returns. Other processing, such as
messages, can occur between the calls to the various parts of the LRC processor.

LRC processors run under an OST, NNT, primary POI tasks (PPT), or DST (logoff
routines only). Your operator can call an LRC processor using a command
procedure, or an LRC processor can be called by another LRC processor. The LRC
processors return control to the NetView program after scheduling work but before
processing is complete. The NetView program then processes other work that is
pending. Only long-running commands can act as a NetView component,
suspending for unrelated operator commands, including ROLL, and resuming, in
turn.

LRC processors are often used to retrieve data from another task or from another
domain without enabling the calling function or calling command procedure to
proceed in the midst of this retrieval. During this retrieval, the task of the
processor can continue to receive messages and accept commands.

For specific coding instructions, see “Calling the Command Processor” on page 16.

60 Programming: Assembler
 Writing Command Processors

Unattended and Attended Operator Task Command

Considerations
Command processors using DSIPSS TYPE=ASYPANEL or other full-screen
functions must test the TVBAUTOO bit. If this bit is 1, full-screen mode is not
permitted. TVBAUTOO indicates an unattended or attended operator task.

Designing and Coding a Command Processor

Command processors adhere to the guidelines for user-written programming
described in “General Coding Guidelines” on page 4. Additionally, command
processors conform to the special requirements described in this section. After
coding your command processor, follow the instructions in “Installing a Command
Processor” on page 76.

To accommodate error recovery, test the TVBRESET flag set by the RESET
command. You can code your command processor to examine this flag regularly
and to end prematurely if the flag is on.

Keep in mind that an OST, NNT, PPT, or autotask can be receiving work (for
example, DOMs) which you can be unaware of. Failure to process that work can
result in a filling of the task's message queues, and the task can receive message
DSI374A, indicating that the buffers threshold for the message queue has been
reached.

Therefore, if you are coding a command processor for an OST, NNT, PPT, or
autotask and it is going to run for an extended period, the command processor
should be an LRC processor. An LRC processor returns control to the NetView
program after scheduling work, but before processing is complete. The NetView
program then processes other work that might be pending.

Input to the Command Processor

When the command processor gains control, the registers contain the following
information:

Register Contents
0 Undefined when command is first called; storage address for resume
routines for long-running commands.
1 The address of the command work block (CWB). The CWB contains the
following information:
v A user save area (CWBSAVEA) that is the command processor's
72-byte save area.
v The address of the command buffer (CWBBUF) for a command call.
This field is 0 for a RESUME, abend reinstate, or LOGOFF call.
v The address of a service work block (SWB) for calling service
facilities (CWBSWB).
v The address of a parse descriptor block (CWBPDB) if the following
are true:
– CWBBUF does not equal 0
– PARSE=Y was specified (or defaulted to) in the CMDDEF
statement of the command processor
If PARSE=N is specified, the CWBPDB equals 0 (zero).
v A work area (CWBADATD) that is the command processor's 256-byte
temporary storage for keeping variables while remaining reentrant.

Chapter 4. Writing Command Processors 61

Writing Command Processors

Register Contents
2-12 Unspecified.
13 The address of a standard 72-byte save area used to store the caller's
registers.
14 The return address.
15 The entry address of the command processor.

When a command results from the NetView automation table, the TVBAIIFR field
contains the address of the message buffer structure that is automated. If
TVBAIIFR=0, the command did not result from an automated message or MSU.
See Figure 5 for an example of an automation internal function request buffer
structure.

CWB BUFHDR Command

PDB String

TVB CWBBUF

CWBPDB PDBBUFA

CWBSWB

IFR
TVBAIIFR BUFHDR SWB
HDRMCEXT

IFRCODE

IFRAUIND
IFRAUACT

IFRAUTBA BUFHDR Message or MSU data

IFRAUTBL

BUFHDR Message or MSU data

IFRAUTA1

IFRAUTA2 BUFHDR Message or MSU data

IFRAUVPT DSIAIFRO
Obj 2

DSIAIFRO
Obj 3

Figure 5. Automation Internal Function Request. An example of a buffer structure when a

command processor is driven from an automation statement in the NetView automation table.
If TVBAIIFR=0, this command is not driven by an automation statement.

Output from the Command Processor

When the NetView program regains control, the registers and their contents are as
follows:

62 Programming: Assembler
 Writing Command Processors

15 A return code
0-14 Restored to caller's contents

If a regular command processor is called by a command procedure (in NetView

command list language, REXX, or, high-level language), the return code is made
available to the caller (&RETCODE, RC, HLBRC, respectively). The NetView
program makes no other use of the return code.

For an immediate command, the NetView program ignores the return code.

For an LRC processor, the completion code is specified on the DSIPOP macro
invocation. See “DSIPOP: Remove Long-Running Command” on page 211 for more
information about the DSIPOP macro. The register 15 return codes returned upon
command resumption indicate processing options. See “Message STIFLE” on page
72.

Control Blocks
Command processors usually access a command buffer and seven control blocks:
CWB, PDB, SWB, TVB, TIB, MVT, and SVL. In addition, type RD command
processors, running under a DST and type D command processors, require the
DSRB. Further, a command driven with NetView automation can require the
automation internal function request (AIFR). The command buffers CWB, PDB,
SWB, DSRB, and AIFR are specific to the command being run. The TVB and TIB
are global to the task, and the MVT and SVL are global to the NetView program.

Figure 6 on page 64 illustrates an example of the required control blocks and their
relevant pointers. For detailed descriptions of these control blocks, see Chapter 7,
“Control Blocks,” on page 103.

Chapter 4. Writing Command Processors 63

Writing Command Processors

Register 1 HDRMLENG = 24
HDRBLENG = 104
HDRMTYPE = HDRTYPET
HDRDOMID = DOM1
HDRTSTMP = X'1314150C'
HDRTDISP = 36

CWB

0 24 36 Command Buffer 104

CWBBUF BUFHDR ROUTE D2, LIST STATUS=OPS

CWBPDB

CWBSAVEA PDB

CWBTIB SCE

CWBSWB PDBCMDA ROUTE

CWBADATD DSRB PDBBUFA DSIRTP

CWBDSRB PDBLENG PDBTYPE PDBDISP SCECADDR

5 36
2 42
4 45
6 50
3 57
SWB

Displacement of
entry in buffer
Type of delimiter
SWBTIB
Length of each element of command

TIB TVB MVT SVL

TIBTVB TVBMVT MVTSVL

Figure 6. Example of Control Blocks Used by Command Processors. The NetView control
block header appears at the beginning of the CWB, DSRB, MVT, PDB, SVL, TIB, and TVB.

The v character is shown only as a place holder in the figure, because the character
used to represent the first, third, and fifth PDBTYPE delimiters does not reproduce
properly on all output devices. The delimiter is a blank, normally represented as a
lowercase b with a slash (diagonal line) running through the letter from lower left
to upper right (�).

Figure 7 on page 65 shows sample code to access a command buffer.

64 Programming: Assembler
 Writing Command Processors

L R3,CWBPDB GET ADDRESS OF PDB

USING DSIPDB,R3 R3 IS BASE FOR PDB
LA R4,PDBTABLE GET ADDRESS OF PDB TABLE
USING PDBENTRY,R4 R4 IS BASE FOR A PDB ENTRY

* First PDB entry is for command name

CLC PDBNOENT,=H’1’ ANY COMMAND PARAMETERS ENTERED?

BNH ............. NO, GO HANDLE THIS SITUATION

* Process 1st parameter after command name

LA R0,PDBENTND-PDBENTRY GET LENGTH OF PDB ENTRY

AR R4,R0 BUMP PAST COMMAND NAME ENTRY

CLI PDBLENG,0 WAS ONLY A DELIMITER SPECIFIED?

BE ............. YES, GO HANDLE THIS SITUATION

L R2,CWBBUF GET ADDRESS OF COMMAND BUFFER

AH R2,PDBDISP POINT TO PARM IN BUFFER
SLR R1,R1 CLEAR LENGTH REGISTER
IC R1,PDBLENG GET LENGTH OF PARM

...... application code to process parm ............................

CLC PDBNOENT,=H’2’ MORE COMMAND PARAMETERS ENTERED?

BNH ............. NO, GO HANDLE THIS SITUATION

* Process 2nd parameter after command name

LA R0,PDBENTND-PDBENTRY GET LENGTH OF PDB ENTRY

AR R4,R0 BUMP TO NEXT ENTRY

CLI PDBLENG,0 WAS ONLY A DELIMITER SPECIFIED?

BE ............. YES, GO HANDLE THIS SITUATION

L R2,CWBBUF GET ADDRESS OF COMMAND BUFFER

AH R2,PDBDISP POINT TO THIS PARM IN BUFFER
SLR R1,R1 CLEAR LENGTH REGISTER
IC R1,PDBLENG GET LENGTH OF PARM

...... application code to process parm ............................

* Process nth parameter after command name

Figure 7. Sample Code to Access a Command Buffer

Writing a Full-Screen Command Processor

A full-screen command processor (FSCP) is a regular command processor that
presents a full screen of data to an operator's terminal and runs only under an
OST. For line-by-line presentation to an operator's terminal, see “Displaying
Information to NetView Operators” on page 12.

An FSCP uses DSIPSS TYPE=ASYPANEL to present data. With long-running

command support, you can code an FSCP to enable additional OST work requests
to be processed without ending the full-screen presentation. Issue DSIPSS
TYPE=ASYPANEL with both output data and input parameters specified in the
PANEL parameter list. If you use separate DSIPSS TYPE=ASYPANEL macros for
output and input, operator-input data might be discarded before the input DSIPSS
can be processed.

Chapter 4. Writing Command Processors 65

Writing Command Processors

An FSCP can issue the DSIPSS macro to request input and then perform other
work before issuing DSIPSS TYPE=PSSWAIT to receive the input. In addition, an
FSCP has direct access to operator input and can use the DSIWAT macro to
synchronize an operator scenario.

The issuer of the DSIPSS TYPE=ASYPANEL request can use DSIPSS

TYPE=PSSWAIT to wait on important NetView event control blocks (ECBs) such as
the termination ECB, the solicited POI ECB, the cross-domain ECB, message ECBs,
the reset ECB, and the user ASYPANEL ECB. When control is returned from the
PSSWAIT, a return code of 56 indicates a NetView ECB has been posted. If you
expect the action of your input to be short (for example, QUIT), first check your
ASYPANEL ECB. The value of the post indicates the status of the DSIPSS
TYPE=ASYPANEL request. See information about the post codes in “Return Codes
in Register 15” on page 221.

Screen Formatting for the 3270 Data Stream

Because the FSCP is responsible for the 3270 data stream, the processor issues the
DSIPSS macro with TYPE=SCRSIZE to find the presentation space dimensions. If
the result is larger than 24 by 80 characters, the processor can use the 3270
Erase/Write Alternate command. Otherwise, it must use the Erase/Write
command.

When the processor issues DSIPSS with TYPE=SCRSIZE for a terminal that uses
14-bit or 16-bit addressing and query support (indicated in the logmode definition),
the returned and actual screen size can be larger than the alternate screen size. If
so, when you use the Erase/Write Alternate command to address the parts of the
screen outside the alternate screen size, a terminal program checks the results. To
avoid this problem, do either of the following commands:
v Use a 24 x 80 character screen image data stream and use the Erase/Write
command instead of the Erase/Write Alternate command.
v Use a Write Structured Field command to create a partition-structured field that
controls the buffering in the terminal.

Note: For more information about the 3270 data stream and buffering, refer to the
IBM 3270 library.

Requesting Input
You do not need to send READ instructions to the terminal. A READ MODIFIED
command is set up and run whenever your operator uses an AID key. To receive
the data, specify an input buffer and an input ECB on a DSIPSS TYPE=ASYPANEL
request. When asking for input, check that the operator's keyboard is unlocked (set
bit 6 of WCC to '1'B). Do this with the same DSIPSS invocation that requests the
input or with an earlier one. You can also choose to reset the modified data tags.
After requesting input, do not request input on a further DSIPSS
TYPE=ASYPANEL request until your ECB is posted.

Posting an ECB
Do not free the storage where your input buffer and ECB reside until the ECB is
posted. When necessary, you can force the ECB to be posted early by issuing
DSIPSS TYPE=CANCEL. After you issue DSIPSS TYPE=CANCEL, the operator
cannot use the terminal until another input request is made or until a DSIPSS
TYPE=OUTPUT request restores the command facility panel.

66 Programming: Assembler
 Writing Command Processors

When an FSCP sends a full screen of data to the display terminal, the system reads
the 3270 data stream into the buffer area. The FSCP can then write more data to
the screen while the operator is viewing or entering data. However, avoid writing
over or erasing the operator's input areas.

When the data is read, the NetView program posts an ECB. The command
processor processes the input and, optionally, presents more full-screen panels.
While the FSCP has a read outstanding, input to the terminal is treated as input to
the command processor, not to the NetView program.

When the command processor is called, it reads and writes to the terminal using
DSIPSS TYPE=ASYPANEL. The PANEL parameter of DSIPSS points to a 20-byte
parameter list. See “DSIPSS: Presentation Services” on page 216 for details about
this process.

Waiting for Lists of Events

The DSIPSS macro with TYPE=PSSWAIT enables the FSCP to wait for both its own
list of events and another list of events, such as important messages. The FSCP can
interrupt its own processing to receive these lists of events. After waiting, the
command processor tests the return code to determine if its ECB was posted or if a
NetView ECB was posted. If the return code shows that a NetView event is
completed, the command can return to the NetView program to enable the
processing of the event. If the ECB panel is posted, the FSCP processes the input in
the buffer. In this way, the command processor has complete control of the screen
format. The command processor returns to the NetView program after saving the
screen status to enable future processing. The FSCP can specify a RESUME routine
(using DSIPUSH) to enable the full-screen presentation to resume.

The reshow option permits an operator to retain previously saved screen data. You
can suspend and resume full-screen processing by using the DSIFIND, DSIPOP,
and DSIPUSH macros and by specifying a RESUME routine.

Testing for Posted Events

The DSIPSS macro with TYPE=TESTWAIT helps the command processor to test
whether a NetView event is already posted. You can use this option before issuing
DSIPSS TYPE=ASYPANEL to avoid performing input or output processing when a
NetView event is already posted. This option enables early detection of
interruptions. With this option, you can also return to the NetView program with a
minimum of screen interruptions. For more information about DSIPSS, see the full
description of the macro and its attributes in “DSIPSS: Presentation Services” on
page 216.

Logging Full-Screen Input and Output

The NetView program does not automatically log full-screen input and output. Use
the DSIWLS macro to log pertinent data.

Accommodating Responses and Interruptions

When you write a panel to the terminal, provide operator response by specifying
an ECB address and READ buffer with at least one of your output requests. This
provides your program with all of the input from the terminal.

Note: The NetView program treats power-off and power-on procedures and the
attention signal as error conditions. For powering off and powering on, your ECB
is posted for a permanent error and your OST is placed in termination status. The
ECB is not posted until the NetView program is notified that the terminal is

Chapter 4. Writing Command Processors 67

Writing Command Processors

powered off. The signal that results from the Attention key causes the NetView
program to set TVBRESET. Your PSSWAIT also ends.

The program command processor responds to PF3 by terminating your FSCP. If

you want your FSCP to make a temporary exit under other conditions, you must
have previously prepared for resumption using DSIPUSH.

You do not need to use TYPE=PSSWAIT when you do not want interruptions, such
as messages and their resulting automation, or to process cross-domain commands.
The command processor can wait on its own list of ECBs. Even if you choose not
to wait on other NetView events, include the OST termination ECB in the list. This
ECB is located in the TVBTECB field of control block TVB. TVBTECB enables the
command processor to be aware of any major condition requiring the command
processor to clean up and exit. Use only the ECBLIST parameter with
TYPE=PSSWAIT in DSIPSS.

Changing FSCP Characteristics

The DSIPSS macro with TYPE=CANCEL makes it possible for you to change
characteristics of the FSCP. These characteristics include the input area length and
the ECB address. You can issue TYPE=CANCEL when a DSIPSS TYPE=ASYPANEL
is active or inactive. You can also issue TYPE=CANCEL if input from
TYPE=ASYPANEL is posted as complete or is not yet complete.

However, issue DSIPSS TYPE=CANCEL only when a program is going to free up

or change the storage areas used for output, input, ECB or parmlist for a
previously issued DSIPSS TYPE(ASYPANEL). Usually, this does not occur until the
program is going to end. If this FSCP is long running, “ending” includes issuing a
DSIPOP and returning to the NetView program. Issuing further CANCELs can
result in operator input being discarded between the CANCEL and the next
TYPE(ASYPANEL) or TYPE(OUTPUT).

Note: If a program must run on NetView V3 or earlier, run MVTVER to determine

which version is used.

Issue TYPE=CANCEL because you cannot guarantee that the operator will enter
data on any given panel. If an active ASYPANEL input request is canceled, the
system posts the ECB with a special post code. See information about the ECB post
codes in “Return Codes in Register 15” on page 221. The storage where the
ASYPANEL ECB is located must not be freed until a DSIPSS TYPE=CANCEL is
issued or the NetView program has posted ASYPANEL ECB for successful or
unsuccessful input.

Writing a Long-Running Command Processor

Long-running command (LRC) processors use the DSIPUSH, DSIFIND, and
DSIPOP macros to synchronize the order in which functions are processed so that
asynchronous events run in sequence or in parallel. An LRC processor
synchronizes functions so that the programs it initiates complete before it ends and
its callers do not resume until after it ends.

DSIPUSH identifies three routines that provide for command resumption, and
recovery and termination. These routines are the RESUME routine, the abend
reinstate routine, and the LOGOFF routine. DSIFIND locates the storage you
associated with the DSIPUSH input name. DSIPOP indicates that a long-running
command has completed.

68 Programming: Assembler
 Writing Command Processors

When one of these routines receives control, CWBBUF is set to 0 and the register 0
contains the storage pointer associated with the long-running command (0 if no
storage). Additionally, one of the following bits are set:
v For a RESUME routine, the TVBRESUM bit is set to on.
v For an abend reinstate routine, the TVBABEND bit is set to on.
v For a LOGOFF routine, the TVBLOGOF bit is set to on.

Notes:
1. The TVBRESUM, TVBABEND, and TVBLOGOF flags are meaningful only
when your input CWBBUF address is 0.
2. HLL command processors cannot be pushed (with DSIPUSH) as ABEND,
LOGOFF, or RESUME routines.

The other registers contain the information described in “Input to the Command
Processor” on page 61.

When a RESUME, abend reinstate, or LOGOFF routine returns control to the

NetView program, all registers must be restored. You need to set register 15 to tell
the NetView program what action to take, as described in the following sections.

RESUME Routines
Before invoking any subordinate command processors or command lists, and
before issuing DSIPSS TYPE=PSSWAIT (or TESTWAIT), the LRC processor
schedules a RESUME routine (using DSIPUSH). The RESUME routine suspends
any other active LRC processors and enables the LRC processor to regain control.

The first request at the top of the long-running command chain defines the
controlling RESUME routine. If you use DSIPUSH while another RESUME routine
is in control, the new RESUME routine becomes the controlling routine. All other
RESUME routines are temporarily suspended.

The suspension period depends on the environment from which the long-running
command received control. If the long-running command was called because of an
asynchronous event, such as an operator command or the automation of a
message, then the NetView ROLL command, if issued, can move (rotate) the
long-running command to the bottom of the long-running command chain. This
gives control to the next long-running command. If the long-running command
received control by direct call from another long-running command, the two
commands are regarded as being related by that direct call. This includes direct
commands from NetView command list language, REXX, and high-level language
command procedures. The ROLL command, if issued, acts against both (or all)
such related commands as a group, moving them altogether and preserving their
order. In either case, DSIPOP can remove the topmost RESUME routine, giving
control to the next long-running command.

Note: Neither the ROLL command nor DSIPOP causes an asynchronous interrupt.
A command gives up control only by returning to its caller, except for the action of
immediate commands.

You can also use DSIPOP to remove (by name) a RESUME routine that is not at
the top of the stack of the long-running command chain. This action is regarded as
a cancellation of that long-running command unless your DSIPOP invocation
specifies COMPCDE. If the long-running command that was removed was part of
a larger group, the calling long-running command is given control, as soon as the
current process permits, and is given a cancel indication, as follows:

Chapter 4. Writing Command Processors 69

Writing Command Processors

v NetView command list language command lists are stopped

v REXX command lists receive a HALT
v All others receive a -5 return code

Note: Refer to IBM Tivoli NetView for z/OS Programming: PL/I and C for more
information about cancelable and noncancelable high-level language command
procedures.

Long-Running Commands
All command procedures are long-running commands. A command procedure's
RESUME routine blocks RESUME routines pushed earlier, exactly like other LRC
processors. A pause or wait state for a command procedure is no exception.

DSIPUSH for a RESUME routine is either major or minor. A major DSIPUSH

places the new RESUME routine at the top of the LRC processor stack, suspending
previously issued long-running commands. A major DSIPUSH is used with
NetView command list language processors. A minor DSIPUSH places the new
RESUME routine on the stack after any leading command procedures (in the same
group), and enables the leading command procedures to complete before the new
RESUME routine gains control. Command procedures already suspended by other
LRC processors are not affected.

You can use a major DSIPUSH to suspend a command procedure until your LRC
processor runs a DSIPOP. You can use a minor DSIPUSH to enable a calling
command procedure to complete, after which your RESUME routine gains control.
The following list describes completion codes and return codes:
v Completion codes
A long-running command can return a completion code to the long-running
command that called it (in the same group) by specifying a value for the
COMPCDE keyword in the DSIPOP macro. If a long-running command was
called asynchronously, the value specified for COMPCDE is ignored. The
completion code is passed to the calling long-running command in CWBRCODE
upon resumption.
v Return codes
A RESUME routine can return control to its caller many times before it
completes, to provide messages, queued commands, called long-running
commands, and other asynchronous work to process. Upon the initial return
(when commanded, CWBBUF¬=0), the value in register 15 is ignored. After each
resumption, the value in register 15 conveys the long-running command
requirements for STIFLE. For an explanation of STIFLE, see “Message STIFLE”
on page 72. Register 15 = -8 requests stifle; register 15 = +8 requests no stifle.
Meanings for other return codes are reserved. For compatibility with prior
releases, a zero (0) return code is valid after DSIPOP is issued to remove the
long-running command from the stack.

An important part of any RESUME routine function is screen control. Because the
state of the operator's terminal is not known (see “Screen Identifier” on page 74)
on entry, the RESUME routine must ensure that the operator is not locked out by a
panel left over from a previous LRC processor. Ensuring this situation can mean
issuing a message (DSIPSS TYPE=FLASH) to guarantee that the command facility
panel and command line are available to the operator. Ensuring this situation can
also mean displaying a full-screen panel (DSIPSS TYPE=ASYPANEL). The screen
control requirement means that you cannot use the DSILRCR8 routine supplied by
the NetView product as a RESUME routine with the NetView program, as was

70 Programming: Assembler
 Writing Command Processors

sometimes appropriate with NCCF. You can use DSILRCR8 as an abend reinstate
or LOGOFF routine if no cleanup besides DSIPOP is needed.

Issuing Messages Upon Resumption

When you use messages for screen control, issuing a message on every resumption
is excessive and can cause looping if the message is automated or routed. Use the
screen serial number (TIBSCRSN) to determine when to issue messages upon
resumption. Be especially cautious when issuing VTAM messages upon
resumptions under the PPT, because all messages are routed and can generate new
activity under the PPT. This new activity disrupts VTAM message reception that
the NetView program might be performing.

To assist RESUME routines that display panels, the NetView program provides
status information through the TIBSCRID field (see “Screen Identifier” on page 74).

A completed RESUME routine (one that has issued DSIPOP against itself) does not
need to be concerned with screen control because the following RESUME routine
assumes responsibility. Ending messages (associated with NCCF) that are issued
when an LRC processor finishes are not appropriate in the NetView program.

With the NetView program, operators can recover from operator errors and certain
program errors through the use of the attention signal or the RESET (NORMAL)
command. When attention is signaled or the RESET command issues a flag,
TVBRESET is set, and an ECB, TVBRESET, is posted. All commands, and especially
LRC processors, can test TVBRESET regularly. Whenever it is set, the command
ends its processing (using DSIPOP, if appropriate) and returns to the NetView
program.

The following steps illustrate the use of the DSIPUSH and DSIPOP macros:
1. A command list calls a command and, to complete the request, the command
processor requests data from a DST.
2. The command processor issues DSIPUSH specifying a RESUME routine. At
this point, the command processor becomes a long-running command.
3. The command processor uses the DSIMQS macro to queue a buffer with
IFRCODE set to IFRCODCR containing its request for data to the DST.
4. The command processor returns to its caller. The terminal remains in the state
it was in when the command list was running. In this case, the command
facility panel is displayed.
5. This operator's task is idle (the command list is suspended by DSIPUSH);
therefore, the RESUME routine defined earlier by DSIPUSH is immediately
called.
6. The command processor finds that CWBBUF=0 (no command is being passed)
and TVBRESUM is set, but TIBLRCNP is not set. The command processor
returns control to its caller.
7. A message is received and displayed. The command processor is called again
as a RESUME routine.
8. The operator issues a full-screen command, which issues its own DSIPUSH
and waits for input.
9. The operator exits (or rolls away from) this latter command processor.
10. The panel of the second command processor remains in place, and the original
command processor RESUME routine is called. This time TIBLRCNP is set.
The command processor issues a FLASH message: STILL WAITING FOR DATA.
The command facility panel is restored by DSIPSS.

Chapter 4. Writing Command Processors 71

Writing Command Processors

11. An IFRCODCR buffer containing the DST reply is received. After issuing the
DSIFIND macro, the IFRCODCR command processor places data in the LRC
processor's long-running command storage (as defined in the original
DSIPUSH). The IFRCODCR command processor only saves the data because
another long-running command can be in control.
12. The command processor is resumed again. Finding its data request satisfied, it
completes its function and issues DSIPOP against itself, using the COMPCDE
keyword on DSIPOP to indicate the nature of the completion. The command
processor returns a return code of 8 in register 15.

Note: For compatibility with prior releases of the NetView program, a zero (0)
return code is acceptable after DSIPOP is issued to remove the long-running
command from the stack.
13. The NetView program calls the next RESUME routine, the command list
invoking the original command, which then continues.
14. The command list receives the return code (RC in REXX or &RETCODE in
NetView command list language) that was specified for COMPCDE on
DSIPOP.

You can set a RESUME routine to return control to the NetView program without
giving up control of the operator's display. For example, the screen can be
dynamically updated based on information sent by another task in the form of an
IFRCODCR message. (See “DSIIFR: Internal Function Request” on page 120.) To
assist with such a function, the NetView program provides two tools: message
STIFLE and a screen identifier.

Message STIFLE
A RESUME routine can request a message STIFLE when it returns control to the
NetView program, indicating that ordinary line mode messages are not displayed
and the operator‘s screen is not disturbed by the processing of the messages.

Some messages are displayed by the NetView program whether or not STIFLE is
in effect. These messages are said to break the stifle mode. The following messages
can break the stifle mode:
v Action messages with ISTnnnA or DSInnnA identifiers.
v Messages that request a reply (HDRTYPEY, except the ASSIGN=COPY of
HDRTYPEY that does not break STIFLE).
v Any message issued with DSIPSS TYPE=FLASH. The intended use of DSIPSS
TYPE=FLASH is for command echoes and screen control messages.

If STIFLE is broken, it remains off until reissued by a RESUME routine.

A stifle request can be honored only while the network log or the hardcopy log
remains active. The NetView program counts messages that are stifled and
displays message DSI593I to remind the operator that it is necessary to consult the
network log or hardcopy log to see these messages. A stifle request is not honored
while the command facility panel is in place. The request is not honored because
the NetView program assumes that the LRC processor gains control of the panel
through the use of DSIPSS TYPE=ASYPANEL before requesting STIFLE.

STIFLE affects only line-mode messages. A full-screen display is not affected. If, for
example, the result of a START DOMAIN command (the logon panel) is delayed
long enough for an LRC processor to gain control, the returning logon panel is
displayed without regard to the STIFLE.

72 Programming: Assembler
 Writing Command Processors

ROLL Function
With a roll group, the operator can switch from one component, such as the
hardware monitor, to another component, such as the session monitor, and return
to the place at which the operator last left the component. This procedure is similar
to window processing in other applications.

A roll group is a set of related DSIPUSH macro requests. DSIPUSH begins a new
roll group when it is called from an asynchronous command environment.
Operator commands, commands generated by automation, and commands
scheduled using DSIMQS are asynchronous. A command called directly from
another long-running command is synchronous. The synchronous long-running
command is added to the roll group started by the asynchronous long-running
command and blocks it until a DSIPOP request is issued against the synchronous
long-running command. The current roll group is defined as the roll group that is
first on the long-running command chain.

The ROLL command treats each specified roll group as a unit when manipulating
the chain. The ROLL command moves the topmost roll group to the bottom of the
stack. All elements within the roll group maintain their position within the group.

For additional information about using the ROLL command, refer to the NetView
online help.

Roll Group Usage

The simplest roll group is a command that calls DSIPUSH with a RESUME routine.
The RESUME routine enables the command processor to respond to a ROLL
request. If this command accepts command input from the operator (with DSIPSS
TYPE=ASYPANEL), a ROLL command causes the long-running command to move
(rotate) to the bottom of the long-running command chain. When the ROLL
command rotates another long-running command similarly to the bottom of the
long-running command stack (or the long-running command ends with DSIPOP),
the RESUME routine regains control.

You can use multiple DSIPUSH requests with different RESUME routines or
different storage pointers for such procedures as implementing a hierarchical panel
structure. By scrolling forward and then backward, the operator returns to the
same panel that was previously displayed. When a panel ends (that is, the operator
uses PF3, and the program calls DSIPOP), the operator returns to the panel within
the hierarchy, that is, above the current panel.

The following steps describe how a full-screen function uses the ROLL capability:
1. Issue DSIPUSH for a RESUME routine.
2. Provide a line on your panels for NetView command input, using 3270 data
stream orders.
3. When the operator enters data on the command line, the input data stream
contains orders that identify the area of the panel in which the operator typed.
4. Use the DSICES macro to verify the command. When command entry is
detected,verify the command, build a standard NetView buffer with
HDRMTYPE=HDRTYPET, and issue the DSIMQS macro to send the buffer to
the operator's own task, using TVBOPID as the destination of the DSIMQS.

Note: You must translate the command input to uppercase if the language the
operator is using has uppercase and lowercase characters.
5. Return to the NetView program to enable the command to be processed.

Chapter 4. Writing Command Processors 73

Writing Command Processors

6. The NetView program reissues your RESUME routine when the command has
completed processing and when your RESUME routine is the first routine on
the stack or the current roll group.
If the command entered was ROLL, the ROLL command processor
automatically switches your roll group to last.
If the command entered establishes a new roll group, your roll group is pushed
down on the stack and the new group becomes current. When the operator
exits from the new roll group, your roll group is called by NetView calling the
topmost RESUME routine.
7. You can also detect PF6 and PF18 as ROLL. You build the command buffer, but
you must look up the command name for the DSIROLL load module using the
DSICES macro and then issue DSIMQS to queue the buffer.
8. So that the operator can switch directly to your function from a different roll
group without ROLL, you can define a command as a reshow request. It can be
the command name for your function with no operands provided.
When your command processor is entered (with no operands) with reshow
requested, issue DSIPUSH with PROMOTE=YES to move your roll group to the
top of the stack. Proceed by refreshing the screen from the last panel the
operator viewed.
Issuing DSIPUSH with PROMOTE=YES exchanges the storage address in the
DSIPUSH parameter list with the one already associated with the named
request, and returns the old value in register 0. Therefore, you can issue
DSIFIND to determine the current address and specify it on the
PROMOTE=YES request to make sure that the address stays the same. If you
do not specify the address, the 0 value in the parameter list replaces the current
value.

Screen Identifier
Requesting STIFLE does not guarantee that an LRC processor's panel is not
modified, but the NetView program provides a way to determine whether
modifications occurred. After writing the panel to the screen, an LRC processor
saves the value of TIBSCRID. Upon regaining control, a RESUME routine can
compare the present and saved values of TIBSCRID to determine whether–and to
some extent, what type of–screen modifications occurred since it last had control.

TIBSCRID, a 4-byte field, consists of two subfields:

v TIBSCRSN
Specifies the low-order 3 bytes that form a serial number for the screen's
contents. This number is incremented whenever anything is sent to the screen
that changes what the operator sees.
v TIBSCRM
Specifies the high-order byte that is a state change indicator. A change in
TIBSCRM usually means a DSIPSS TYPE= CANCEL request was issued. A
change can also mean that a Lock Keyboard or other non-data 3270 command
was sent to the terminal.

When an LRC processor regains control and TIBSCRID is unchanged, the LRC
processor can resume processing as if it had never lost control.

When TIBSCRM (and not TIBSCRSN) is changed, the LRC processor reestablishes
its read by issuing DSIPSS TYPE=ASYPANEL to send a Write and Unlock
command (X'F182') to the terminal and re-specify the ECB, if any, by which the
long-running command waits for input. This procedure makes refreshing the
screen unnecessary.
74 Programming: Assembler
 Writing Command Processors

When TIBSCRSN is changed, some visible modification to the LRC processor's

panel is made. You must rewrite the entire panel.

Abend Reinstate Routines

An abend reinstate routine performs a required recovery action, such as freeing
control blocks, after the NetView program recovers from abend of a task. You
cannot use abend routines while running under the DST because DSTs are not
reinstated after abends. While running under the DST, use a LOGOFF routine
instead.

The abend routine assesses the damage caused by an abend and either keeps or
cancels the long-running command. Each command in the stack must be associated
with an abend reinstate routine. With its return codes in register 15, the abend
routine notifies the task whether the command is to be kept or removed from the
queue and freed, as follows:
Code Meaning
0 Keep the long-running command request queued
8 Remove the currently queued long-running command request from the
queue

If the routine keeps a long-running command, the RESUME routine runs the first
time that the task has no other work to perform. All stacked long-running
command routines are maintained in their current order. Abend reinstate routines
cannot issue the DSIPOP or DSIPUSH macros.

When a task recovers from an abend, all abend reinstate routines are called,
starting with the top one in the stack, which is the most recent. When the abend
reinstate routine returns to its task, it specifies whether the associated command is
to remain on the stack or be removed.

LOGOFF Routines
A LOGOFF routine gives the command processor control before the task ends. The
task is not reinstated, and the command processor can perform any final cleanup
processing, such as closing a data set or freeing storage. Each command in the
stack must contain a LOGOFF routine.

A LOGOFF routine is called sequentially for each request on the queue. LOGOFF
routines cannot issue the DSIPOP or DSIPUSH macros.

When the command processor returns to the task, requests are taken off the queue
and freed.

All return codes for LOGOFF routines are ignored.

When a task ends, all the LOGOFF routines are called starting with the top, or
most recent, request on the stack. Each request is removed from the queue and
freed.

Automation Task Command Processors

When you write commands to run under OSTs, consider the effects of running
under automation tasks and MVS console tasks. These OSTs have the TVBAUTOO
bit set to 1, indicating that immediate commands and full-screen mode commands
are not supported in this task.

Chapter 4. Writing Command Processors 75

Writing Command Processors

Installing a Command Processor

To install a command processor, define the command verbs with CMDDEF
statements as described in IBM Tivoli NetView for z/OS Installation: Configuring
Additional Components. The command processor can also be added dynamically
using the ADDCMD command. For more information on ADDCMD, refer to IBM
Tivoli NetView for z/OS Command Reference Volume 1 (A-N).

If your command processor supports line-mode output (DSIPSS TYPE=OUTPUT),

you can specify ECHO=Y. If your command processor supports full-screen mode
output (DSIPSS TYPE=ASYPANEL), you can specify ECHO=N. Then assemble and
link edit the command processor into a load module in the NetView load library.
The NetView program loads and calls the command processor according to its
linkage editor attributes.

See “Testing Your Program” on page 1 for information about testing your
command processor before using it.

Template for a Command Processor

The following example illustrates entry and exit processing required by all
command processors. This template, a part of the NetView sample library, is
member CNMS4202 of the CNMSAMP data set.
ATMPCMDP CSECT
***********************************************************************
* LICENSED MATERIALS - PROPERTY OF IBM *
* 5697-B82 (C) COPYRIGHT TIVOLI SYSTEMS 1998 *
* 5655-007 (C) COPYRIGHT IBM CORPORATION 1989, 2010 *
* ALL RIGHTS RESERVED. *
* *
* NAME(ATMPCMDP) SAMPLE(CNMS4202) RELATED-TO() *
* MODULE NAME: *
* FUNCTION: *
* SYNTAX: *
* *
* INSTALLATION: *
* *
* MACROS: DSICBS *
* CONTROL BLOCKS: DSICWB,DSIMVT,DSIPDB,DSISVL,DSISWB,DSITIB,DSITVB *
* *
* INPUT: REG 1 - ADDRESS OF COMMAND WORK BLOCK (DSICWB) *
* REG13 - ADDRESS OF CALLER’S SAVE AREA *
* REG14 - RETURN ADDRESS *
* REG15 - ENTRY ADDRESS *
* *
* OUTPUT: *
* REGISTERS: *
* REG 0 - REG14 - RESTORED UPON RETURN *
* REG 15 RETURN CODES: *
* 0 - SUCCESSFUL *
* NETVIEW MACROS: *
* DSICBS - CONTROL BLOCK SERVICE *
* *
***********************************************************************
EJECT
DSICBS DSICWB,DSIMVT,DSIPDB,DSISVL,DSISWB,DSITIB,DSITVB, X
PRINT=NO
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4

76 Programming: Assembler
 Writing Command Processors

R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8 MVT
R9 EQU 9 TVB
R10 EQU 10 TIB
R11 EQU 11 CWB
R12 EQU 12 BASE REG
R13 EQU 13 SAVEAREA
R14 EQU 14
R15 EQU 15
EJECT
***********************************************************************
* *
* SAVE REGISTERS AND ESTABLISH BASE REGISTER *
* *
***********************************************************************
USING *,R15
B PROLOG
DC C’ATMPCMDP &SYSDATE. AT &SYSTIME.’
PROLOG DS 0H
STM R14,R12,12(R13) SAVE REGISTERS
DROP R15
LR R12,R15 SET BASE REGISTER
USING ATMPCMDP,R12
***********************************************************************
* *
* ESTABLISH ADDRESSABILITY TO THE COMMAND WORK BLOCK (CWB) AND SET *
* UP THE SAVE AREA USING CWBSAVEA *
* *
***********************************************************************
LR R11,R1 LOAD CWB ADDR
USING DSICWB,R11 R11 BASE FOR COMMAND WORK BLOCK
LA R1,CWBSAVEA USE CWBSAVEA FOR SAVEAREA
ST R1,8(R13) STORE MY SA INTO CALLERS SA
ST R13,4(R1) STORE CALLERS SA IN MINE
LR R13,R1 R13 HAS MY SAVEAREA ADDRESS
***********************************************************************
* *
* ESTABLISH ADDRESSABILITY TO THE TASK INFORMATION BLOCK (TIB), THE *
* TASK VECTOR BLOCK (TVB), AND THE MAIN VECTOR BLOCK (MVT). *
* *
***********************************************************************
L R10,CWBTIB GET DSITIB ADDRESS
USING DSITIB,R10 ESTABLISH ADDRESSABILITY
L R9,TIBTVB GET DSITVB ADDRESS
USING DSITVB,R9 ESTABLISH ADDRESSABILITY
L R8,TVBMVT GET DSIMVT ADDRESS
USING DSIMVT,R8 ESTABLISH ADDRESSABILITY
*
XC CWBADATD,CWBADATD ZERO AUTODATA AREA
SLR R15,R15 ZERO RETURN CODE REGISTER
***********************************************************************
* MAIN PROCESSING GOES HERE *
***********************************************************************
***********************************************************************
* EXIT *
***********************************************************************
RETURN EQU *
L R13,4(R13) GET CALLERS SAVEAREA ADDRESS
L R14,12(R13) RESTORE REG14
LM R0,R12,20(R13) RESTORE REGS
BR R14 RETURN
SPACE
EJECT
LTORG

Chapter 4. Writing Command Processors 77

Writing Command Processors

EJECT
*
DSICWB DSECT
ORG CWBADATD AUTODATA AREA
DS XL(256-(*-CWBADATD)) AUTODATA LENGTH CHECK
END ATMPCMDP

78 Programming: Assembler
Chapter 5. Writing User Subtasks
This section describes user subtasks and illustrates how to write, process, and
install them.

Types of User Subtasks

The NetView program provides two methods for writing user subtasks. The first
method uses the data services task (DST) interface as a coding base. The DST base
provides interfaces for the following functions:
v An initialization installation exit
v A subtask processing module (DSIZDST)
v CNMI service
v VSAM service
v Data services command processor (DSCP)

The DST provides an ideal structure for user-written tasks because the DST can be
defined with VSAM services, CNM services, or neither service. You can implement
user-defined functions within the data services command processors. The DST
provides all the low-level user subtask functions that you must otherwise code if
you wrote a complete optional subtask (OPT). Write an optional subtask only if
access to the subtask event control block (ECB) processing loop is required.

The other method requires that you code an OPT. With this method, NetView
supplies an intertask communication (message queue) ECB and a termination ECB.
You must provide an appropriate ECB processing loop and any additional
function. This requires more coding than the first method, but it offers more
flexibility in the kinds of functions that you can implement.

Optional Subtask Processing Overview

A user subtask requires the following processes:
Installation
Use the CNMSTUSR or CxxSTGEN member to define an optional subtask
to the NetView program. The CNMSTYLE member is processed during
NetView initialization. For information on CNMSTYLE processing, see IBM
Tivoli NetView for z/OS Installation: Getting Started.
Initialization
The initialization process of the subtask performs any required
initialization functions. Examples include acquiring NetView control blocks
using the DSILCS macro and acquiring dynamic storage using the DSIGET
macro.
Processing
The processing part of a subtask begins by invoking the DSIWAT macro to
wait on an ECB list.The ECB list must include the subtask termination ECB
(TVBTECB) and generally includes the message queue ECB (TVBMECB),
which is used for intertask communication (using the DSIMQS macro). You
can also include user-defined ECBs in the ECB list.

© Copyright IBM Corp. 1997, 2015 79

Writing User Subtasks

Termination
As shown in Figure 8, the termination process frees all acquired resources
(for example, storage and NetView control blocks) and returns to the
NetView program.

Enter Subtask

TVBTERM=1 Yes
?
No

Initialization

TVBTERM=1 Yes Release

? Resources Exit

No

Issue DSIWAT
Macro on the
ECB List

Process the Data

Message Termination

User-Defined Set TVBTERM=1

Processing

Figure 8. Subtask Organization

Installation of User Subtasks

Code a TASK statement for the subtask in the CNMSTUSR or CxxSTGEN member.
The TASK statement defines the task to the NetView program and provides
information through the following keywords:
MOD Specifies the name of the module to be run as a subtask. You can link edit
the module into the appropriate NetView library.
MEM Specifies the user-defined initialization member found in DSIPARM to be

80 Programming: Assembler
 Writing User Subtasks

used by this task. You are responsible for the format and contents of the
specified member. The member can be read and processed during the task
initialization.
PRI Specifies the relative task priority (1–9), where 1 is the highest task priority
that you can assign and 9 is the lowest.
INIT Specifies whether the task is to be started during NetView initialization
(INIT=Y) or using the START command only (INIT=N).

An example of a TASK statement is:

TASK.USERTASK.MOD=USERMOD
TASK.USERTASK.MEM=USERMEM
TASK.USERTASK.PRI=7
TASK.USERTASK.INIT=Yes

In the preceding example, the subtask identification is USERTASK. USERMEM is

the name of the DSIPARM member. The priority of the subtask is 7 and is started
during NetView initialization.

For more information about the TASK statement, see the IBM Tivoli NetView for
z/OS Administration Reference.

Initialization of the OPT

Issuing the START TASK command or specifying INIT=Y on the TASK definition
statement attaches the optional subtask (OPT) normally. The TVBTERM bit in the
TVB is set to off (0).

When an OPT is attached, the registers contain the following information:

Register Contents
1 The address of the task vector block (TVB)
13 The address of a standard 72-byte save area used to store the caller's
registers
14 The return address
15 The entry address of the subtask
0, 2–12 Unspecified

The following list shows the control block names that are used in attaching an
OPT:
v Task vector block (TVB)
v Task information block (TIB)
v Main vector table (MVT)
v Service routine vector list (SVL)

The TVB contains the address of the TIB and the MVT, and the task control block
of the operating system. The MVT contains the address of the SVL. See Chapter 7,
“Control Blocks,” on page 103 for detailed descriptions of these control blocks.

After the subtask is initialized, but before it starts processing, you can indicate that
the subtask is ready to begin processing by performing the following steps:
1. Ensure that the subtask is not already on the TVB chain.
2. Enqueue the TVB chain.
3. Set the TVBOPID field of the TVB to a unique subtask identifier.

Chapter 5. Writing User Subtasks 81

Writing User Subtasks

4. Set the TVBACTV bit to on.

5. Dequeue the TVB chain.
6. Specify an end to task initialization by issuing a message. Use DSIPSS
TYPE=OUTPUT for this message. The message is returned to the appropriate
operator and process (for example a pipeline) that issued a START command
for your task, otherwise it is returned to the authorized receiver. This message
signals an end to correlation for the START command.

One method of setting the TVBOPID field is to copy the contents of TVBLUNAM
into TVBOPID. (TVBLUNAM is the value of the TSKID operand in the TASK
definition statement.) Another method is to use a predefined value.

If TVB374CT is turned on during subtask initialization, the NetView program

maintains a counter of the number of buffers on the public message queues. If this
counter exceeds the threshold value defined in the NetView constants module,
DSICTMOD (CNMS0055), message DSI374A is issued.Set TVB374CT just before
TVBACTV is turned on for public message queue thresholding. TVB374CT turns
off in the main task during subtask termination.

Note: Refer to the IBM Tivoli NetView for z/OS Installation: Getting Started for more
information about the NetView constants module (DSICTMOD).

TVBMEMNM Field
The value of the MEM keyword of the TASK definition statement is used as the
name (1 - 8 characters) of an initialization member or file. You find the value of the
MEM keyword in the TVBMEMNM field of the TVB if initialization input is
required. If the subtask is coded to process this member or file, the following
macros are called to read from the member or file:
v DSIDKS TYPE=CONN,NAME=DSIPARM to connect the subtask to disk services
for the DSIPARM data set.
v DSIDKS TYPE=FIND,NAME=TVBMEMNM to find the member or file and read
the first record.
v DSIDKS TYPE=READ to read a record. The READ is repeated until a
user-defined END statement is read or until an end-of-file return code is
returned.
v DSIDKS TYPE=DISC to disconnect from disk services.

If the subtask does not use the initialization member or filename, you can use
TVBMEMNM for other purposes, depending on the manner in which you specify
the MEM keyword of the TASK statement. For example, you can decide to use this
field as the data definition (DD) name to be opened by the subtask, or you can
specify a default operator to receive messages.

Processing
The following sections discuss processing subtasks using an ECB loop, intertask
communication, and operator communications.

ECB Loop
The processing section of a subtask usually begins by issuing the DSIWAT macroto
wait on an ECB list. The ECB list contains the subtask termination ECB
(TVBTECB), and generally contains the message queue ECB (TVBMECB), used for
intertask communication using the DSIMQS (message queuing service) macro. In
addition to these two ECBs that are provided with the NetView program, the ECB
list can contain user-defined ECBs for additional functions.
82 Programming: Assembler
 Writing User Subtasks

Intertask Communication
If your subtask receives messages or commands from other tasks (or exits), include
the normal message ECB (TVBMECB) in your subtask's wait list. Optionally, you
can include the high-priority and low-priority message ECBs (TVBMECBH and
TVBMECBL). If the subtask services the high and low queues, set the bit TVBMM
to B'1' to indicate this. (When TVBMM is B'0', the message queuing service puts all
messages on the normal queue, regardless of how they are sent.) Retest the
high-priority ECB after each item of work on a lower queue, to enable
higher-priority work to pre-empt the queue of lower-priority work.

Each message queue has three parts: a private queue, a public queue, and an ECB.
(Each has two queues for reentrant code.) The elements and their respective
priorities are shown in Table 7:
Table 7. Message Processing Elements
Priority Private Queue Public Queue ECB
High TVBMPRQH TVBMPUBH TVBMECBH
Normal TVBMPRIQ TVBMPUBQ TVBMECB
Low TVBMPRQL TVBMPUBL TVBMECBL

Message Queue Processing: When your subtask receives a message buffer, the
TVBMECB is posted and the message buffer is inserted at the head of the public
message queue pointed to by TVBMPUBQ, a last in, first out (LIFO) queue. When
your subtask detects that the TVBMECB ECB has been posted, the public message
queue can be moved to the private message queue (TVBMPRIQ) for processing.
Because the DSIMQS service handles situations such as mainline interruption (for
example, an exit running asynchronously queues a message buffer to your
subtask), simultaneous processing in multiple subtasks, and parallel processing in
multiprocessor environments, you must use the assembler compare and swap (CS)
instruction to acquire message buffers from the public message queue.

To process the public message queue, do the following steps:

v Set TVBMECB to 0.
v Use the assembler CS instruction to obtain the queue of buffers from
TVBMPUBQ and store 0 in TVBMPUBQ. If public message queue thresholding
is being done (TVB374CT is on), you can add code to set TVBQCNT to 0 using
the assembler CS instruction.
v Reverse the order of the queue, that is, make it first in, first out (FIFO) so that
the message buffers can be processed in the order that they are received.

The following segment of assembler code demonstrates how to move the public
message queue to the private message queue. Addressability to the DSITVB control
block is assumed.
MESSAGEQ EQU * BRANCH HERE WHEN TVBMECB POSTED
XC TVBMECB,TVBMECB CLEAR MESSAGE ECB
CHEKQ EQU *
SLR R0,R0 CLEAR SWAP REGISTER
L R3,TVBMPUBQ LOAD COMPARAND REGISTER
CS R3,R0,TVBMPUBQ CS ZERO ON THE PUBLIC QUEUE
BNE CHEKQ RETRY IF TVBMPUBQ CHANGED
LTR R3,R3 IS QUEUE EMPTY
BZ WAIT BR IF EMPTY
USING BUFHDR,R3 MAP BUFHDR ONTO QUEUE HEAD
REVQ EQU * MAKE LIFO QUEUE A FIFO QUEUE
L R1,HDRNEXTM R1 = POINTER TO NEXT BUFFER

Chapter 5. Writing User Subtasks 83

Writing User Subtasks

ST R0,HDRNEXTM SET NEXT TO PREVIOUS

LR R0,R3 MAKE CURRENT PREVIOUS
LTR R3,R1 END OF QUEUE?
BNZ REVQ CONTINUE UNTIL END REACHED
ST R0,TVBMPRIQ ANCHOR THE PRIVATE QUEUE
PROCESS EQU * BEGIN BUFFER PROCESSING

The message buffers can be dequeued from the private message queue and
processed. After each buffer is processed, it is freed. Message buffers are obtained
with DSIGET Q=NO and SUBPOOL 0, so they are freed with DSIFRE Q=NO and
SUBPOOL 0. These are the default values.

Message Buffer Contents: Message buffers are described in detail in Chapter 2,

“Designing Assembler Modules,” on page 3. They can be actual messages to be
displayed (HDRMTYPE = HDRTYPEU) or internal function requests (HDRMTYPE
= HDRTYPEI). For internal function requests queued to your optional subtask, you
can define your own function type by setting the IFRCODE field to IFRCODUS
(user function) and then taking appropriate user-defined action when your
optional subtask receives the buffer.

Using IFRCODUS to Call a User-Defined Command Processor: Use the

following technique to call a user-defined command processor under your optional
subtask:
v Issue DSIMQS (from any subtask environment) to send an internal function
request (HDRMTYPE=HDRTYPEI and IFRCODE=IFRCODUS) to your optional
subtask. The command name and command parameters follow the DSIIFR
portion of the buffer passed to DSIMQS.
v When processing the IFRCODUS message buffer under your subtask, add 2 to
HDRTDISP to adjust the displacement to the start of the command and subtract
2 from HDRMLENG to keep the length consistent.
v Follow the steps listed under “Calling a Command Directly” on page 15 to call
the command processor.

Define the command processor called as TYPE=D or TYPE=RD on its respective

CMDDEF statement in CNMCMD or its included members. It is a user-written
command processor. Do not call any of the command procedures that are provided
with the NetView program from your optional subtask.

Note: The DSIZCSMS and DSIZVSMS macros are not valid under an optional task.

Sending Message Buffers: Use the DSIMQS macro to sendmessage buffers to

other subtasks. These message buffers can contain actual operator messages to be
displayed, or they can contain internal function requests (IFRs) to be run by the
receiving subtasks. See Chapter 8, “Macros,” on page 155 for details of the DSIMQS
macro.

Operator Communications
Sending Messages to Operators: You can use DSIPSS TYPE=OUTPUT or
TYPE=IMMED to send messages. Messages sent this way go to the owner who
started the subtask. If the subtask was started during NetView initialization or the
owner has logged off, the message is sent to the PPT for routing and automation.

You can also use the DSIMQS macro to send messages to the authorized receiver
of messages or to the operator that started the subtask. The TIBMSGNM field of
the DSITIB control block contains zeros if the subtask was started during NetView
initialization (that is, if you specified INIT=Y on the TASK definition statement).

84 Programming: Assembler
 Writing User Subtasks

Commands from operators are buffers with HDRMTYPE equal to HDRTYPET,

HDRTYPEB, or HDRTYPQC. All other commands are HDRTYPEI.

Logging Messages: You can use macro DSIWLS to write messages from the
subtask to the network log, CanzLog log, the MVS system log, an external log, or a
NetView sequential log. See “DSIWLS: Write Log Services” on page 242 for more
information. You cannot start hardcopy logging for user-written subtasks.

Scheduling Commands: You can use macro DSIMQS to schedule commands to

run under other tasks. See “Scheduling Commands Using DSIMQS” on page 16 for
more information.

Calling Command Processors: See “Calling a Command Directly” on page 15.

Note:
1. You cannot call command lists, immediate commands, or regular commands
from an optional task. Only command processors defined as TYPE=D or
TYPE=RD can be called from an optional task.
2. You cannot call DST service macros DSIZVSMS and DSIZCSMS under an
optional task.

User-defined Functions: When a user-defined ECB is posted for work, a

user-defined command processor can be called as explained in the previous
section, or a subroutine can be called to perform the requested function. The
method depends on how you want to handle your implemented function.

Terminating the OPT

When an optional subtask (OPT) terminates normally, the TVBTERM bit is set on,
indicating that the subtask resources can be released. When a subtask abends, the
TVBTERM bit is set on and the subtask is reattached. This is called a cleanup
attach. When the subtask regains control, it frees the resources it had obtained and
exits normally.

Include the TVBTECB field of TVB (termination ECB) in the subtask ECB list for
each OPT you write. When a CLOSE NORMAL command is issued and all
operators have logged off, the main task posts the TVBTECB of the subtask. This
posting indicates that subtask termination is requested.

When the subtask finds the TVBTECB posted, the subtask performs the following
steps:
1. Releases all resources
2. Sets the TVBOPID field to blanks
3. Enqueues the TVB chain
4. Sets the TVBACTV bit to off
5. Sets the TVBTERM bit to on
6. Dequeues the TVB chain
7. Reloads the registers originally passed to the subtask and return to the
operating system

After the subtask releases all resources, NetView macros cannot be issued.

Chapter 5. Writing User Subtasks 85

Writing User Subtasks

Additional Considerations
Special Requirements for IRB Exits
User-written interruption request block (IRB) exits that call NetView macro services
require the following special processing:
v On entry, if the TVBINXIT is not on, set it on. If the TVBINXIT bit is already set
on, increment TIBMUXIT by 1.
v On exit, if TIBMUXIT is zero (0), clear the TVBINXIT bit. However, if TIBMUXIT
is greater than 0, decrement it by 1.

Displaying Status
The LIST command displays the status of asubtask on an operator's terminal. For
OPTs, in addition to status, a header line and the contents of TVBOPID and
TVBLUNAM are also displayed. Status is determined by the following TVB bit
fields in the following order:
1. TVBLGOFF – Stopping
2. TVBACTV – Active
3. TVBLGON – Starting
4. None of the above – Inactive

The subtask can also create a status display.

VTAM Outage Processing

User-written code (exit routines, command processors, and subtasks) that requires
the VTAM program to operate receives error codes when the VTAM program is
inactive. User-written subtasks that require the VTAM program must enable the
VTAM program to end without terminating or abending the NetView program.

Do this as follows:
v If your subtask opens a VTAM ACB, code a TPEND exit for VTAM that is called
when VTAM ends. Your TPEND exit can post TVBTECB to signal subtask
termination to begin.
v If your subtask requires VTAM to be active and does not open an ACB, you can
still be notified. Set the TVBAUTVE bit in the TVB for your subtask. When the
main subtask TPEND is called (for HALT NET, QUICK, for HALT NET,
CANCEL, and for VTAM ABEND), the NetView main subtask posts TVBTECB
for every subtask that has TVBAUTVE set to 1.
v The NetView program also provides another bit, TVBAUTVS, which causes the
NetView main subtask to reattach your subtask when the NetView program
detects that the VTAM program has successfully opened the main subtask's
ACB. Set the TVBAUTVS bit to 1 for this function.

Data Services Task (DST)

A DST is a set of NetView interfaces built on top of the optional task base. The
NetView program provides a subtask processing module (DSIZDST) along with the
following interfaces:
v An initialization exit
v A data services command processor (DSCP) that provides the following services:
– A CNM data services macro interface (DSIZCSMS) to request and send data
across the communication network management interface (CNMI)
– An interface to enable a command processor to receive unsolicited CNM data

86 Programming: Assembler
 Writing User Subtasks

– A VSAM data services macro interface (DSIZVSMS) using PUT and GET to
obtain records from a predefined VSAM data set.
v Various installation exits

Installation of a DST
You can dynamically start a data services task (DST) without defining it in the
CNMSTYLE member by using the START command with the TASK keyword.

If you choose to define the TASK statement in the CNMSTYLE member, the
statement follows the same format as the optional TASK statement, with the
following exceptions:
v The MOD keyword must specify DSIZDST as the subtask processing module.
DSIZDST, provided by the NetView program, provides the necessary
initialization, processing, and termination routines to use the DSCP interfaces.
v The initialization data set member (specified by the MEM keyword) must
contain DSTINIT statements to provide initialization parameters required by
DSIZDST. The statements are described in the following sections under their
respective interfaces.

The other TASK statement keywords have the same meanings as those coded for
an optional task, as follows:
PRI Specifies the relative task priority (1 - 9). One is the highest task priority
that can be assigned, and 9 is the lowest.
INIT Specifies whether the task is to be started during NetView initialization
(INIT=Y) or using the START command only (INIT=N).

An example of a TASK statement is as follows:

TASK.SQLOGTSK.MOD=DSIZDST
TASK.SQLOGTSK.MEM=SQLOGMEM
TASK.SQLOGTSK.PRI=2
TASK.SQLOGTSK.INIT=N

In the preceding example, the subtask identification is SQLOGTSK. SQLOGMEM is

the name of the DSIPARM member. The priority of the subtask is 2 and is not
started during NetView initialization. You can use the START command to start the
subtask.

Initialization of a DST
The following keywords apply to DST initialization (DSTINIT) processing.
v FUNCT
Specifies the DST services that are required. In all cases, the ability to call DSCPs
is provided. The following list shows the function choices:
OTHER
The DST does not require the CNMI or VSAM interfaces.
BOTH Both of 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 described in Chapter 3,
Chapter 5. Writing User Subtasks 87
Writing User Subtasks

“Writing Installation Exit Routines,” on page 23, and is called once for every
statement in the specified initialization member (MEM keyword of TASK
statement). When the end of file is reached, USERPDB and USERMSG are both
0. For each statement (except end-of-file condition), the standard installation exit
return codes cause the following 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 not 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
terminates the DST. Termination occurs only if the initialization process has failed.

The initialization exit calls the DSIPUSH service to define a LOGOFF routine. The
LOGOFF routine is called during normal or abnormal end-of-task processing. No
termination exit is provided. The LOGOFF routine frees any resources that the user
has acquired. Storage that has been acquired with the Q=YES option is
automatically freed by the DSIZDST module.

Note: For additional details on DSTINIT statements, refer to the IBM Tivoli
NetView for z/OS Administration Reference.

Data Services Command Processor

A data services command processor (DSCP) generally performs CNM data services
using macro DSIZCSMS, or VSAM data services using macro DSIZVSMS, or both
services.

When a DST calls a DSCP, the input to the DSCP includes the address of a data
services request block (DSRB) in the CWBDSRB field. The function code
(DSRBFNCD) indicates the purpose for which the command was called.
DSRBFNCD is described in “DSIDSRB: Data Services Request Block” on page 118.

Observe these two restrictions when writing a DSCP:

v Only commands defined as TYPE=D or TYPE=RD can be called under a DST or
queued to a DST. Call only user-defined commands directly. Commands called
from your DSCP cannot use NetView macros DSIZVSMS or DSIZCSMS.
v Use only DSIPSS TYPE=OUTPUT or TYPE=IMMED. Messages sent this way go
to the operator who started the subtask (that is, to the owner). If the subtask
was started during NetView initialization, or if the owner has logged off, the
message is sent to the primary POI task (PPT) for routing and automation.

Data services requests are generally sent with HDRMTYPE=HDRTYPEI. Operators

can queue commands using the EXCMD command. These commands can be
identified because they are HDRTYPET, HDRTYPEB, or HDRTYPQC. You can
check the HDRMTYPE field and reject direct operator requests.

88 Programming: Assembler
 Writing User Subtasks

CNM Data Services

The DST provides access to both solicited and unsolicited CNM data. A DSCP can
issue DSIZCSMS to solicit CNM data from the network. You can define a DSCP to
receive unsolicited data from VTAM.

An access method control block (ACB) with AUTH=CNM must be defined to

VTAM with the ACB name matching the task ID of the DST.

Unsolicited CNM Data Interface

VTAM provides a default table (ISTMGC01) that controls the routing of unsolicited
CNM request units (RUs). You can write a supplemental table (ISTMGC00) to
override the default routing information that VTAM provides. 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 CNMI services,
an ACB is opened with an ACB name (the application name) that is the same as
the task name defined by the TSKID operand of the DST TASK definition
statement. The 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.

DSTINIT Keywords: The following list shows the keywords for the DSTINIT
statement:
UNSOL
Specifies the command verb name of the module that is to serve as the
unsolicited DSCP for this DST. The unsolicited DSCP cannot issue the
DSIZCSMS macro, but can issue the DSIZVSMS macro.
DSRBU
Specifies the number of unsolicited DSRBs that are to be allocated to this
DST. If this DST does not process unsolicited CNM data, set this value to
0. If the unsolicited DSCP issues the DSIZVSMS macro, set this value to
the number of concurrent DSIZVSMS requests that are valid. If the
unsolicited DSCP does not issue the DSIZVSMS macro, set this value to 1.

Note: To issue DSIZVSMS, you must also specify FUNCT=BOTH.

DSCP Interface: When the unsolicited DSCP receives control, the DSRBFNCD
field contains the DSRBFUNS (unsolicited) function code, DSRBUBUF is 0, and
DSRBCUSB contains the address of a NetView buffer containing the unsolicited
data. The RU starts at the offset specified in HDRTDISP, and the RU length is in
HDRMLENG. If a deliver header is present, it is considered part of the data (for
example, HDRTDISP points to the start of the deliver header). Refer to the z/OS
Communications Server library for more information. Table 8 describes the return
codes on entry to the unsolicited DSCP.
Table 8. Return Codes on Entry to the Unsolicited DSCP
DSRBRCMA DSRBRCMI Meaning
00 00 Successful completion.
00 16 Installation exit rejected the deliver RU. HDRMLENG is
set to 0.
00 20 Data has been truncated. The length of the deliver RU is
greater than the length of the buffer. HDRMLENG is set to
the truncated length.

Chapter 5. Writing User Subtasks 89

Writing User Subtasks

Table 8. Return Codes on Entry to the Unsolicited DSCP (continued)

DSRBRCMA DSRBRCMI Meaning
00 24 Data is truncated after the installation exit returned with a
return code of USERSWAP. HDRMLENG is set to the
truncated length.

Solicited CNM Data Interface

A DSCP can call the DSIZCSMS macro to acquire CNM data from the network.

DSTINIT Keyword: The DSTINIT statement keyword is:

DSRBO
Specifies the number of solicited DSRBs that are required by this task and
limits the number of concurrent DSIZCSMS and DSIZVSMS requests. This
value must be at least 1 (a DSCP cannot be called unless a solicited DSRB
is available) and no greater than 862.

DSCP Interface: Acquiring CNM data is a two-part process. When the DSCP is
first driven (generally by a command buffer queued by an OST using a DSIMQS
macro), the DSRBFNCD field contains a value of DSRBFNRM. The CWBDSRB field
points to a DSRB that must be passed on the DSIZCSMS macro. You must issue
the DSIZCSMS macro with this DSRB. After you issue the macro, register 15
contains the major return code and register 0 contains the minor return code
(additional completion information). If register 15 is not 0, the macro has failed. If
register 15 is 0, the request has successfully been sent to VTAM. At this time, the
DSCP can exit because the data is returned on a subsequent invocation of the same
DSCP. (This is called a redrive operation.)

When the DSCP is redriven (the second part of the process), the DSRBFNCD code
is DSRBFSOL. Check the DSRB major return code (DSRBRCMA) and the DSRB
minor return code (DSRBRCMI) to determine whether the request completed
successfully.

Table 9 describes major and minor return codes and their meanings.
Table 9. DSIZCSMS Return Codes
DSRBRCMA DSRBRCMI Meaning
00 00 Successful completion.
00 04 Negative response was received. DSRBINPT contains the
address of the negative response.
00 08 Insufficient storage to process the request.
00 16 Installation exit rejected the deliver RU. HDRMLENG is
set to 0.
00 20 Data has been truncated. The length of the deliver RU is
greater than the length of the buffer. HDRMLENG is set to
the truncated length.
00 24 Data is truncated after the installation exit returns with a
return code of USERSWAP. HDRMLENG is set to the
truncated length.
00 28 VTAM rejected the request.
00 32 CNM interface closed because of an unrecoverable error.
00 36 Positive response was received.

90 Programming: Assembler
 Writing User Subtasks

Table 9. DSIZCSMS Return Codes (continued)

DSRBRCMA DSRBRCMI Meaning
00 44 Cancellation because of timer completion.

If the request completes successfully, the input buffer supplied on the initial
DSIZCSMS invocation (INPUT parameter) contains the received data. The buffer
contains a standard NetView buffer header with HDRTDISP containing the offset
to the start of the data. If the data is preceded by a deliver RU, HDRTDISP
contains the offset to the start of the deliver RU.

After the initial invocation of DSIZCSMS and until the DSCP is redriven, the DSRB
is considered in use and is not available to other DSCPs. Other DSCPs can run
during this time if the DSRBO value is greater than 1 and there is a DSRB that is
not in use by another DSCP. When the DSCP is redriven, the DSRB is the only
control block that does not change from the initial invocation of the DSCP. You can
use the DSRBUSER field to contain or point to any additional environment
information that you want to maintain. See the description of DSRBUSER for more
information.

VSAM Service Interface

A DSCP can call the DSIZVSMS macro to perform input/output to a specified
VSAM data set. Use the access method services DEFINE CLUSTER statement to
define a key-sequenced read/write data set as needed by the NetView program.

For information about the DEFINE CLUSTER statement, refer to the z/OS library,
DFSMS component.

DSTINIT Keywords
The following are the keywords for the DSTINIT statement. The primary and
secondary data sets are user-defined and can be switched with each other.
PDDNM
Specifies the DD name of the primary data set to be used by VSAM
services. Allocate this data set before starting the DST.
PPASS
Specifies the VSAM password to be used when the primary data set ACB
is opened.
SDDNM
Specifies the DD name of the secondary data set to be used by VSAM
services. Allocate this data set before starting the DST. The NetView
SWITCH command controls which data set is currently the active data set.
SPASS
Specifies the VSAM password to be used when the secondary data set ACB
is opened.
MACRF
Specifies local resource sharing.
XITVN
Specifies an installation exit to receive control when an empty VSAM data
set has been opened for processing. You can use this to put an initialization
record into the data set.

Chapter 5. Writing User Subtasks 91

Writing User Subtasks

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.
XITVO
Specifies an installation exit to receive control before output of a record to
the VSAM data set.

Note: If DSRBO is greater than 1, the NetView program does not guarantee that
the DSIZVSMS requests for VSAM PUTS are processed in the order they were
submitted. The requests are completed asynchronously.

DSCP Interface
Like the CNMI service (DSIZCSMS), using DSIZVSMS is a two-part process.

When the DSCP is first driven, generally by a command buffer sent by an OST
using a DSIMQS macro, the DSRBFNCD field contains a value of DSRBFNRM. The
CWBDSRB field points to a DSRB that must be passed on the DSIZVSMS macro.

Issue the DSIZVSMS macro with the supplied DSRB. After you issue the macro,
register 15 contains the major return code and register 0 contains the minor return
code, which is additional completion information. If register 15 is not 0, the macro
has failed. If register 15 is 0, the request has successfully been sent to VSAM. At
this time, the DSCP can exit because the success or failure of the VSAM
input/output requested is returned on a subsequent invocation of the same DSCP.
This is called a redrive operation. When the DSCP is redriven, the DSRBFNCD
code is DSRBFVSM. Check the DSRBRCMA (DSRB major return code) and the
DSRBRCMI (DSRB minor return code) to see if the request completed successfully.

Table 10 describes the major and minor return codes for the DSIZVSMS macro.
Table 10. DSIZVSMS Return Codes
DSRBRCMA DSRBRCMI Meaning
00 00 Successful completion.
00 16 Installation exit processing of VSAM input has rejected the
input. HDRMLENG is set to 0.
00 24 Data has been truncated. Installation exit returned data
longer than NetView buffer on RC = USERSWAP.
HDRMLENG is set to the truncated length.
00 28 Return code from installation exit is not valid.
08 VSAM RPL feedback VSAM logical error, indicated in
DSRBRCMI. Refer to the OS/VS VSAM library and the
DFSMS VSAM library.
12 VSAM RPL feedback VSAM physical error, indicated in
DSRBRCMI. Refer to the OS/VS VSAM library and the
DFSMS VSAM library.

Relevant DSRB fields are as follows:

DSRBVRPL
The address of the VSAM RPL that was used for the input/output.
DSRBVACB
The address of the VSAM ACB for the DST.
DSRBVDAD
The address of the VSAM input/output buffer, with a standard BUFHDR.

92 Programming: Assembler
 Writing User Subtasks

For GET requests, the BUFHDR HDRMLENG field indicates the length of
the data read. HDRTDISP contains the offset to the data.
DSRBVKEY
The address of the key in the DSRBVDAD buffer.
DSRBVKLN
The key length.
DSRBVRTP
Indicates the type of request just completed:
1 - DSRVGET (VSAM GET)
2 - DSRVPUT (VSAM PUT)
3 - DSRVPNT (VSAM POINT)
4 - DSRVERS (VSAM ERASE)
5 - DSRVNRQ (VSAM ENDREQ)

After the initial invocation of DSIZVSMS and until the DSCP is redriven, the DSRB
is considered in use and is not available to other DSCPs. Other DSCPs can run
during this time if the DSRBO value is greater than 1 and there is a DSRB that is
not in use by another DSCP. When the DSCP is redriven, the DSRB is the only
control block that does not change from the initial invocation of the DSCP. You can
use the DSRBUSER field to contain or point to any additional environment
information that you wish to maintain. See the description of DSRBUSER for more
information.

Example of DSCP Design

You can use a DSCP to solicit CNM data from a resource in the network and
record the results on a VSAM data set. To accomplish this, DSCP processing can
follow the steps in Figure 9 on page 94.
▌1▐ A DST that receives an IFRCODCR buffer calls the DSCP with a function
code of initial call. The DSCP issues DSIZCSMS to solicit the CNM data. The
DSCP returns to the caller.
▌2▐ The DSCP is redriven. 1 with a function code of solicited CNM data. The
DSCP issues DSIZVSMS to write the data to the VSAM data set. The DSCP
returns to the caller.
▌3▐ The DSCP is redriven with a function code of VSAM I/O completed. If more
than one CNM buffer is needed, the DSCP issues another DSIZCSMS to retrieve
the buffer. The DSCP returns to the caller.
▌4▐ Steps 2 and 3 repeat alternately until the DSCP has retrieved all of the data.
▌5▐ When the DSCP is redriven for completion of the last VSAM PUT, it sends
a completion message and returns control to the DST. Because neither
DSIZCSMS nor DSIZVSMS was issued, the DSRB is not redriven. Processing for
the DSCP ends.

1. When a DSCP is redriven, its input control blocks and fields, except for the DSRB, can be completely different from those used in
its previous invocation

Chapter 5. Writing User Subtasks 93

Writing User Subtasks

DSCP

Initialize

Check DSRB
Function Code

Yes Initial No
Command
?

Yes Valid No Yes CNMI No

Command Completion
?

More
Yes CNMI No
Work
?
DSIMBS

Build Error
1 Message
Issue Issue 3
DSIZCSMS DSIZCSMS
5

DSIMQS Issue 2 DSIMQS

DSIZVSMS 4
Message Message
Queue Write to Queue
Disk Log

End

Figure 9. Structure of a Data Services Command Processor

Figure 10 on page 95 shows that one way you can structure data services requests.
This example starts with an initial operator command. This command calls the
DSCP using DSIMQS with an IFRCODCR buffer. When the DSCP has obtained
VSAM or CNM data to be presented, it can do either of the following steps:
v Send the message data to the terminal (for standard or title-line output).
v Call a presentation services command processor (PSCP) to present the data (for
full-screen output).

94 Programming: Assembler
 Writing User Subtasks

Operator
Terminal

Command
entered
from
terminal

DST DST
DSIZCSMS
VTAM
User-Written DSIMQS Data
Regular Command IFRCODCR Services
Processor for Command
Syntax and Processor DSIZVSMS
Data
Parameter Checking Base

Message

DSIMQS
Command
Processor
Saves
Data DSIMQS
IFRCODCR

DSIPSS to
send full
screen of RESUME
data Presents Data

Figure 10. Example of Program Design for Data Services Requests

The command processor uses DSIGET to obtain storage. The address of this
storage can be saved in DSRBUSER (provided that the DSRB is considered “in
use”) or DSIPUSH can save it as a named storage pointer. Saving this information
establishes and maintains data from one DSCP call to the next.

If the DSCP does not use the parse buffer PDB, you can improve the performance
by specifying PARSE=N on the CMDDEF statement defining the DSCP. In this
case, the command buffer is not parsed and no PDB is provided to the command
processor.

Chapter 5. Writing User Subtasks 95

Writing User Subtasks

An operator can have one or more pending DST requests. You can use the LIST
DST command to list active DST requests.

User-Defined Services
You can call command processors defined as TYPE=D or TYPE=RD under the DST
to perform user functions. The processors are called with a standard NetView
command processor interface (register 1 points to a DSICWB control block). If
parsing of the command buffer is not required, specify PARSE=N on the respective
CMDDEF statement for the DSCP. This option improves performance.

See Appendix A, “Assembler Samples,” on page 271 for an example of a

user-written optional subtask.

96 Programming: Assembler
Chapter 6. Writing User Function Directories
This section explains how to add functions, expand, or replace those REXX
functions that exist in the NetView REXX environment.

The DSIRXEBS macro described in Chapter 8, “Macros,” on page 155 is used to

obtain storage for an evaluation block.

Overview of User-Written Functions

You can write external functions to extend the capabilities of the REXX language.
You can write functions that supplement either the built-in functions or the
functions that are provided. You can also write a function that replaces a provided
function. For example, if you want a new substring function that performs
differently from the SUBSTR built-in function, you can write your own substring
function and name it STRING. Users at your installation can then use the STRING
function in their REXX command lists.

You can write an external function or subroutine in assembler and store it in a load
library. This provides faster access to the function or subroutine than if the
function or subroutine is written in REXX. For even faster access to a function or
subroutine, and therefore better performance, you can group frequently used
external functions and subroutines in function packages (grouped or packaged
together). To include an external function or subroutine in a function package, it
must be linked into a load module together with a function package directory. The
name of the resulting load module must be added to the function package table in
the NetView DSIRXPRM module.

As of NetView V6R2, function package names and command environments are

defined by using REXX.FUNCPKGLIST statements and REXX.CMDENV
statements in the CNMSTYLE (CNMSTUSR or CxxSTGEN) member; for more
information, see the Administration Reference. For REXX initialization parameters
other than function package names and command environments, refer to the
CNMSJM11 sample for the default NetView DSIRXPRM module.

The NetView program supports the following types of function package

directories:
v DSIRXUFP user packages, which are function packages that an individual user
can write to replace or supplement certain system-provided functions. When the
function packages are searched, the user packages are searched before the local
and system packages.
v DSIRXLFP local packages, which are function packages that a system support
group or application group can write. Local packages can contain functions that
are available to a specific group of users or to the entire installation. Local
packages are searched after the user packages and before the system packages.
v DSIRXFPG system packages, which are function packages written for the
NetView program. System packages are searched after any user and local
packages.

Subroutines can also be included in the function package directories.

© Copyright IBM Corp. 1997, 2015 97

Writing User Function Directories

To provide new functions or change existing functions, several steps are required.
The steps are described and explained in more detail in the following sections.

Interface to Functions
When your code gets control, the function gets a control block called the
evaluation block (EVALBLOK).The function places the result in the evaluation
block, which is returned to the language processor. The result in the evaluation
block is used in the interpretation of the REXX instruction that contained the
function.

For instructions on obtaining an evaluation block, see the NetView DSIRXEBS

macro description in Chapter 8, “Macros,” on page 155.

Entry Specifications
When the code for the function gets control, the contents of the registers are as
follows:
Register 0
Address of the environment block (TIB address is in
ENVBLOCK_USERFIELD)
Register 1
Address of the external function parameter list (EFPL)
Registers 2-12
Unpredictable
Register 13
Address of a register save area
Register 14
Return address
Register 15
Entry point address

External Function Parameter List

When the function gets control, register 1 points to the external function parameter
list, as described in Table 11. TSO/E provides the mapping macro IRXEFPL for the
external function parameter list.
Table 11. External Function Parameter List
Offset Number of
(Decimal) Bytes Description
0 4 Reserved
4 4 Reserved
8 4 Reserved
12 4 Reserved
16 4 The address of the parsed argument list. Table 12 on page
99 shows the format of the argument list.
20 4 The address of a fullword that contains the address of an
evaluation block (EVALBLOK). The evaluation block is
used to pass back the result of the function. Table 13 on
page 99 describes the evaluation block.

98 Programming: Assembler
 Writing User Function Directories

Argument List
Table 12 shows the format of the parsed argument list that the function receives at
offset +16 (decimal). TSO/E provides the mapping macro IRXARGTB for the
argument list.
Table 12. Format of the Argument List
Offset Number
(Dec) of Bytes Field Name Description
0 4 ARGSTRING_PTR Address of argument 1
4 4 ARGSTRING_LENGTH Length of argument 1
8 4 ARGSTRING_PTR Address of argument 2
12 4 ARGSTRING_LENGTH Length of argument 2
16 4 ARGSTRING_PTR Address of argument 3
20 4 ARGSTRING_LENGTH Length of argument 3
24 8 --- X'FFFFFFFFFFFFFFFF'

In the argument list, each argument consists of the address of the argument and its
length. The argument list is terminated by X'FFFFFFFFFFFFFFFF'.

Evaluation Block
Before the function returns control to the language processor, the address of a
fullword that contains the address of the evaluation block (EVALBLOK) is placed
at offset +20 of the external function parameter list. The function computes the
result and returns the result in the evaluation block.

The evaluation block consists of a header and data, in which you place the result
from your function. Table 13 shows the format of the evaluation block.

TSO/E provides the mapping macro IRXEVALB for the evaluation block.
Table 13. Format of the Evaluation Block
Offset Number of
(Decimal) Bytes Field Name Description
0 4 EVPAD1 A fullword that contains X'00'. This field is
reserved and is not used.
4 4 EVSIZE Specifies the total size of the evaluation block, in
doublewords.
8 4 EVLEN On entry, this field is set to X'80000000', which
indicates no result is currently stored in the
evaluation block. On return, specify the length of
the result, in bytes, that your code is returning.
The result is returned in the EVDATA field at
offset +16.
12 4 EVPAD2 A fullword that contains X'00'. This field is
reserved and is not used.
16 n EVDATA The field in which you place the result from the
function or subroutine. The length of the field
depends on the total size specified for the control
block in the EVSIZE field. The length of the
EVDATA field can be computed using the
formula (EVSIZE*8)-16.

Chapter 6. Writing User Function Directories 99

Writing User Function Directories

The function computes the result, moves the result into the EVDATA field, and
updates the EVLEN field. If the initial evaluation block is too small to hold the
complete result, you can use the DSIRXEBS macro to obtain a larger evaluation
block. DSIRXEBS creates the new evaluation block and returns the address of the
new block. Your code can then place the result in the new evaluation block. You
must also change the parameter for the address of the EVALBLOK in the
parameter list to point to the new evaluation block. If you used DSIRXEBS to get
the initial evaluation block, DSIRXEBS releases the evaluation block if its address is
provided when obtaining the larger evaluation block.

Functions must return a result. Subroutines are not required to return a result.

Directory for Function Packages

After writing the code for the function, create an entry in one of the directories.
You need a directory entry for each individual function package you want defined.

Note: Functions not contained in the function package can be link-edited into the
load library as stand-alone functions.

A load module contains a function package directory that you can tailor to
individual users or local groups. The name of the entry point at the beginning of
the directory is the function package directory name. The name of the directory is
specified only on the CSECT. In addition to the name of the entry point, the
function package directories define each entry point for the individual functions
that are part of the function package. The directories consist of two parts:
v A header
v Individual entries for each function included in the function package

Table 14 shows the format of the directory header. Table 15 on page 101 illustrates
the rows of entries in the function package directory.
Table 14. Format of the Function Package Directory Header
Offset Number of
(Decimal) Bytes Description
0 8 An 8-byte character field that defines the directory. This is the
name of the directory. For example, you can specify DSIRXUFP,
which is one of the dummy function package names that is
provided. The name must be in uppercase and left-aligned.
8 4 Specifies the length, in bytes, of the header. This is the offset
from the beginning of the header to the first entry in the
directory. This must be a fullword binary number equivalent to
decimal 24.
12 4 Specifies the number of functions defined in the function
package (the number of rows in the directory). The format is a
fullword binary number.
16 4 Reserved.
20 4 Specifies the length, in bytes, of an entry in the directory
(length of a row). This must be a fullword binary number
equivalent to decimal 32.

At offset +0 in the header, specify the name of the function package directory. Two
dummy function package directory names are provided:
v DSIRXUFP for a user function package
100 Programming: Assembler
 Writing User Function Directories

v DSIRXLFP for a local function package

Format of the Entry in the Directory

Table 15 shows an entry in a function package directory. The entry starts
immediately after the directory header and defines a function or subroutine in the
function package. The individual fields are described following the table.
Table 15. Format of an Entry in a Function Package Directory
Offset Number of
(Decimal) Bytes Field Name Description
0 8 FUNC-NAME The name of the first function or
subroutine (entry) in the directory.
8 4 ADDRESS The address of the entry point of the
function or subroutine (for the first entry).
12 4 --- Reserved.
16 8 SYS-NAME The name of the entry point in a load
module that corresponds to the function or
subroutine (for the first entry).
24 8 SYS-DD The ddname from which the function or
subroutine is loaded.

The following list describes each entry (row) in the directory:

ADDRESS
Specifies a 4-byte field that contains the address, in storage, of the entry point
of the function or subroutine. This address is used only if the code has already
been loaded.
If the address is 0, the sys-name and, optionally, the sys-dd fields are used.
If you specify the address, the sys-name and sys-dd fields for the entry are
ignored.
FUNC-NAME
Is the 8-character name of the external function or subroutine. This is the name
that is used in the REXX command list. The name must be in uppercase and
left-aligned.
If this field is blank, the entry is ignored.
Reserved
Is a 4-byte field that is reserved.
SYS-DD
Specifies an 8-character name of the DD from which the function or subroutine
is loaded. The name must be in uppercase and left-aligned. If the address is 0
and this field is blank, the module is loaded from the linklist.
SYS-NAME
Supplies an 8-character name of the entry point in a load module that
corresponds to the function to be called for the func-name. The name must be
in uppercase and left-aligned.
If you specify the address, this field can be blank. If you specify an address of
0 and this field is blank, the entry is ignored. If you specify sys-dd, the LOAD
is issued from DD sys-dd. If you do not specify sys-dd, the module is loaded
from the linklist.

Chapter 6. Writing User Function Directories 101

Writing User Function Directories

Example of a User Function Directory

Figure 11 shows an example of a user function directory. The example is explained
following the figure:

DSIRXUFP CSECT
DC CL8’DSIRXUFP’ String identifying directory
DC FL4’24’ Length of header
DC FL4’4’ Number of rows in directory
DC FL4’0’ Word of zeros
DC FL4’32’ Length of directory entry
* Start of definition of first entry
DC CL8’MYF1 ’ Name used in command list
DC FL4’0’ Address of preloaded code
DC FL4’0’ Reserved field
DC CL8’ABCFUN1 ’ Name of entry point
DC CL8’FUNCTDD1’ DD from which to load entry point
* Start of definition of second entry
DC CL8’MYF2 ’ Name used in command list
DC FL4’0’ Address of preloaded code
DC FL4’0’ Reserved field
DC CL8’ABCFUN2 ’ Name of entry point
DC CL8’FUNCTDD1’ DD from which to load entry point
* Start of definition of third entry
DC CL8’MYS3 ’ Name used in command list
DC AL4(ABCSUB3) Address of preloaded code
DC FL4’0’ Reserved field
DC CL8’ABCFUN3 ’ Name of entry point
DC CL8’FUNCTDD1’ DD from which to load entry point
* Start of definition of fourth entry
DC CL8’MYF4 ’ Name used in command list
DC VL4(ABCFUNC4) Address of preloaded code
DC FL4’0’ Reserved field
DC CL8’ ’ Name of entry point
DC CL8’FUNCTDD1’ DD from which to load entry point
SPACE 2

END DSIRXUFP

Figure 11. Example of a Function Package Directory

In Figure 11, the name of the function package directory is DSIRXUFP, which is
one of the dummy function package directory names provided with NetView. Four
entries are defined in this function package:
v MYF1, an external function
v MYF2, an external function
v MYS3, a subroutine
v MYF4, an external function

102 Programming: Assembler

Chapter 7. Control Blocks
This chapter describes control block fields related to customization interfaces. The
other fields that can be in control block mapping macros are those containing the
internal use control information and are not to be used as a programming
interface.

NetView control blocks and buffers passed to installation exits and command
processors are intended for read-only use. Do not alter them, except for fields
specifically designed as user fields, such as TVBUFLD, CWBSAVEA, and
CWBADATD.

MVTUFLD, TVBUFLD, and TIBUFLD are user fields. They are 4-byte fields that
the NetView program does not modify or refer to. User fields are for code that is
not NetView code, such as customer code or other applications running on the
NetView program.

One DSIMVT and one MVTUFLD field exist for each NetView program. One
TVBUFLD and one TIBUFLD exist for each NetView subtask and for each optional
task.

Any product that uses task user fields can remove valuable NetView resources.
Some NetView functions can keep you from overriding task user fields. See
“DSIPUSH: Establish Long-Running Command” on page 223 for information about
the DSIPUSH function.

Because only a single set of user fields is provided, use a method to communicate
the application usage of a particular field so that subsequently developed
applications do not interfere with the existing usage of the field. Use one of these
methods or one of your own:
v Any application or product using any field should document its use. If a task
user field (such as TVBUFLD or TIBUFLD) is used, document the name of the
task (such as TVBOPID or TVBLUNAM) for anyone who uses the application or
product.
For example, if a component of a product is coded to run as an optional task,
and the product uses the TIB or TVB user fields of that optional task, include
that information in the product documentation.
v The TVBUFLD and TIBUFLD fields of a non-NetView task are under the control
of the code that “owns” the task. In the previous example, if a customer queries
the value in the TVBUFLD of every TVB on the TVB chain, do not query the
TVBUFLD in the optional task. The product can be using the TVBUFLD of its
task for a purpose that conflicts with the customer’s intended use.

BUFHDR: Buffer Header

All message and command buffers have an initialized buffer header (BUFHDR)
preceding the buffer text. BUFHDR describes the size and use of the buffer, and
the origin of the message or command. The items marked with an asterisk (*) in
Figure 12 on page 104 are the BUFHDR fields you must initialize.

© Copyright IBM Corp. 1997, 2015 103

BUFHDR

BUFHDR is a separate DSECT contained in the task information block (DSITIB). To

obtain the BUFHDR DSECT, use the DSICBS macro to include the TIB control
block.

The size of the BUFHDR was increased in a previous release of the NetView
program. The BUFHDR presentation-extension fields shown in Figure 12 were
added.

Standard Buffer Header

0 (0)
HDRMLENG * HDRBLENG *
Message Length Total Length of Buffer
4 (4)
HDRIND HDRMTYPE * HDRTDISP *
Line Type Message Type Displacement to the first
character of the text from
start of header
8 (8)
HDRTSTMP
Time Stamp Field
12 (12)
HDRDOMID
Domain Identification

20 (14)
Reserved Area

BUFHDR Extension - HDRMCEXT (used by DSIMQS macro)

24 (18)
HDRNEXTM
Chain Field
28 (1C)
HDRSENDR
Operator ID of sending subtask
32 (20)

36 (24) BUFHDR presentation extension (used for presentation attributes)

HDRTLEN HDRTTYPE
Text Object Length Text Object Length
40 (28)
HDRTLNTY HDRTPCON HDRTPCOL
Line type flags-2 bytes Presentation Presentation
Control Color
44 (2C)
HDRTPHIL HDRTPINT
Presentation Presentation
Highlighting Intensity

Figure 12. Buffer Header (BUFHDR)

An initialized BUFHDR has the fields set as shown in Table 16 on page 105:

104 Programming: Assembler

 BUFHDR

Table 16. Control Block Fields

Field Name Length Description
BUFHDRND 0 Label at the end of BUFHDR for use in computing the
length, in bytes, of BUFHDR.
HDRBLENG 2 The length, in bytes, of the entire buffer: header, text, and
unused space. This length is used if the buffer is to be
released with macro DSIFRE. It is a number 0 - 32767.
HDRDOMID 8 The identifier of the domain that originated the message.
This field is displayed and logged.

The domain identifier under which a particular program is

running is shown in the MVTCURAN field of the main
vector table (DSIMVT). The value of HDRDOMID equals
the value of MVTCURAN. MVTCURAN is an 8-byte field
that contains a field DOMAINID of 5 bytes and is padded
on the right with blanks. The 3 bytes farthest to the right
are reserved.
HDRIND 1 This field is normally set to 0, except when
HDRMTYPE=HDRTYPEJ, HDRTYPEK, or HDRTYPEL. In
these cases:
HDRLNCTL TYPE = CONTROL LINE
HDRLNLBL TYPE = LABEL LINE
HDRLNDAT TYPE = DATA LINE
HDRLNEND TYPE = DATA END LINE.
Note: A multiline message within the NetView program
can end with a buffer that contains no data, but it is
simply marked as the end of the multiline message
(HDRIND = HDRLNEND). In this case, the HDRMLENG
field of this last buffer is 0.

When HDRMTYPE=HDRTYP10:
HDRLNMSU TYPE=MSU DATA BUFFER
HDRLNHIR TYPE=MSU HIERARCHY BUFFER
HDRMCEXT 12 An extension that is appended to the BUFHDR when a
buffer is transferred from one subtask to another. Except
for a buffer with HDRMTYPE of HDRTYPEI (an IFR),
which must already have an extension, macro DSIMQS
BFRFLG=NO builds this extension when it creates a buffer
copy for the destination task. If you want to pass the
actual buffer with DSIMQS BFRFLG=YES, you must build
the extension and initialize HDRSENDR.
HDRMLENG 2 The length, in bytes, of the text in the buffer.
HDRMSG 0 Label to indicate the place for text to begin if HDRMCEXT
is present.
HDRMSGLN 0 Label at the end of HDRMCEXT for use in computing the
length, in bytes, of BUFHDR+HDRMCEXT.
HDRMTYPE 1 Indicates the current use of the buffer or the origin of the
command. If the buffer is written using macro DSIPSS, this
character is displayed and logged. For a list of values for
HDRMTYPE, see Table 18 on page 106.
HDRNEXTM 4 Multiline write-to-operator (MLWTO) buffer chain pointer;
points to the next buffer in the chain.

Chapter 7. Control Blocks 105

BUFHDR

Table 16. Control Block Fields (continued)

Field Name Length Description
HDRSENDR 8 The originator's operator ID as found in the sender's
TVBOPID field of the task vector block (DSITVB).
HDRTDISP 2 The offset from the start of the buffer header to the first
byte of text.
HDRTEXT 0 Label to indicate the place for text to begin if HDRMCEXT
is not present.
HDRTSTMP 4 The time that the buffer was created, in the packed
decimal form hhmmss X'0C', where:
hh Is the hour of the day, from 00–23
mm Is the minutes of the hour, from 00–59
ss Is the seconds of the minute, from 00–59
0C Is a packed decimal sign

To obtain values for this field, use DSIDATIM. See

“DSIDATIM: Date and Time” on page 165.
Text 2 HDRTDISP indicates where the text starts.

Values for HDRIND Fields

The following table shows the values for the HDRIND fields:
Table 17. Values for HDRIND Fields
Field Value Meaning
HDRLNCTL The control line of the BUFHDR.
Note: If you use HDRTCONT, set HDRLNTYP to the value of
HDRLNCTL, and set HDRMTYPE to HDRTYPEJ, HDRTYPEK, or
HDRTYPEL.
HDRLNDAT The data line of the BUFHDR.
Note: If you use HDRTDATT, set HDRLNTYP to the value of
HDRLNDAT, and set HDRMTYPE to HDRTYPEJ, HDRTYPEK, or
HDRTYPEL.
HDRLNEND The end line of the BUFHDR.
Note: If you use HDRTENDT, set HDRLNTYP to the value of
HDRLNEND, and set HDRMTYPE to HDRTYPEJ, HDRTYPEK, or
HDRTYPEL.
HDRLNLBL The label line of the BUFHDR.
Note: If you use HDRTLABT, set HDRLNTYP to the value of
HDRLNLBL, and set HDRMTYPE to HDRTYPEJ, HDRTYPEK, or
HDRTYPEL.
HDRLNMSU The length, in bytes, of the MSU data buffer.

Values for HDRMTYPE Fields

The following table shows the values for the HDRMTYPE fields:
Table 18. Values for HDRMTYPE Fields
Field Value Meaning
HDRTYPDT Indicates non-message data type.
(D)

106 Programming: Assembler

 BUFHDR

Table 18. Values for HDRMTYPE Fields (continued)

Field Value Meaning
HDRTYPEB (?) Indicates a command or command list buffer that suppresses display and
logging. It is not displayed on the operator's screen. This field type is used
to suppress display and logging of commands entered with a suppression
character as defined in the CNMSTYLE initialization member. It is also
used to suppress display and logging of command list statements that are
preceded by this same suppression character.
HDRTYPEC Indicates a command or message from a command list. This field type
(C) changes to HDRTYPEB for suppressed command list statements. It
changes to HDRTYPQC for quiet commands.
HDRTYPED (!) Indicates a message from an immediate command processor. It is usually
sent to the screen using DSIPSS TYPE=IMMED. When displayed in the
immediate message area on the screen, the HDRMTYPE and DOMAIN
name are not displayed. When received cross-domain, this type of message
is in the normal output area, along with its domain name and type prefix.
DSIPSS TYPE=IMMED does not enforce or set HDRTYPED.
HDRTYPEE Indicates a message from the operating system interface. This type is not
(E) used for title-line mode (MLWTO), system action, or WTOR messages.
Also see HDRTYPEK and HDRTYPEY for other forms of operating system
interface messages.
HDRTYPEF Indicates a VSAM record. This is not displayed on the operator's screen.
(F) This type is used within the data services task (DST).
HDRTYPEG Indicates a CNMI record. This is not displayed on the operator's screen.
(G) This type is used within the data services task (DST).
HDRTYPEI (I) Indicates an internal function request (DSIIFR). This buffer is a formatted
interface within and between tasks. The IFR contains a function number
(IFRCODE) that determines the format and function of the buffer.
HDRTYPEJ (') Indicates a title-line (MLWTO) message originating from the NetView
program. These buffers must be in a sequence and include a description of
control, label, data, and end designators. The NetView program treats
these sequences of buffers as a single message for presentation and
automation.
HDRTYPEK The same as HDRTYPEJ but for IBM non-NetView code.
(")
HDRTYPEL The same as HDRTYPEJ but for non-IBM written code.
(=)
HDRTYPEM Indicates a message from the NetView message command processor.
(M)
HDRTYPEN Indicates a regular single buffer message from the NetView program.
(-)
HDRTYPOR Indicates a message generated in a pipeline. The vertical bar character (|)
(|) is an EBCDIC X'4F'.
HDRTYPEQ Indicates a message from the VTAM POI that is a single-buffer unsolicited
(Q) message. See also HDRTYPEV, HDRTYPEY, and HDRTYPEK for other
VTAM POI messages. This message type is not set for messages from
VTAM received on the operating system interface.
HDRTYPER Indicates that an operator entered the VTAM REPLY command in response
(R) to NetView WTOR number DSI802A. This message type is logged but
does not appear on NetView consoles.
HDRTYPES (S) On some installation exit interfaces, HDRMTYPE is set to HDRTYPES to
indicate a swapped buffer.

Chapter 7. Control Blocks 107

BUFHDR

Table 18. Values for HDRMTYPE Fields (continued)

Field Value Meaning
HDRTYPET (*) Indicates a command issued to the NetView program from a NetView
terminal. This message type indicates that the buffer is a command rather
than a message. HDRTYPET generally implies a command buffer as if an
operator had typed the command. HDRTYPET buffers cannot contain
non-printable text.
HDRTYPEU Reserved for non-IBM users. This type cannot be used for action messages
(U) (WTOR) or title-line (MLWTO) messages.
HDRTYPEV Indicates a message from the VTAM POI that is a single-buffer solicited
X'40' message. Also see HDRTYPEQ, HDRTYPEY, and HDRTYPEK for other
VTAM POI messages. This message type is not set for messages from
VTAM received on the operating system interface.
HDRTYPEW Indicates an IBM-written single-line message. This type is similar to
(+) HDRTYPEN and HDRTYPEU.
HDRTYPEX Indicates a cross-domain (NNT-OST) command.
(X)
Code running in an NNT can issue DSIPSS TYPE=OUTPUT for a
HDRTYPEX buffer, and the corresponding command is executed in the
OST that started the session with that NNT. This message type is useful
for sending unformatted (hexadecimal) data from the NNT to an OST for
full-screen or other formatting. This type is limited to 256 bytes. It is not
displayed on the operator's screen.
HDRTYPEY Indicates single-buffer action or WTOR. This type can be a message from
(>) the operating system interface and from the VTAM POI. These messages
remain on the screen until an action is taken or the reply is entered. The
operator can delete these messages by overstriking the > character and
pressing ENTER. The message disappears the next time the screen wraps
over the text.

When the HDRTYPEY flag is set and the IFRAUWQE flag is not set, the
NetView program looks for a 3-character reply ID immediately preceding
the message number in the message text. If this reply ID exists, then the
message is a VTAM WTOR. Otherwise, the message is treated as a held
message.

If IFRAUWQE is set to 1, the IFRAUWQD data is checked to see if the

WQE data indicates a WTOR or action message. A WTOR is indicated if a
2-character reply ID immediately precedes the message ID. If the reply ID
exists, it is delimited from the message ID by one space. Otherwise, the
message is an action message.
HDRTYPEZ Similar to HDRTYPEN but specifically indicates a message from a data
(Z) services task (DST).
HDRTYPE$ ($) Indicates a non-displayable data message. This type is used for data
transfer between high-level language command procedures.
HDRTYPLT Indicates a trace record, not a message buffer. This message type is used
(L) exclusively for NetView Internal Trace and must not be used in any
message buffer.
HDRTYPLX Indicates a message response from a UNIX command.
(x)
HDRTYPQC Indicates a command with all synchronous messages suppressed
X'32' (performance option).
HDRTYPTS (t) Indicates a message response from a TSO command.
HDRTYPWB Indicates a command issued from the NetView Web browser. This message
(B) type indicates that the buffer is a command rather than a message.

108 Programming: Assembler

 BUFHDR

Table 18. Values for HDRMTYPE Fields (continued)

Field Value Meaning
HDRTYPWT Indicates a message that matched an &WAIT and was displayed. The W
(W) appears in the Match Fonts field on the panel and in the logs but is not in
the HDRMTYPE field in the buffer. The HDRMTYPE field in the buffer
contains the original message type.
HDRTYPE1 Indicates a PPOLOG echo of console operator command.
(V)
HDRTYPE2 Indicates a PPOLOG copy of console message, suppressed or
(Y) unsuppressed.
HDRTYP10 Indicates a management services unit (MSU) data buffer.
X'10'
HDRTYPZZ Indicates an end-of-response message.
X'37'

BUFHDR Presentation Extension

Presentation information is present in all text data buffers in automation internal
function request (AIFR) structures if you have turned on the IFRAUMVI indicator.
Table 19 shows the values for the HDRMCEXT fields.

Note: You must index HDRTDISP beyond HDRTMSGT.

Table 19. Description of HDRMCEXT Fields
Field Name Length Description
HDRTLEN 2 The length of the text object (10 decimal).
HDRTTYPE 2 The type of text object.
Value Meaning
HDRTOBJ
The type value for the message text object.
HDRTLNTY 2 The line type flags. The first byte is the value of
HDRLNT1; the second is the value of HDRLNT2. For
information on using this field, see “DSITIB: Task
Information Block” on page 145 and the programming
notes in the DSITIB macro.
HDRTPCON 1 Alarm indication. (Not used by the NetView program.) To
use this field, see the programming notes in the DSITIB
macro.

Chapter 7. Control Blocks 109

BUFHDR

Table 19. Description of HDRMCEXT Fields (continued)

Field Name Length Description
HDRTPCOL 1 The presentation color field. The following HDRTPCOL
color values override any other setting for the foreground
color for one line of a multiple line message or the entire
message for single-buffer messages:
Value Meaning
HDRDEFCO
Default color
HDRBLACK
Black
HDRBLUE
Blue
HDRRED
Red
HDRPINK
Pink
HDRGREEN
Green
HDRTURQ
Turquoise
HDRYELLOW
Yellow
HDRWHITE
White

To use this field, see the programming notes in macro

DSITIB.
HDRTPHIL 1 The foreground highlighting.

To use this field, set both HDRTFPAF and IFRAUMVI on.

Value Meaning
HDRDEFAU
Default highlighting
HDRHNONE
No highlighting
HDRBLINK
Flashing characters
HDRRVIDO
Reverse video
HDRUNDER
Underscored characters

To use this field, see the programming notes in macro

DSITIB.

110 Programming: Assembler

 BUFHDR

Table 19. Description of HDRMCEXT Fields (continued)

Field Name Length Description
HDRTPINT 1 Foreground intensity.
Value Meaning
HDRINDEF
Default intensity
Note: A value of HDRINDEF causes checking of
fields in DSIAIFRO, the screen format values
from the DEFAULTS and OVERRIDE commands,
or the NetView standard default table.
HDRINORM
Normal intensity
HDRIHIGH
High (bright) intensity

To use this field, set both HDRTFPAF and IFRAUMVI on.

HDRTMSGT 0 The end of the BUFHDR presentation extension.
HDRTDISP must index beyond this point.
Note: Do not use HDRTMSGT to reference message text.
HDRTDISP is the true offset to text start.

Example Scenario of BUFHDR Usage

Macro DSIDKS uses the buffer header when reading a disk data set. You specify
the blocking factor to block the disk data set. The disk services module DSIDRS
prefixes the physical read buffer with a BUFHDR.

When the first record is requested, macro DSIDKS reads the first block. HDRTDISP
is adjusted to indicate the first logical record. DSIDKS also sets HDRMLENG to
reflect the logical record length. When DSIDKS is issued for the next logical record,
HDRTDISP is adjusted to indicate the next logical record until the block is
exhausted. DSIDKS reads another physical record; the process starts again from the
first logical record in the block.

DSIAIFRO: Automation Vector Extensions

The DSIAIFRO maps the extensions to the AIFR, which are in vector-object format.
These extensions are chained from the base AIFR. The first DSIAIFRO of the chain
is contained in the base AIFR.

Modifications of the AIFR Format

Figure 13 on page 112 shows a diagram of the AIFR with a chain of DSIAIFRO
objects. Figure 14 on page 114 shows a diagram of the AIFR extension.

Chapter 7. Control Blocks 111

DSIAIFRO

AIFR

256 Bytes

16 DSIAIFRO
Bytes IFRAUVPT Object 2

DSIAIFRO
Object 3

Figure 13. DSIAIFRO Chain

Every AIFR extension (pointed to by IFRAUVPT) is in the format of an SNA GDS

variable that can contain other SNA GDS variables. The contained items are called
objects and are of the following form:
LLLLKKKKD...D,

Where:
LLLL Represents a 2-byte length field
KKKK
Represents a 2-byte type-identification field
D...D Represents either data values, or one or more contained objects

An AIFR extension is an object that can contain objects. In general, the objects it
contains are unordered. Its first contained object is necessarily the next extension
locator, and the next extension locator must be present and must be first.

The format of AIFR extension offsets is as follows:

01 AIFR extension length, including this length field (n+1).
23 AIFR extension type code = X'0010'.
4n The AIFR extension. n is determined by the preceding length field.
Offsets
Description
45 Length of first part of the AIFR extension

(m+1-4 = m-3)
67 Code for first part of the AIFR extension

112 Programming: Assembler

 DSIAIFRO

8m Value or content of first part of the AIFR extension

m+1 m+2
Length of second part of the AIFR extension (k-m)
m+3 m+4
Code for second part of the AIFR extension
m+5 k Value or content of second part of the AIFR extension
... Third and later parts of the AIFR extension

The minimum value of n is 15; that is, the minimum length of the AIFR extension
is 16. There must be at least one contained object, because the first part of the AIFR
extension must be the next extension locator.

The format of this locator is:

4 5 Length of next extension locator (12)
6 7 Code for next extension locator = X'0011'
8 11 Address space identifier for the next AIFR extension
12 15 Address of the next AIFR extension

If the address (positions 12-15) is zero, there is no further AIFR extension.

Note: In the NetView message processor, the maximum length of a DSIAIFRO

object is 4 kilobytes.

The address space identifier is in access list entry token (ALET) format. When this
identifier is set to zero, the extension is in the same address space as the base. (The
ALET is an S/370 architecture item, and is not operating system specific.)

Format of the Message Control Object

A message control object can contain data from an MDB and its source object. The
message control object is mapped by DSIMCO, which is contained within
DSIAIFRO. The message control object, together with its contained objects, is used
to transport the MDB data from a message data block. The message control object
is one of the objects that can be included in a DSIAIFRO object. It is in the format
of an SNA generalized data stream (GDS) variable that can contain other GDS
variables. It begins with a 2-byte field that defines the length of the object,
followed by a 2-byte code identifying it as a message control object. All of its
contained objects are in the same form.

The message control object can contain an MDB global object and a source object.
In turn, the MDB global object can contain a general object and a control program
object. An example of this “nesting” is shown in Figure 14 on page 114:

Chapter 7. Control Blocks 113

DSIAIFRO

IFRAUVPT
or DSIAIFRO
AIFNXPTR
Next extension locator object Must be first

DSIMCO (optional)

DSIMSO (optional)

DSIMSOSB

DSIMSOSB (optional)
DSIMSO and DSIMGO
(optional) can be in either
order within DSIMCO
DSIMGO (Optional)

DSIGOJ

DSICPO (Optional)

Figure 14. Example of an AIFR Extension

Table 20 details the self-identifying codes for the message control object and the
objects it can contain.
Table 20. Message Control Object Type/Self-Identifying Code Matrix. All objects have 2-byte
lengths and 2-byte codes; some objects might be absent.
Object Type Map Name in DSIAIFRO Self-Identifying Code
Message Control Object DSIMCO 0006
MDB Global Object DSIMGO 0007
MDB General Object DSIGOJ 0001
MDB Control Program DSICPO 0002
Object
Source Object DSIMSO 0005
1
MDB NLS (none) 0003
2
MDB Message Text Object DSITOJ 0004
Note:
1. MDB NLS is not used.
2. MDB Message text objects are not contained in DSIMCO. The data from the MDB
message text objects is stored in the IFRAUTBA buffer chain.

Format of the Source Object

The source object is mapped by DSIMSO, which is contained within DSIAIFRO.
The source object is used to identify the origin of an MDB and is one of the objects
that can be included in a message control object. It is in the format of an SNA
generalized data stream (GDS) variable that can contain other GDS variables. It
begins with a 2-byte field that defines the length of the object, followed by a 2-byte
code identifying it as a source object. Following that initial 4-byte descriptor, there
are as many sub-objects as needed up to a maximum of 1100 bytes.

The following list shows the codes for a subobject (part of the source object
containing a name):
D5 The nickname, in character format 1 – 8 bytes

114 Programming: Assembler

 DSIAIFRO

01 The NETID from the MDS-MU header 1 – 8 bytes

02 The NAU name from the MDS-MU header 1 – 8 bytes

Note: Characters for these fields can be from the coded graphic character set
01134–00500. Trailing EBCDIC blanks are permitted but are insignificant. This set
consists of capitals A – Z and numerals 0 – 9, without punctuation or special
symbols.

Source
Object Sub-object 1 Sub-object 2 Sub-object n
Header

Figure 15. Source Object Diagram. Source Object has 2-byte length and 2-byte code. Each
Sub-object has 1-byte length, 1-byte code, and data.

The source object name identifies the origin of the message in the MDB. The name
of the source is selected using the following hierarchy from the sub-objects
contained in the source object:
1. The first nickname, if any. If no nickname is found, go to step 2.
2. The first NETID concatenated to a NAU name, with a period (.) between them,
if both exist in sequence. If that combination is not found, go to step 3.
3. The first NAU name, if it exists. If that is not found, go to step 4.
4. Either the character string N/A if none of listed names exist, or null if the
message has no source object vector, or if the vector data has structural damage
(unacceptable length fields, for example).

DSICBH: Control Block Header

The control block header (DSICBH) precedes all NetView control blocks, except the
BUFHDR and the internal function request (DSIIFR) control block. CBH identifies
the length and type of control block that follows it, and the type of subtask the
control block represents.

The fields in the DSICBH are as follows:

Table 21. Control Block Header Fields
Field Name Length Description
CBHID 1 A 1-character identifier of the control block. CBHPDB is
the identifier for a parse descriptor block (DSIPDB).

Chapter 7. Control Blocks 115

DSICBH

Table 21. Control Block Header Fields (continued)

Field Name Length Description
CBHTYPE 1 The type of subtask that the control block represents. (The
TIB and the TVB each contain this identifier.) The types
are the primary POI task (PPT), the operator station task
(OST), the NetView-NetView task (NNT), the hardcopy
task (HCT), a data services task (DST), and the optional
subtask (OPT). The DSILCS macro uses this field for
managing command work blocks (DSICWBs) and service
work blocks (DSISWBs). In all other cases, this byte is
reserved.
CBHHCT
The identifier used for a TIB or a TVB belonging
to an HCT
CBHMNT
The identifier used for a TIB or a TVB belonging
to an MNT
CBHNNT
The identifier used for a TIB or a TVB belonging
to an NNT
CBHOPTSK
The identifier used for a TIB or a TVB belonging
to an OPT or a DST
CBHOST
The identifier used for a TIB or a TVB belonging
to an OST
CBHPPT
The identifier used for a TIB or a TVB belonging
to the PPT
CBHLENG 2 A halfword that contains the length of the control block.
CBHLENG represents either the length that is preallocated
or the length that is obtained by macro DSIGET. For
example, a parse descriptor block (DSIPDB) has both a
fixed-size portion and a variable number of entries. For a
DSIPDB, CBHLENG contains the length of both parts. This
field is to be treated as a 16-bit unsigned binary
(maximum 65535).

DSICWB: Command Work Block

The command work block (DSICWB) contains the command processor parameters,
a save area, and a work area. The following fields are in the DSICWB:
Table 22. Command Work Block Fields
Field Name Length Description
CWBCBH 4 A standard control block header.
CWBADATD 256 A work area for the command processor. If more storage is
required, the command processor obtains it with macro
DSIGET and releases it with macro DSIFRE. The command
processor frees any storage it obtains.
CWBBUF 4 A pointer to a buffer containing a BUFHDR and the
command text.

116 Programming: Assembler

 DSICWB

Table 22. Command Work Block Fields (continued)

Field Name Length Description
CWBDSRB 4 Used only by data services command processors (DSCPs).
The data services task (DST) initializes this field with the
address of the data services request block (DSIDSRB). This
field contains 0 for all other command processor types.
CWBPARMS 12 A command processor parameter area. Its subfields are
CWBBUF, CWBPDB, and CWBSWB.
CWBPDB 4 A pointer to a parse descriptor block (DSIPDB), which is
described under “DSIPDB: Parse Descriptor Block” on
page 142. The PDB contains parse information for the
command pointed to by CWBBUF. If a special type of
parse is required, the command processor can reuse the
PDB.
CWBPECB 4 A pointer to a parameter list containing the address of the
posted ECB and an environment pointer. The parameter
list is mapped by the DSITECBR control block. DSITECBR
contains the returned parameter list when an ECB is
posted on a DST list.
CWBRCODE 4 On resumption, an LRC receives a return code from a
called command.
CWBSAVEA 72 A save area that the command processor can use.
CWBSWB 4 A pointer to a service work block (DSISWB) that the
command processor can use or pass as a parameter to
service macros or modules. Service macros build
parameter lists in the SWB for the service modules. The
SWB also contains a task information block (DSITIB)
pointer, a parameter list, and a save area for use by the
service routine. You can reuse SWBs without
reinitialization. Service routines or macros need only the
CBH and the TIB address.
CWBTIB 4 The address of the TIB for the subtask. The TIB and the
task vector block (DSITVB) to which the TIB field TIBTVB
is pointed contains all the information that relates to the
subtask under which the command is running. This
information contains the operator ID, the task type, and
the task status.

DSIDSB: Data Services Block

The data services block (DSIDSB) contains information used by the disk read
service routines called when the DSIDKS macro is issued. The following fields are
used by the issuer of DSIDKS to access the records read:
Table 23. Data Services Block Fields
Field Name Length Description
DSBBUFF 4 The address of the I/O buffer containing the record read
from the data set member. The buffer contains a BUFHDR
with HDRTDISP containing the offset of the requested
logical record.
DSBREC 4 The address of the requested logical record read using the
DSIDKS macro.

Chapter 7. Control Blocks 117

DSIDSRB

DSIDSRB: Data Services Request Block

The data services request block (DSIDSRB) contains information that a data
services command processor (DSCP) needs to communicate with the data services
task (DST). It also contains workspace for the I/O routines. The following list
shows the relevant fields in the DSIDSRB:
Table 24. Data Services Request Block Fields
Field Name Length Description
DSRBCBH 4 A standard control block header.
DSRBCUSB 4 The address of a buffer used by the CNMI for unsolicited
data. This field is used only when the DSRB function code
(DSRBFNCD) indicates that unsolicited data has been
received. The buffer contains a BUFHDR, and the data
length is in the HDRMLENG field of BUFHDR.
DSRBFLG 1 The flag settings. The bits can be examined but not
changed.
DSRBACTV = 1
An active transaction is using this DSRB. A
transaction is defined as a request from the time
of its first arrival at the DSCP to the last exit of
the DSCP. When a transaction ends, you can
reassign the DSRB to another transaction.
DSRBINUS = 1
The VSAM or the CNM interface service routine
has an active request using this DSRB. DSRBINUS
is not on when DSRBACTV is off.
DSRBTYPE = 1
The DSRB is used for unsolicited CNM data.
DSRBTYPE = 0
The DSRB is used for VSAM or CNM solicited
data traffic.
DSRBFLGS 1 The flag settings. The bits can be examined but not
changed.
DSRBCPMS = 1
The alert was generated from the distributed host.
DSRBCPMS = 0
The alert came from the local CNMI.
DSRBFNCD 1 Indicates the reason that the command processor was
called. The following list shows the constants for
DSRBFNCD:
DSRBFNRM (1)
The first calling of the command processor, as the
result of an IFRCODCR queued from another
subtask using DSIMQS.
DSRBFUNS (2)
The command processor was called to handle
unsolicited CNM data.
DSRBFSOL (3)
Solicited data was received from the CNMI.
DSRBFVSM (4)
A VSAM I/O request has completed.

118 Programming: Assembler

 DSIDSRB

Table 24. Data Services Request Block Fields (continued)

Field Name Length Description
DSRBINPT 4 The address of the CNM interface input buffer.
DSRBOID 8 The ID of the operator that initiated the transaction.
DSRBPRID 2 A halfword field that contains a correlation identifier for
use by the CNM interface.
DSRBRCMA 4 The return code for a completed request. It is set after the
request is completed but before the DSCP is called again
for request completion. This return code value is further
explained by the minor return code (DSRBRCMI). See
“DSCP Interface” on page 92 for a description of the
return codes.
DSRBRCMI 4 The minor return code for a completed request. See
DSRBRCMA.
DSRBTIB 4 The address of the DST information block (DSITIB).
DSRBUBUF 4 The address of the original command that was sent to the
DST. This field is unchanged during the data services
transaction. This buffer contains a BUFHDR and the
HDRMCEXT extension. It also has an X'0003' IFRCODE
and HDRTYPEI. See “DSIIFR: Internal Function Request”
on page 120.
DSRBUSER 4 A field available for user purposes. If this field is used for
a storage address, the DST does not free the storage; it is
freed by the user. DSIGET Q=YES allocates storage. You
can free storage by using DSIFRE Q=YES. The field
DSRBUSER is set to zero (0) when the control returns to
DST unless the DSRB is considered in use (DSRB's field
DSRBFLG is set to DSRBINUS). If you do not free storage,
the storage remains allocated but not addressable and this
storage is not freed until the subtask ends.
DSRBVACB 4 The address of the VSAM ACB for the DST.
DSRBVDAD 4 The address of the VSAM I/O buffer with a standard
BUFHDR. For GET requests, the BUFHDR HDRMLENG
field indicates the length of the data read. HDRTDISP
contains the offset to the data.
DSRBVECB 4 An event control block (ECB) for use by DST when
requesting VSAM I/O.
DSRBVKEY 4 The address of the key in the DSRBVDAD buffer.
DSRBVKLN 2 The key length.
DSRBVRPL 4 The address of the VSAM request parameter list (RPL)
that was used for the I/O.
DSRBVRTP 1 An indicator of the type of request just completed:
1 - DSRVGET (VSAM GET)
2 - DSRVPUT (VSAM PUT)
3 - DSRVPNT (VSAM POINT)
4 - DSRVERS (VSAM ERASE)
5 - DSRVNRQ (VSAM ENDREQ)

Chapter 7. Control Blocks 119

DSIDTR

DSIDTR: Data Transport Request

The data transport request (DSIDTR) control block is used to pass a request to the
NetView program-to-program interface (PPI). For field names and descriptions,
refer to the IBM Tivoli NetView for z/OS Application Programmer's Guide.

DSIELB: External Logging Block

The external logging block (DSIELB) maps the header information about the buffer
passed to the XITXL exit.

The following table describes the XITXL exit fields:

Table 25. External Logging Block Fields
Offset Name Length Description
0 ELBLENG 2 Unsigned length of DSIELB
5 ELBLOG 3 EBCDIC log type
2 ELBRLENG 2 Unsigned length of record
4 ELBTYPE 4 Log type
8 4 Reserved by the NetView program
12 Start of record

DSIIFR: Internal Function Request

The internal function request (DSIIFR) is a formatted buffer that is transmitted to a
subtask's message queue using macro DSIMQS. One relevant field in the DSIIFR is:
Table 26. Internal Function Request Field
Field Name Length Description
IFRCODE 2 bytes The following list shows the most commonly specified
examples:
IFRCODAI
A NetView automation internal function request
(AIFR). See “AIFR–Automation Internal Function
Request” on page 121 for the subfields of the
AIFR.
IFRCODCR
The remainder of the buffer is a command to run.
IFRCODPN
The command is entered from a full-screen panel.
IFRCODUS
The buffer is user-defined and is passed to
DSIEX13, the message receiver exit routine
(applies only to an OST or NNT).

For a complete list of IFRCODEs, see the DSIIFR macro.

For the IFR, the value of HDRTDISP is always decimal 36, which includes a
standard 24-byte BUFHDR and a 12-byte HDRMCEXT. The IFRCODE must begin
immediately after the BUFHDR extension (at displacement decimal 36 as indicated
by the HDRTDISP value).

120 Programming: Assembler

 AIFR

AIFR–Automation Internal Function Request

The following fields are defined starting at the location with the IFRPARMS label
when IFRCODE=IFRCODAI.

Note: The AIFR is 256 bytes, including the headers.

Table 27. Automation Internal Function Request Fields
Length or Subfield or
Field Name Mask EQU Description
IFRAUIND 1 byte NA Contains the primary AIFR control flags. These
identify optional fields and describe routing
and processing actions as follows.
1... .... IFRAUWQE See the IFRAUSSI subfield. When this flag is
on, subfields in the IFRAUWQD field are set
from the WQE data received from the system.
This data is also forwarded to all NetView
domains by NNT tasks and RMTCMD
autotasks.
Notes:
1. If the IFRAUTBA buffer has
HDRMTYPE=HDRTYPEY and the
IFRAUWQE flag is on, the message must
have a 2- to 4-digit EBCDIC reply ID in
front of the message number in the text.
2. Whenever MDB fields are present and have
corresponding WQE fields, the WQE fields
are set from the MDB fields when the AIFR
structure is created, and the IFRAUWQE
subfield is set on. This preserves the
meaning of WQE data accessed by
command list variables and the automation
table in existing functions.
.1.. .... IFRAUCMD Set by the NetView automation table to indicate
that an action is in the buffer referenced by
IFRAUCMB. Each command action for a
particular message has a separate AIFR
structure.
Note: IFRAUCMD and IFRAUACT cannot both
be on at the same time.
..1. .... IFRAUACT Indicates that MSG/MSU actions exist in the
bits in the IFRAUTA1 and IFRAUTA2 fields.
See the IFRAUTA1 and IFRAUTA2 fields for
settings controlled by the IFRAUACT subfield.

The IFRAUCMD subfield and the IFRAUACT

subfield cannot both be on at the same time. If
both the IFRAUCMD and IFRAUACT subfields
are 0, the buffer is subject to defaults and
overrides. This bit must be on to specify force
flags in IFRAUTA4.

Chapter 7. Control Blocks 121

AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
...1 .... IFRAUMTB Used to control recursion and to prevent
secondary receiver and copied messages from
being processed by the NetView automation
table. This bit can be set to 1 to prevent the
NetView automation table from processing this
message. The IFRAUMTB bit is turned off
when received from an NNT task to automate
cross-domain messages.
Note: Secondary receiver and copied messages
can be automated when received as
cross-domain messages. If the IFRAUMTB bit is
on, WTOs issued by the NetView program
must be issued with descriptor code 13 to
prevent reautomation, if the AIFR message is
written to a system console.
.... 1... IFRAUPPT Indicates that a message originated in the PPT
task. This bit replaces the P designation in byte
7 of the HDRDOMID subfield. The P is
displayed and logged only as part of the
domain name but is never in the buffer header.
.... .1.. IFRAUXDM Indicates that a message was received from an
NNT task or an RMTCMD autotask. This bit
can be used to determine if a message came
from another domain.
.... ..1. IFRAUDOM Indicates that this is a system delete message
request. The system deletes messages by
SMSGID values, by ASID and TCB address, or
by ASID alone. This bit can be set only by the
NetView program. If the GOJGDOM bit is set
on, there are additional types of DOMs as
defined by the DSIAIFRO field.
Note: If you use GOJGDOM bit, turn off the
IFRAUWDO bit. The GOJGDOM bit indicates
the message data block (MDB) form of DOM,
while the IFRAUWDO field indicates the
subsystem interface form of DOM. Keep the
IFRAUDOM field on if either the IFRAUWDO
or GOJGDOM field is on.
.... ...1 IFRAUDFL IFRAUDFL and IFRAUDF2 are valid when
IFRAUWDO is on. IFRAUDFL=OFF and
IFRAUDF2=OFF means delete by SMSGID.
IFRAUDFL=ON and IFRAUDF2=OFF means
delete by ASID. IFRAUDFL=ON and
IFRAUDF2=ON means delete by ASID and
TCB address.
Note: If you use IFRAUWDA or IFRAUWDT,
you must set IFRAUDFL on. Otherwise, set
IFRAUDFL off.
IFRAUIN2 1 byte The second byte of indicator flags is as follows:

122 Programming: Assembler

 AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
1... .... IFRAUDF2 IFRAUDFL and IFRAUDF2 are valid when
IFRAUWDO is on. IFRAUDFL=OFF and
IFRAUDF2=OFF means delete by SMSGID.
IFRAUDFL=ON and IFRAUDF2=OFF means
delete by ASID. IFRAUDFL=ON and
IFRAUDF2=ON means delete by ASID and
TCB address.
Note: If IFRAUWDT is on, IFRAUDF2 must be
set on. If IFRAUWDA is on, IFRAUFD2 must
be off.
.1.. .... IFRAUEX2 Used to prevent calling DSIEX02A, DSIEX04, or
DSIEX09 a second time. This bit is on when
these exits are called to ensure that DSIMQS
queuing of buffers from them does not cause
re-drives. IFRAUEX2 is reset when received as
a cross-domain message.
..1. .... IFRAUPRI Indicates that a message was routed using
ASSIGN PRI. This is the primary copy of the
message and is subject to automation. This bit
replaces the indicator in HDRDOMID. Prevents
ASSIGN COPY.
...1 .... IFRAUSEC Indicates that a message was routed using
ASSIGN SEC. This is a secondary copy of the
message and is not subject to automation. This
bit replaces the indicator in HDRDOMID.
IFRAUMTB is also set on. Prevents ASSIGN
COPY.
.... 1... IFRAUCPY Indicates that a message was routed using
ASSIGN COPY. This is a secondary copy of the
message and is not subject to automation. This
bit replaces the indicator in HDRDOMID.
IFRAUMTB is set on also. Prevents ASSIGN
COPY of copy.
.... .1.. IFRAUAUT Indicates that the buffer was sent using
DSIMQS using authorized receiver routing.
This bit replaces the indicator in HDRDOMID.
.... ..1. IFRAUDLD Indicates that a message was received from a
down-level domain. The AIFR indicators
HDRDOMID and HDRSENDR are not reliable.
.... ...1 IFRAUNSL Indicates that the message is routed using
unsolicited receiver rules. This applies to
unsolicited subsystem interface traffic, DSIMQS
AUTHRCV, and unsolicited VTAM messages.
IFRAUWID 4 bytes NA The SMSGID value used for DOM purposes
and to collect MLWTO buffers. This is a copy of
write-to-operator queue element (WQE) data.

Chapter 7. Control Blocks 123

AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
IFRAUTCB 4 bytes NA The job step TCB address for the issuer of the
write-to-operator (WTO). It is used as a
correlation value and cannot be an address in
the current memory (or machine).
Notes:
1. If you use IFRAUWJT, set IFRAUTCB to the
same value as IFRAUWJT.
2. If you use CPOCTCB, set IFRAUTCB and
IFRAUWJT to the same value.
IFRAUASI 2 bytes NA Reserved for NetView internal use.
IFRAUSRB 2 bytes NA Provided for the user. It is initialized to zeros
when created by the NetView program and is
copied into all copies of the original. It is not
changed.
Notes:
1. You must have a BUFHDR and
HDRMCEXT on all buffers chained to
IFRAUTBA.
2. If you use IFRAUMVI, you must also have
a presentation vector as mapped by the
HDRMDBVI field within BUFHDR.
3. IRFAUSRB and IFRAUSB2 refer to the same
user field in the message, but return the
value in different formats.
IFRAUTBA 4 bytes NA The pointer to data buffers. These are queued
using the HDRNEXTM field to point to the
next data buffer. An entire MLWTO or title-line
message is chained to this field. The buffers
must have standard NetView buffer headers
and message buffer header extensions. If the
IFRAUMVI indicator is on, there must also be a
presentation vector as mapped by the
HDRMDBVI field in the BUFHDR field. See
BUFHDR field within the DSITIB macro.
IFRAUTBL 4 bytes NA Points to the last buffer in the chain and is
primarily intended for allowing buffers to be
added to the end of a message without
scanning the chain looking for the end.

124 Programming: Assembler

 AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
IFRAUTA1 1 byte NA IFRAUTA1 and IFRAUTA2 provide the
NetView automation table processing values.
They can be set by DSIEX02A, but are subject
to NetView automation table and OVERRIDE
command changes. IFRAUACT must be on and
IFRAUCMD must be off for these actions to
take effect for a message. See the IFRAUIND
field notes for additional IFRAUACT
information. The force flags in the IFRAUTA4
field control whether OVERRIDE settings can
alter the effect of the IFRAUTA1 and
IFRAUTA2 indicators.
00.. ....
HOLD - default
10.. ....
HOLD - YES
01.. ....
HOLD - NO
11.. ....
Reserved
..10 ....
Message from MVS
.... 00..
SYSLOG - default
.... 10..
SYSLOG - YES
.... 01..
SYSLOG - NO
.... 11..
Reserved
.... ..00
NETLOG - default
.... ..10
NETLOG - YES
.... ..01
NETLOG - NO
.... ..11
NETLOG - YES, IND, CLS

Chapter 7. Control Blocks 125

AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
IFRAUTA1 1 byte NA Note:
(continued) 1. To specify a setting for HOLD, use the first
two bits of IFRAUTA1 with IFRAUACT.
The GOJGHOLD setting, included in the
AIFR extension mapped by the DSIAIFRO
macro, shows the HOLD setting of the
message as received from an MVS extended
console, and is not used by the NetView
program after its initial examination when
the message is placed in an AIFR.
2. When an automated message is sent across
domains over an OST-NNT session, all
automation table processing values are reset
except for HOLD, DISPLAY, and BEEP.

126 Programming: Assembler

 AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
IFRAUTA2 1 byte NA Option bits:
00.. ....
HCYLOG - default
10.. ....
HCYLOG - YES
01.. ....
HCYLOG - NO
11.. ....
Reserved
..00 ....
DISPLAY - default
..10 ....
DISPLAY - YES
..01 ....
DISPLAY - NO
..11 ....
Reserved
.... 00..
BEEP - default
.... 10..
BEEP - YES
.... 01..
BEEP - NO
.... 11..
Reserved
.... ..1.
Do not reroute held action messages at
logoff
.... ...1
Command echo
Note: The IFRAUTA2 BEEP flags must be set
when the AIFR is created to BEEP - YES if any
of the MDB beep indicators are on. See the
HDRSNALM field within BUFHDR. After the
AIFR is made, the OVERRIDE flag, IFRAUTA2
flags, force flags, and DEFAULTS flag
determine if the terminal beeps. Because
IFRAUTA1 and IFRAUTA2 are related, see also
the usage notes for IFRAUTA1.
IFRAUTA3 1 byte NA More display flags, as follows:
1... .... IFRAUAOI Indicates whether all or one routing is done as
stated in the NetView automation table. A bit
value of 1 indicates ALL, while a bit value of 0
indicates ONE. This flag is internal to NetView
automation table processing and to the
DSIEX16 interface.

Chapter 7. Control Blocks 127

AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
.1.. .... IFRAUPFU Indicates that a message is full-line mode. This
is similar to title-line processing, except that
messages start at the top of the screen. This bit
is internal to NetView display management.
..1. .... IFRAUPFW Indicates that a message is wide-line mode.
This bit is internal to NetView display
management.
...1 .... IFRAUSSI Indicates that a message was received on the
subsystem interface. This is to allow
independent testing for WQE data from the
indication that a message has been subjected to
system logging through WTO.
Note: IFRAUSSI is also set to indicate that this
is an MVS message with MDB data. See the
IFRAUVEC field.
.... 1... IFRAUWAT Indicates that a message has satisfied a wait in
a command list. (This bit indication replaces
changing HDRMTYPE to HDRTYPWT, which
obscured the HDRMTYPE value.)

DSIEX16 is driven with the message, and upon

return the NetView program frees the buffer
structures if all the display and log action
indicators still say no-display, no-log, and
suppress-override options. The driving of
DSIEX16 for wait-suppressed messages is
intended for accounting purposes, although
resetting the indicators enables logging of
wait-suppressed messages, for example.
.... .1.. IFRAUX16 Indicates that DSIEX16 has been driven and
prevents DSIEX16 from being driven again for
this message. This bit is set to 0 when received
on a cross-domain session to allow processing
in the new domain.
.... ..1. IFRAUVSE Indicates that the message was received in VSE
format (partition ID, reply ID, message ID).
This bit is not reset when received
cross-domain, allowing messages to retain their
format integrity.
.... ...1 IFRAUACN Indicates that the message is an action message.
Note: If IFRAUACN is on, either IFRAUWWR
and CPOMLR (if it exists) is on, or the
IFRAUWDS or CPOCDESC (if it exists)
contains a descriptor code that is one of the
values specified on the
MVSPARM.ActionDescCodes CNMSTYLE
statement.

128 Programming: Assembler

 AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
IFRAUTA4 1 byte NA The first six flags force the actions specified in
the IFRAUTA1 and IFRAUTA2 fields to be in
effect regardless of the OVERRIDE command
options specified for this task. If the bit is 1, the
override is ignored. If the related IFRAUTA1 or
IFRAUTA2 flags are B'00', the action imposed
by the DEFAULTS command or initial setting
applies.

The IFRAUFHD and IFRAUFBP flags, when

specified with nonzero values for the related
IFRAUTA1 or IFRAUTA2 flags, cause the BEEP
or HOLD action to occur regardless of the
initial settings or DEFAULTS command options.
These flags can be set by the NetView program
and are not reset when received cross-domain,
so that DSIEX02A exit, in the new domain, can
get a true picture of the original message.

The NetView program sets the IFRAUFSL and

IFRAUFNL fields, and does so in
multiple-routed copies. When force flags are set
before NetView automation occurs, either by
the NetView program before the DSIEX02A exit
or by the DSIEX02A exit , the automation table
values for that option are ignored. The
IFRAUACT bit must be set on to make the
IFRAUTA1 and IFRAUTA2 actions effective.
1... .... IFRAUFHD Forces HOLD actions.
.1.. .... IFRAUFSL Forces SYSLOG actions.
..1. .... IFRAUFNL Forces NETLOG actions.
...1 .... IFRAUFHL Forces HARDCOPY actions.
.... 1... IFRAUFDS Forces DISPLAY actions.
.... .1.. IFRAUFBP Forces BEEP actions.
.... ...1 IFRAUFLO Displays only the first line of AIFR.
IFRAUTA5 1 byte NA These flags indicate automation settings for
hardware monitor MSUs that are processed by
the automation table. These flags can be
accepted and changed in installation exit
DSIEX16B.
1... .... IFRAUHMH An MSU had one or more matches in the
automation table. The hardware monitor uses
this indicator to put a percent sign (%) in the
column farthest to the right in certain alert
panels. Addressable in the DSIEX16B exit.
.1.. .... IFRAUPES Hardware monitor settings of the ESREC filter
for primary events.
1=PASS
0=BLOCK
Addressable in the DSIEX16B exit.

Chapter 7. Control Blocks 129

AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
..1. .... IFRAUPAR Hardware monitor settings of the AREC filter
for primary events.
1=PASS
0=BLOCK
Addressable in the DSIEX16B exit.
...1 .... IFRAUPOP Hardware monitor settings of the OPER filter
for primary events.
1=PASS
0=BLOCK
Addressable in the DSIEX16B exit.
.... 1... IFRAUPRO Hardware monitor settings of the ROUTE filter
for primary events.
1=PASS
0=BLOCK
Addressable in the DSIEX16B exit.
.... .1.. IFRAUSES Hardware monitor settings of the ESREC filter
for secondary events.
1=PASS
0=BLOCK
Addressable in the DSIEX16B exit.
.... ..1. IFRAUSAR Hardware monitor settings of the AREC filter
for secondary events.
1=PASS
0=BLOCK
Addressable in the DSIEX16B exit.
.... ...1 IFRAUSOP Hardware monitor settings of the OPER filter
for secondary events.
1=PASS
0=BLOCK
Addressable in the DSIEX16B exit.
IFRAUTA6 1 byte NA These flags indicate automation settings for
hardware monitor MSUs that are processed by
the automation table. These flags can be
accepted and changed in installation exit
DSIEX16B.
1... .... IFRAUSRO Hardware monitor settings of the ROUTE filter
for secondary events.
1=PASS
0=BLOCK
.1.. .... IFRAUXLO Hardware monitor settings for the external log
only.
1=YES
0=NO

130 Programming: Assembler

 AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
..1. .... IFRAUCOL The automation table set the color for the MSU.
1=YES
0=NO
...1 .... IFRAUXAT The automation table set the extended
highlighter attributes for the MSU.
1=YES
0=NO
.... 1... IFRAUINT The automation table set the intensity for the
MSU.
1=YES
0=NO
.... .1.. IFRAUBEP The automation table set the beep for the MSU.
1=YES
0=NO
.... ..1. IFRAUVEC Indicates that automation vector extensions
exist. All vectors are chained from the
IFRAUVPT field. The vectors are mapped by
the DSIAIFRO macro.
.... ...1 IFRAUMVI Indicates that presentation vectors exist in the
data buffers chained from IFRAUTBA. These
presentation vectors are included in an
expanded form of the BUFHDR. See the
HDRMDBVI field in BUFHDR.
IFRRIDLN 2 bytes NA The length of the REPLYID from the message
text. The value is 0 under the following
conditions:
1. No REPLYID exists.
2. HDRMTYPE = HDRTYPEY.
IFRAUIRT 4 bytes NA Indicates an important message indicator is
sent to operators listed by the routing buffer
chained to IFRAUIRT. IFRAUIRT must always
be zero when IFRCODAI buffers are sent
cross-domain. The following bytes are found in
the buffer pointed to by IFRAUIRT and are
preceded by a standard 24-byte BUFHDR.
Field(Length)
Description
IFRAUSMI(2)
Status monitor indicator number
IFRAUIRC(1)
Number in the route list
IFRAUIRL(*)(8)
Route list values

Chapter 7. Control Blocks 131

AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
IFRAUCMB 4 bytes NA Points to an internal function request (DSIIFR)
that has an IFRCODE of IFRCODCR unless the
command buffer is received into the current
domain through an NNT task across a
NetView-to-NetView (NNT) session. A
command buffer received by an NNT has a
HDRMTYPE of HDRTYPEX (cross-domain
command) rather than a HDRTYPEI (DSIIFR).
IFRAUPRS 4 bytes NA Built and used only during NetView
automation table processing.
IFRAUSRC 16 bytes NA Provided for 16 bytes of user data. It is set to
zeros when the AIFR is created and is copied
from the original buffer without change.
Note: IFRAUSRC and IFRAUSC2 refer to the
same user field in the message, but return the
value in different forms.
IFRAUSDR 8 bytes NA Used to retain the HDRSENDR value when
sending AIFRs from one domain to another.
IFRAUTAF 8 bytes NA Used to retain the terminal access facility (TAF)
session name when replacing it with the
domain ID in AIFR HDRDOMID.
IFRAURTL 4 bytes NA The address of the route action list used only
during calls to DSIEX16. The routing list is
mapped by IFRAURTB. The IFRAUAOI bit
determines whether the first or all active tasks
in the list specified are sent to the buffer.
IFRAUTBC NA Indicates the MQS receipt of a computed
message.
IFRAUTBN NA Indicates the MQS receipt of an ABEND
message.
IFRAULBR NA The last buffer received.
4 bytes NA The indicator flags are as follows:
IFRAUIN3
IFRAUI3X
IFRAUPTS NNT to OST test priority.

IFRAUPHI and IFRAUPLO indicate the

queuing priority of a command sent from an
NNT task to its associated OST.

If neither bit is on, a default of LOW for a

regular CMD and HIGH for an IMMEDIATE or
BOTH command is used.

If both bits are on, the CMD is processed at the

command priority of the receiving OST task.
See the TEST option of the DSIMQS macro in
PRI for more information.
Note: Test for IFRAUPTS field before testing
the IFRAUPHI or IFRAUPLO bits separately to
avoid errors.

132 Programming: Assembler

 AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description

1... .... IFRAUPHI NNT to OST high-command priority.

.1.. .... IFRAUPLO NNT to OST low-command priority.
00.. ....
IFRAUPHI and IFRAUPLO OFF - Use
default priority
10.. ....
IFRAUPHI ON, IFRAUPLO OFF - Use
HIGH priority
01.. ....
IFRAUPHI OFF, IFRAUPLO ON - Use
LOW priority
11.. ....
IFRAUPHI and IFRAUPLO ON - Use
receiving OST's priority
..1. .... IFRAUPMX Indicates the message was received from VM
PMX using the external form of DSIMQS.
...1 .... IFRAUNVD NetView held message. When IFRAUNVD is
set in a DOM, it is a NetView internal DOM
and other DOM fields are not valid. In
NetView internal DOMs, the combination of
domain ID (HDRDOMID) and message time
value (IFRAUGMT) uniquely identify the
message to be deleted.
.... 1... IFRAUCLR Clear the screen after all queued messages are
sent. IFRAUCLR causes the screen to be cleared
so that the message is at the top of the screen
output area. If IFRAUPSH or IFRAULCK are
on, the screen is locked or held and then
cleared when the lock or held condition is
completed.
.... .1.. IFRAUPSH Lock and hold screen after all pending normal
queued messages are sent. IFRAUPSH causes
the screen to be held after all previous
messages are written. Any buffer queued to
IFRAUTBA is displayed in the area indicated
by IFRAUIMD after the hold is complete.
Supersedes IFRAULCK.
.... ..1. IFRAULCK Lock screen using normal locking rules after all
pending normal queued messages are sent.
Ignored if IFRAUPSH bit is on. IFRAULCK
causes the screen to be locked after all previous
messages are written. Any buffer queued to
IFRAUTBA is displayed in the area indicated
by IFRAUIMD after the lock is complete.
Ignored if the IFRAUPSH bit is on.

Chapter 7. Control Blocks 133

AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
.... ...1 IFRAUIMD Message is written to the immediate message
area after all pending normal messages
reserved for IFRAUIN3. IFRAUIMD indicates
that a message is written to the immediate
message area. If the message was issued using
DSIPSS TYPE=IMMED on an OST, the message
appears immediately. If issued by DSIPSS
TYPE=OUTPUT, the message appears in the
immediate area after all pending queued
messages. A possible use is to display a
message describing a held condition when
using IFRAUPSH.
..1. .... IFRAUNSB Command does not break the message stifle
setting of the OST. IFRAUNSB causes all
command output messages to be suppressed if
the operator is in a non-interruptible display
mode. The output messages are displayed
when the operator switches back to the NCCF
panel.
1.... .... IFRAUDMA Automate the removal of the message. The
message re-drives the automation table when it
is removed from the held queue.
.1.. .... IFRAUDMN A DOM is not expected and the queue element
that waits for the DOM is removed.
00.. .... IFRAUDMA Normal DOM processing with no automation
IFRAUDMN when message is deleted.
..1. .... IFRAUDTO MVS DOM-by-Token.
...1 .... IFRAUDLO NetView LOCAL delete.
IFRAUWQD 88 bytes NA Maps the WQE data that has been processed
into a format independent of levels of z/OS
and JES.
IFRAUWHD 4 bytes NA Eye catcher 'MSG' or 'DOM'.
IFRAUWF1 1 byte NA Flags 1:
.... .1.. IFRAUWWR WTOR.
Note: If you use CPOMLR, set IFRAUWWR to
the same value as CPOMLR. If IFRAUWWR is
on, turn on IFRAUACN.
.... ..1. IFRAUWSP Message suppressed.
.... ...1 IFRAUWBD Broadcast to all.
Note: If you use CPOMLBC, set IFRAUWBD to
the same value as CPOMLBC.
IFRAUWF2 1 byte Flags 2:
1... .... IFRAUWJN Display job names.
Note: If you use CPOMSGTA, set IFRAUWJN
to the same value as CPOMSGTA.
.1.. .... IFRAUWST Display status.
Note: If you use CPOMSGTB, set IFRAUWST
to the same value as CPOMSGTB.

134 Programming: Assembler

 AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
.... .1.. IFRAUWSS Display session.
Note: If you use CPOMSGTF, set IFRAUWSS
to the same value as CPOMSGTF.
IFRAUWF3 1 byte NA Flags 3
IFRAUWF4 1 byte Flags 4:
1... .... IFRAUWDT DOM by ASID and TCB
Note: If you use IFRAUWDT, set IFRAUDFL
and IFRAUDF2 to corresponding meanings.
The bits do not correspond one-for-one.
.1.. .... IFRAUWDA DOM by ASID.
Note: If you use IFRAUWDA, set IFRAUDF2
and IFRAUDFL to corresponding meanings.
The bits do not correspond one-for-one.
IFRAUMCS 2 bytes NA MCS flags.
Notes:
1. Set IFRAUMCS(1) on if any of the following
have nonzero bits:
v CPOCERC or IFRAUWRT
v CPODESC or IFRAUWDS
2. If you use CPOCMCSC, set IFRAUMCS(3)
to the same value as CPOCMCSC.
3. If you use CPOMLBC, set IFRAUMCS(6) to
the same value as CPOCMLBC.
IFRAUNVF 1 byte NA Specific to the NetView program:
Note: These three flags correspond to the three
flags that are defined in the MVS WQE control
block when the NetView program is using the
SSI interface, and correspond to three similar
flags in the MDB when running Extended
Console Mode. The exact meaning and use of
the flags is a property of the operating system.
Refer to operating system documentation for
specific details.
.1.. .... IFRAURET AMRF retained message
..1. .... IFRAURRT Retain in AMRF
...1 .... IFRAUNRT Do not retain in AMRF
1... .... IFRAUNVO NetView-designated.
IFRAUFL5 1 byte Flags 5:
.... ..1. IFRAUPLS Indicates the plus sign (+).
IFRAUWMA 1 byte NA Area ID.

Chapter 7. Control Blocks 135

AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
IFRAUWDS 2 bytes NA Descriptor codes.
Notes:
1. If you use CPOCDESC, set IFRAUWDS to
the same value as CPOCDESC.
2. You must set IFRAUMCS(1) on if any of the
following have nonzero bits:
v CPOCERC or IFRAUWRT
v CPODESC or IFRAUWDS
3. If descriptor code 1, 2, 3, or 11 is on in
IFRAUWDS or CPODESC, set IFRAUACN
on.
4. If you use CPOMLIA, set IFRAUWDS(2) to
the same value as CPOMLIA.
5. If you use CPOMLCE, set IFRAUWDS(3) to
the same value as CPOMLCE.
IFRAUWAS 2 bytes NA ASID of issuer
IFRAUWJT 4 bytes NA JSTCB of issuer
Notes:
1. If you use IFRAUWJT, set IFRAUTCB to the
same value as IFRAUWJT.
2. If you use CPOCTCB, set IFRAUWJT and
IFRAUTCB to the same value.
IFRAUWSN 8 bytes NA System name
Note: If you use GOJGOSNM, set IFRAUWSN
to the same value.
IFRAUWRT 16 bytes NA Route codes
Notes:
1. If you use CPOCERC, set IFRAUWRT to the
same value as CPOCERC.
2. Set IFRAUMCS(1) on if any of the following
have nonzero bits:
v CPOCERC or IFRAUWRT
v CPODESC or IFRAUWDS.
IFRAUWTL 4 bytes NA Used internally by the NetView program
IFRAUWJU 8 bytes NA Job number
Note: If you use CPOCOJID, set IFRAUWJU to
the same value as CPOCOJID.
IFRAUWJA 8 bytes NA Job name
Note: If you use CPOCOJBN, set IFRAUWJA to
the same value as CPOCOJBN.
IFRAUTOK 8 bytes NA MVS message processing facility token.
Note: If you use CPOCAUTO, set IFRAUTOK
to the same value.
IFRAUGMT 8 bytes NA The Coordinated Universal Time store clock
value at the time the AIFR was created. This
value is preserved on all subsequent copies of
the original information, and is preserved on
cross-domain sessions. You can set this field
only once for each AIFR.

136 Programming: Assembler

 AIFR

Table 27. Automation Internal Function Request Fields (continued)

Length or Subfield or
Field Name Mask EQU Description
IFRAUCON 8 bytes NA The EBCDIC name of the console to which an
MVS message was directed, if any.
IFRAUVAS NA Reserved for NetView internal use.
IFRAUVPT NA The next extension locator address.
Notes:
1. The AIFR length is fixed at 256 bytes, including the BUFHDR field and the
HDRMCEXT field. Do not expand it.
2. The length of the IFRRIDLN field is zero when there is not a reply ID or when the
HDRMTYPE field does not have a value of HDRTYPEY.

Automation Internal Function Request Routing List

IFRAURTB is the mapping of the route action list that is used during DSIEX16
processing. IFRAURTL is the address of a standard NetView buffer with a standard
buffer header and a standard buffer header extension. The route list within this
buffer contains a list of names that get identical copies of the IFRCODAI structure.
Bit IFRAUAOI determines whether all active or the first active name receives a
copy of the IFRCODAI. HDRMSG is a field within BUFHDR that is part of the
DSITIB control block macro. This buffer is addressed separately from the
IFRCODAI buffer. HDRBLENG, HDRMLENG, and HDRTDISP are the only fields
that are initialized in this buffer header.

The following are relevant fields:

Table 28. Automation Internal Function Request Routing List Fields
Field Name Length Description
IFRAURCC 2 bytes A halfword count of the number of route names that
follow. The HDRBLENG value must be sufficient to
contain this number of names plus the buffer headers.
IFRAURCL 10 bytes A variable-sized array of 10-character names. These must
contain an operator ID of no more than 8 characters
padded with blanks to a length of 10.

Multiple 10-character fields continue here.

Usage notes:
1. Setting the message action flags in the buffer in DSIEX02A is equivalent to
specifying the options in the NetView automation table. If the message is
selected by the NetView automation table, any options specified by the table
overlay the DSIEX02A values. After DSIEX02A and table processing, the
message is evaluated against criteria specified by DEFAULTS and OVERRIDE
commands to determine display and logging actions. IFRAUACT must be set
to 1 if any ACTIONS are selected by DSIEX02A. When obtaining storage for an
AIFR, separate invocations of DSIGET are used for each buffer chained off the
AIFR. This includes the buffers in the IFRAUTBA chain. For each DSIGET,
specify nonqueued subpool zero storage.
2. In the BUFHDR that precedes the IFR:
a. HDRMTYPE is specified as I (HDRMTYPE=X'C9'; symbol HDRTYPEI).

Chapter 7. Control Blocks 137

AIFR

b. For a DSIIFR received on a task message queue, HDRTDISP contains the

displacement to the IFRCODE. For IFRCODCR and IFRCODUS, the
NetView program modifies HDRTDISP and HDRMLENG so that all
commands appear the same to the command processor. The command verb
is followed by the parameters. The IFR section is logically removed.

DSILOGDS: NetView Log

The NetView log maps the record written to the network log. Table 29 shows the
fields in the DSILOGDS:
Table 29. NetView Log Fields
Field Name Length Description
LOGDATE 4 Date of record; format is 0CyydddC, where yy is the year,
ddd is the day, and C defines the field as packed decimal.
LOGDISP 2 Record text displacement.
LOGDOMID 8 Domain ID of record originator.
LOGKEYDT 4 Same as LOGDATE.
LOGKEYTM 4 Time of record; format is hhmmss0c, where hh is the hour,
mm is the minute, ss is the second, and 0C defines this field
as packed decimal.
LOGLUNAM 8 Task name of record originator.
LOGMTYPE 1 Message type of record.
LOGOPID 8 Operator ID of record originator.
LOGSEQ# 4 Sequence number for VSAM key.
LOGTEXT Text of network log record.
LOGTIME 4 Same as LOGKEYTM.

DSIMVT: Main Vector Table

The main vector table (DSIMVT) is the main control block for information
throughout NetView. It contains global information, such as the domain name, the
status of NetView, and pointers to other tables and subtasks.

Each NetView program has one MVT. You can locate the MVT from a subtask
through the TVBMVT, a pointer in the task vector block (DSITVB).

The following are relevant fields in the MVT:

Table 30. Main Vector Table
Field Name Length Description
MVTART 2 In prior releases, a pointer to DSIART. The contents of this
field are set to zero. This symbolic name has been
removed from DSIMVT, and the field usage changed to
reserved to preserve other field offsets in the MVT.
MVTARTLN 2 In prior releases, the length of each entry in DSIART. The
contents of this field are set to zero. This symbolic name
has been removed from DSIMVT, and the field usage
changed to reserved to preserve other field offsets in the
MVT.
MVTCBH 4 A standard control block header.

138 Programming: Assembler

 DSIMVT

Table 30. Main Vector Table (continued)

Field Name Length Description
MVTCDSES 2 Obsolete.
MVTCLOSE 1 A flag bit indicating the CLOSE command has been
issued. The state of the bit can be checked with the
NVCLOSE automation table condition item.
MVTCURAP 9 The name of the NetView domain as defined by the
started procedure or the CNMSTYLE member, as follows:
MVTCURAL
1-byte field that shows the length of the domain
name (1–5 characters).
MVTCURAN
8-byte field that contains the domain name
padded with blanks.
MVTDRTRY 2 The number of times an I/O operation is retried before it
becomes a permanent error.
MVTGFMG1 4 A pointer to a write-to-operator parameter list containing
the message DSI124I STORAGE REQUEST FAILED FOR NCCF.
This message can be used by any WTO macro with MF=E.
No additional storage is required. The routing code is
(2,11); the descriptor code is 11.
MVTGFMG2 4 A pointer to a write-to-operator parameter list containing
the message DSI125I CRITICAL STORAGE SHORTAGE FOR
NCCF. This message can be used by any WTO macro with
MF=E. No additional storage is required. The routing code
is (2,11); the descriptor code is 11.
MVTGMSG 4 Pointer to a buffer containing the message DSI073A
COMMAND PROCESSOR UNABLE TO BUILD RESPONSE MESSAGE.
MVTMETH 1 Indicates that the access method is VTAM (V).
MVTMLGON 2 The number of times incorrect logon information is
processed before that terminal session ends. This number
is specified in the MAXLOGON definition statement.
MVTMRC 2 The number of times an OST or PPT can abend before it
terminates. This number is specified in the MAXABEND
definition statement. The MAXABEND count for a task is
reset to 0 if the task runs for at least one hour after the last
abend.
MVTNAUNM 8 The correct origin LU name (either VTAM CP name or
NetView LU name) while the DSI6DST task is active. If
DSI6DST is not active, this field is blank. This field is
useful for building complete MDS-MUs.
MVTNCCFQ 8 The QNAME value for macros ENQ and DEQ.
MVTNETID 8 The name of the network ID.
MVTOIT 4 In prior releases, a pointer to DSIOIT. The contents of this
field are set to zero. This symbolic name has been
removed from DSIMVT, and the field usage changed to
reserved to preserve other field offsets in the MVT.

Chapter 7. Control Blocks 139

DSIMVT

Table 30. Main Vector Table (continued)

Field Name Length Description
MVTPRDSF 16 Three common designed product-unique subfields that are
used to communicate information to other products. For
example, this release of NetView stores
005697B82NETVIEW in this field.
MVTMODNU
2 character field that contains the common
modification identifier. The MVTMODNU
subfield used with MVTVER subfield also
identifies the version and release.
MVTPRNUM
Seven-character field that contains the licensed
program number.
MVTPRNAM
Seven-character field that contains the software
product common name.
MVTRCNT 4 The total number of unique, specific, and wildcard
resource names defined in the span of control table. This
count does not include view names defined in the
NetView span table.
MVTSCNT 2 The total number of span names defined for span of
control. This count does not include span names defined
in the NetView span table that contain only view
identifiers.
MVTSNT 4 In prior releases, a pointer to DSISNT. The contents of this
field are set to zero. This symbolic name has been
removed from DSIMVT, and the field usage changed to
reserved to preserve other field offsets in the MVT.
MVTSNTLN 2 In prior releases, the length of each entry in DSISNT. The
contents of this field are set to zero. This symbolic name
has been removed from DSIMVT, and the field usage
changed to reserved to preserve other field offsets in the
MVT.
MVTSPANA 1 In prior releases, a flag bit indicating that the
authorization and routing table (DSIART) resides above
the 16Mb line. The contents of this field are set to zero.
This symbolic name has been removed from DSIMVT, and
the field usage changed to reserved to preserve other field
offsets in the MVT.
MVTSVL 4 The address of the service routine vector list (SVL) that
contains the addresses of the service routines.
MVTSYMBM 4 The address of the MVS ASASYMBM service routine that
performs substitution for MVS symbols. This field contains
the address of the NetView service routine or zeros if
NetView symbolic substitution is disabled. Refer to the
MVS library for information on how to call the
ASASYMBM service routine.
MVTSYMBT 4 The address of the NetView logical extension to the
system-provided symbol table mapped by ASASYMBT.
MVTTOD 8 The system time-of-day clock when the NetView program
was started.
MVTTVB 4 The address of the first TVB in the TVB chain.

140 Programming: Assembler

 DSIMVT

Table 30. Main Vector Table (continued)

Field Name Length Description
MVTTVBRN 18 The RNAME value for the TVB chain.
MVTUFLD 4 A user-defined field.

For a description of user-defined fields, see Chapter 7,

“Control Blocks,” on page 103.
MVTVER 4 Contains an identifier that can be displayed for the
NetView release under which your code is running.

MVTAIDFT–DSIEX16 Interface Data:

For field name MVTAIDFT, the following defaults are set in DSIMVT and relate to
DSIEX16:
Table 31. DSIMVT Defaults that Relate to DSIEX16
Length or
Mask Start-up Value Description
1 byte
1... .... 1
1 = Messages can be held on the screen.
0 = Messages cannot be held on the screen.
.x.. .... Reserved.
..0. .... 0
0 = Messages other than NetView WTO and WTOR are
not written to the system log.

1 = NetView messages are written to the system log.

...1 .... 1
1 = Messages are written to the NetView log if the
NetView log is active.

0 = Messages are not written to the NetView log.

.... 1... 1
1 = Messages can be written to the hardcopy log if one is
started for the operator.

0 = Messages are not written to the hardcopy log.

.... .1.. 1
1 = Messages can be displayed on the NetView operator's
station.

0 = Messages cannot be displayed on the NetView

operator's station.
.... ..1. 1
1 = Messages can beep on the NetView operator's station.

0 = Messages cannot beep on the operator's station.

.... ...x Reserved.

Chapter 7. Control Blocks 141

DSIMVT

Table 31. DSIMVT Defaults that Relate to DSIEX16 (continued)

Length or
Mask Start-up Value Description
Usage notes:
1. DISPLAY, BEEP, HOLD, and HCYLOG actions are the same in each IFRCODAI
structure on the chain pointed to by the original AIFR's HDRNEXTM field. However,
the original AIFR can be different from those on the chain.
2. You can change the settings using the DEFAULTS command.
3. The interpretation of the results of the settings is affected by the settings of AIFR flags
for a message and by the OVERRIDE command settings currently in effect for each
operator.
4. Some messages are not affected by these settings.

DSIPDB: Parse Descriptor Block

The parse descriptor block (DSIPDB) contains parse information for a command. It
is pointed to by CWBPDB in the CWB or by USERPDB in the USE. The PDB has
no fixed length. The following are fields in DSIPDB:
Table 32. Parse Descriptor Block Fields
Field Name Length Description
PDBCBH 4 Standard control block header.
PDBBUFA 4 The address of the command buffer. CWBBUF also
contains this address.
PDBCMDA 4 A pointer to the entry in the system command table (SCT)
for the verb in the buffer that caused this command
processor to be called. Macro DSIPAS (parameter alias
services) and DSIKVS (keyword and value security
services) use this entry as a parameter.
PDBFLAGS 1 Indicator byte for command processors.
PDBIMMED
1 runs as an immediate command. 0 runs as a
regular command or a data services command.
PDBNOENT 2 The number of syntactical element entries in the PDB,
including the verb and all parameters.
PDBTABLE 0 Label to indicate the beginning of PDB entries.

142 Programming: Assembler

 DSIPDB

Table 32. Parse Descriptor Block Fields (continued)

Field Name Length Description
PDBENTRY 4 Each syntactical element creates one entry in this portion
of the PDB. The verb is always the first entry. Each entry
contains the length, the delimiter, and the offset from the
beginning of the buffer, as specified in the following three
fields:
Field Name
Description
PDBDISP
A 2-byte field specifying the offset from the start
of the buffer to the first character of the nth
syntactical element. For example, element addr(n)
= PDBBUFA + PDBDISP(n).
PDBLENG
A 1-byte field specifying the length of the
particular syntactical element. This field does not
include the length of the delimiter. When two
delimiters other than blanks occur sequentially,
the length is 0. Also, when two delimiters are
separated by a blank or blanks, the length is 0.
The offset is set to point to the second delimiter.
PDBTYPE
A 1-byte field specifying the delimiter character
that separates this element from the next one. The
standard parsing delimiters are blank, comma,
period, and equal sign. The end of the record is
treated as if it were delimited by a blank.
Multiple blanks are treated as 1 blank. Blanks
preceding a syntactical element are ignored.
For example,
verb parameter1,parameter2
creates the following:
1. An entry for the verb (preceding blanks are
ignored)
2. An entry for parameter1, delimited by a
comma
3. An entry for parameter2, delimited by a blank.
PDBENTND
A label at the end of PDBENTRY for use in
computing the length of PDBENTRY.

DSISCE: System Command Entry

The system command entry (DSISCE) contains information about a command.
Macro DSICES returns the SCE of a verb or command processor. The address of
the SCE is also input to macro DSIPAS.

Table 33 on page 144 shows the fields in the DSISCE:

Chapter 7. Control Blocks 143

DSISCE

Table 33. System Command Entry Fields

Field Name Length Description
SCECADDR 4 This is the address of the linkage assist routine for
command processors, DSICMDLD.
SCELNAME 8 The load module or phase name of the command
processor to be called for the verb.
SCERCADR 4 The address of the command processor's entry point.
SCEVERB 8 The command verb, left-aligned and padded with blanks.

DSISCT: System Command Table

The system command table (DSISCT) contains a system command entry (DSISCE)
for each command defined to the NetView program in the CMDDEF definition
statement. The table contains no user fields. However, you must include this
control block to obtain a dummy control section (DSECT) of the SCE.

DSISVL: Service Routine Vector List

NetView macros use the service routine vector list (DSISVL) to call the requested
service routine. For example, if you run a program that issues DSIPSS, DSISVL is
the means by which DSIPS1 (NetView presentation services main service routine)
is found.

The SVL contains the addresses of many service routines. The SVL has no user
fields. However, include this control block to use NetView services.

DSISWB: Service Work Block

The service work block (DSISWB) contains the parameter list for most service
facilities used in user-written code.

The following are fields in DSISWB:

Table 34. Service Work Block Fields
Field Name Length Description
SWBADATD 256 The automatic work area to be used for reentrant variable
definition.
SWBLRCPL * An area where the caller builds parameter lists for
DSIPUSH, DSIPOP, and DSIFIND.
SWBPLIST 256 The parameter list area.
SWBSAVEA 72 A standard save area.
SWBTIB 4 The pointer to the caller's TIB.
MQSENTTO 8 The operator ID of the operator to whom the message was
sent. Returns to the issuer if DSIMQS is issued with a
LIST of type 1ST.

For a description of SWBLRCPL, see “DSIPUSH: Establish Long-Running

Command” on page 223, “DSIPOP: Remove Long-Running Command” on page
211, and “DSIFIND: Find Long-Running Command Storage” on page 170.

144 Programming: Assembler

 DSITECBR

DSITECBR: Branch Table of ECB Processor Load Modules

The branch table of the ECB processor load modules (DSITECBR) control block
contains the addresses of load modules that are ECB processors for a DST. When a
private or dynamic ECB is posted in a DST task list, the ECB processor in the DST
branch table is called by DSITECBR.

DSITECBR also contains the environment area that is pushed down with the
DSITECBS macro and returned when the ECB is posted.

Table 35 shows the fields in the DSITECBR:

Table 35. Branch Table of ECB Processor Load Modules Control Block Fields
Field Name Length Description
TECBPRMS 8 The returned label that maps the start of the parameter list
pointed to by the CWBPECB field in the DSICWB control
block. See “DSICWB: Command Work Block” on page 116
for more information.
TECBPTR 4 The posted ECB address.
TECBENV 4 The user's environment that was pushed with the
DSITECBS macro.

DSITIB: Task Information Block

The task information block (DSITIB) keeps information about an attached subtask.
The TIB is acquired and freed by the main task.

The following DSITIB fields apply to all NetView tasks. These fields are read-only
unless otherwise specified. Fields that are useful when writing optional subtasks
are noted. Do not modify these fields unless you are writing an optional task.
Table 36. Task Information Block Fields
Field Name Length Description
TIBCBH 4 A standard control block header. The CBHTYPE field
contains the same information as the CBHTYPE field in
the TVB.
TIBACB 4 A pointer to a VTAM ACB for NetView subtasks. This
field can be modified by a user-written optional task.
TIBAPID 9 The VTAM application program name for a NetView
subtask. This field can be modified by a user-written
optional task.
TIBAPWD 9 The VTAM password for NetView subtasks. This field can
be modified by a user-written optional task.
TIBAREA1 62 Pointers to other control blocks such as CWB, SWB, or
PDB for NetView subtasks. This field can be modified by a
user-written optional task.
TIBBITS 1 3270 address mode support flags:
TIB12BIT = 1 means 12-bit addresses are valid.
TIB14BIT = 1 means 14-bit addresses are valid.
TIB16BIT = 1 means 16-bit addresses are valid.
Note: More than one bit can be on at the same time to
indicate the allowed modes.

Chapter 7. Control Blocks 145

DSITIB

Table 36. Task Information Block Fields (continued)

Field Name Length Description
TIBCLRDF 1 Default color:
X'00' Color field not found
X'F4' Green
X'FA' Orange
TIBCLR# 1 Number of colors supported.
TIBEDATD 256 Reserved for the NetView program in NetView tasks. This
area can be used for reentrant storage in a user-written
task.
TIBECBPO 1 A constant to test whether an ECB has been posted.
TIBELT 4 Read-only for applications in NetView tasks. A pointer to
the subtask ECB list. This field can be modified by a
user-written optional task.
TIBEXLST 4 Read-only for applications in NetView tasks. A pointer to
the subtask VTAM EXLST. This field can be modified by a
user-written optional task.
TIBFLGS 1 TIBLRCNP is superseded by the TIBSCRID field.
TIBHLITE 1 Highlight support flags.
TIBBGCOL = 1 means background color is supported.
TIBBLINK = 1 means flashing is supported.
TIBREVRS = 1 means reverse video is supported.
TIBREPEX = 1 means extended field mode is
supported.
TIBUNSCR = 1 means underscore is supported.
TIBMSGNM 8 The operator identifier of the subtask that issued the
START TASK command. If the subtask was started
automatically with INIT=Y, this field contains zeros.
TIBMUXIT 1 A counter used to track the level of multiple asynchronous
interrupts.
TIBNDATD 256 Reserved for the NetView program in NetView tasks. This
area can be used for reentrant storage in a user-written
task.
TIBOSEXT 4 Reserved for the NetView program in NetView tasks. A
pointer to an optional subtask extension to the TIB. The
optional subtask releases any storage pointed to by this
area at task end.
TIBOSLST 4 Reserved for the NetView program in NetView tasks. This
field can be modified by a user-written optional task, but
must be either zero or contain the address of a
user-NetView buffer. The data is displayed by the NetView
LIST taskname command in addition to the normal LIST
command data.
TIBPROFL 8 The profile name for the operator that logged on to this
task. The first byte of this field contains binary zero or a
blank if the NetView security options that are specified in
the CNMSTYLE member indicate that no profile is used.
For example, if the SECOPTS.OPERSEC statement is set to
SAFDEF or MINIMAL, NetView operator profiles are not
used.

146 Programming: Assembler

 DSITIB

Table 36. Task Information Block Fields (continued)

Field Name Length Description
TIBQUERY 4 The address of a Query Reply 3270 data stream, which
was read by the NetView program if the logmode
indicated that Query was supported. The data starts with
an AID byte of X'88', and is followed by Query Reply
structured fields as described in the Data Stream library.
TIBSAVEE 72 A save area for subtask use. This field is reserved for the
NetView program in NetView tasks. This field can be
modified by a user-written optional task.
TIBSAVES 72 A save area for subtask use. This field is reserved for the
NetView program in NetView tasks. This field can be
modified by a user-written optional task.
TIBSCRID 4 Screen identifier:
TIBSCRM
1-byte screen modification type.
TIBSCRSN
3-byte screen serialization number.
TIBTVB 4 A pointer to the TVB. The address of the MVT can be
obtained from the TVB. MVT locates all other control
blocks.
TIBUFLD 4 This field is not referenced or changed by the NetView
program. This field can be defined by the subtask.

For a description of user-defined fields, see Chapter 7,

“Control Blocks,” on page 103.
TIBXECB 4 The NetView program uses this field as an ECB for
cross-domain communication in OST and NNT. This field
is reserved for the NetView program in NetView tasks.
This field can be modified by a user-written optional task.

DSITVB: Task Vector Block

The task vector block (DSITVB) contains information about the status of the
subtask. Each subtask in NetView has one TVB. Certain service routines, such as
DSIPSS, use the TVB to store control information that is important for processing
their code.

The TVB contains pointers to the MVT and the TIB. You can obtain the addresses
of other important control blocks from these control blocks. The TIB, an extension
of the TVB, represents an active task. TVBs are chained together through the
TVBNEXT field. MVTTVB points to the beginning of the chain.

Table 37 on page 148 shows the relevant fields in the DSITVB.

Chapter 7. Control Blocks 147

DSITVB

Table 37. Task Vector Block Fields

Field Name Length Description
TVBCBH 4 A standard control block header. The CBHTYPE byte
indicates the subtask type:
X'00' PPT
X'01' NNT
X'02' OST
X'03' HCT
X'05' Optional subtask

To distinguish the different types of optional subtasks,

refer to the field TVBMODNM.
TVBMECB 4 An event control block (ECB) that notifies the subtask that
a message or a queue of messages has been sent using
macro DSIMQS.
TVBMECBH 4 An ECB that notifies the subtask that a high-priority
message or queue of messages has been queued to the
high-priority public message queue (TVBMPUBH).
TVBMECBL 4 An ECB that notifies the subtask that a low-priority
message or queue of messages has been queued to the
low-priority public message queue (TVBMPUBL).
TVBMPRIQ 4 The address of the normal-priority private message queue.
TVBMPRQH 4 The address of the high-priority private message queue.
TVBMPRQL 4 The address of the low-priority private message queue.
TVBMPUBH 4 The address of the high-priority public message queue.
See “Intertask Communication” on page 83 for information
on processing public and private message queues.
TVBMPUBL 4 The address of the low-priority public message queue. See
“Intertask Communication” on page 83 for information on
processing public and private message queues.
TVBMPUBQ 4 The address of the normal-priority public message queue.
See “Intertask Communication” on page 83 for information
on processing public and private message queues.
TVBMVT 4 A pointer to the MVT.
TVBNEXT 4 A pointer to the next TVB on the TVB chain. The TVB
chain is anchored from MVTTVB.
TVBPRIQ 1 Priority queuing flags:
TVBMM = 1
The subtask provides services for the
high-priority and low-priority message queues as
well as the normal queue.
TVBRESTE 4 An ECB that notifies the subtask that RESET command
has been entered.
TVBTCB 4 The MVS task control block (TCB) address.
TVBTECB 4 An ECB that requests that the subtask shut down as soon
as possible. Include TVBECB in every subtask ECB list. A
subtask can use this ECB to shut down.
TVBTIB 4 A pointer to the TIB for the subtask.

148 Programming: Assembler

 DSITVB

The subtask uses the following bit fields. Some of these flag bits are defined by the
subtask; others are defined by the main task.
Table 38. Task Vector Block Subtask Fields
Field Name Length Description
TVBAIIFR 4 Address of AIFR buffer structure when a command is
driven from the NetView automation table, the MS
transport, or the NetView high-performance transport.
Otherwise, the address is zero (0).
TVBHCUSE 4 Can be defined by the subtask. For an HCT, this field
tracks the number of subtasks currently using the
hardcopy subtask.
TVBIND1 1 Indicator byte:
TVBTERM
A value of 1 indicates that the subtask has ended
normally, and the subtask has released all
resources. This bit must be supported by the
subtask. If the bit is set on by the main task
before attaching the subtask, a value of 1
indicates to the subtask that it has been attached
for cleanup. The subtask is to release all resources
and return control to the main task with this bit
still set to 1.
TVBIND2 1 Indicator byte:
TVBVCLOS
This flag bit can be defined by the subtask.
TVBABLOG
A 1 indicates a task is being re-initialized just
after an abend.
TVBIND3 1 Indicator byte:
TVBACTV = 1
The subtask is active. This bit is set by the
subtask. While this bit is on, messages can be sent
to the subtask using macro DSIMQS.
TVBINXIT = 1
An IRB exit routine is running.
TVBLGOFF = 1
The subtask is ending upon request.
TVBLGON = 1
The subtask is starting.
TVBRCVAI
Can be defined by the subtask. For an OST or an
NNT, TVBRCVAI = 1 means a RECEIVE ANY for
cross-domain sessions has been issued.
TVBRESET = 1
Regular commands stop processing immediately.
If your subtask does not run command
processors, you can redefine this flag.
TVBIND4 1 Indicator byte:
TVBRCVRY = 1
Recovery is in progress for this subtask.

Chapter 7. Control Blocks 149

DSITVB

Table 38. Task Vector Block Subtask Fields (continued)

Field Name Length Description
TVBLUNAM 8 The name of the task that is specified by the TASK
statement in the CNMSTYLE member. This field is
initialized before the subtask is attached.
TVBMEMNM 8 This field is initialized with the MEM parameter of the
TASK definition statement in the CNMSTYLE member. It
is the name of the member in the DSIPARM data set that
contains the initialization parameters for an optional
subtask.
TVBMODNM 8 The name of the module to be attached as a subtask as
specified in the MOD parameter of the TASK definition
statement. This field can be used to determine the type of
optional subtask.
TVBOPID 8 The unique subtask identifier. This name can be the same
as TVBLUNAM. TVOPID is set up by the subtask when
initialization is complete.
TVBQCNT 4 If TVB374CT is on, the total number of buffers on the
public message queues are stored in this counter. If
TVBQCNT reaches the threshold value, message DSI374A
is issued. Threshold values for the public message queues
are described in the IBM Tivoli NetView for z/OS
Administration Reference.
TVBUFLD 4 A user field that can be defined by the subtask.

For a description of user-defined fields, see Chapter 7,

“Control Blocks,” on page 103.
TVBZIND1 1 Indicator byte:
TVBZPUP
Primary VSAM data set in use
TVBZSUP
Secondary VSAM data set in use
TVBZIND2 1 Indicator byte:
TVBABEND
The ABEND reinstate routine is running. If this
indicator is on, macros DSIPUSH and DSIPOP
cannot be issued.
TVBLOGOF
The LOGOFF routine is running. If this indicator
is on, DSIPUSH and DSIPOP cannot be issued.
TVBRESUM
The RESUME routine is running.
TVBZIND3 1 Indicator byte:
TVB374CT
The total number of buffers on the public
message queues are stored in TVBQCNT if this
bit is on.

150 Programming: Assembler

 DSITVB

Table 38. Task Vector Block Subtask Fields (continued)

Field Name Length Description
TVBZIND4 1 Indicator byte:
TVBAUTOO
User code is running under an unattended
operator task.
TVBAUTVE
The task depends on VTAM and must be
terminated by the main task when VTAM ends.
TVBAUTVS
The task depends on VTAM and must be
reattached by the main task when VTAM starts.
When VTAM ends, the task terminates.

DSIUSE: Installation Exit Parameter List

The installation exit parameter list (DSIUSE) contains addresses for the following:
v Buffer containing the message or MSU
v LU name associated with the message or MSU
v Operator identification
v Service work block (DSISWB)
v Task vector block (DSITVB)
v Parse descriptor block (DSIPDB)

An extension of USE is present for DSIEX12 and the DST exit routines involved
with input and output (XITCO, XITCI, XITVN, XITVI, XITVO, and XITXL). For
DSIEX12, the password, hardcopy printer name, and profile name are given. For
the DST exit routines, the address of the DSRB is given.

Table 39 shows the fields in DSIUSE.

Table 39. DSIUSE Field Names and Descriptions
Field Name Length Description
USERCBH 4 A standard control block header. The second byte,
USERCODE, indicates the exit routine that is called.
Values X'01'–X'15' correspond to installation exits
DSIEX01–DSIEX19. The DST installation exit codes are
defined in the USE control block.

Chapter 7. Control Blocks 151

DSIUSE

Table 39. DSIUSE Field Names and Descriptions (continued)

Field Name Length Description
USERLGON 36 An extension for DSIEX12 and the DST exit routines. If
present, this extension contains the following fields:
Field(Length)
Description
field(4)
USEDSRB
For DST exit routines, the fields XITVI,
XITVO, XITCI, XITCO, and XITXL point
to the DSRB associated with the DST
I/O request.
USETOTVB
For DSIEX12 only.
For other exit routines, this field is not initialized.
USENPSWD(8)
For DSIEX12 only. This field contains the new
password successfully entered by the operator at
logon when OPERSEC (in CNMSTYLE or its
included members) is specified as SAFPW,
SAFCHECK, or SAFDEF. If OPERSEC=MINIMAL
or if OPERSEC=NETVPW is specified,
USENPSWD contains blanks (X'40'). For exit
routines other than DSIEX12, this field is not
initialized.
USERHCPY(8)
For DSIEX12 only. This field contains the name of
the hardcopy printer used by the operator for this
session. If no hardcopy printer is used or if the
SECOPTS.OPERSEC statement in the CNMSTYLE
member specifies MINIMAL, the USERHCPY
field contains blanks (X'40'). For exit routines
other than DSIEX12, this field is not initialized.
USERPROF(8)
For DSIEX12 only. This field contains the name of
the profile used for this session. If the
SECOPTS.OPERSEC statement in the CNMSTYLE
member specifies MINIMAL or SAFDEF, the
USERPROF field contains blanks (X'40'). For exit
routines other than DSIEX12, this field is not
initialized.
USERPSWD(8)
For DSIEX12 only. This field contains the operator
password entered at logon. If the OPERSEC
statement is specified as MINIMAL in the
CNMSTYLE member, the USERPSWB field
contains blanks (X'40'). For exit routines other
than DSIEX12, this field is not initialized.

152 Programming: Assembler

 DSIUSE

Table 39. DSIUSE Field Names and Descriptions (continued)

Field Name Length Description
USERLU 4 A pointer to an 8-byte area that contains the logical unit
name (LUNAME) related to the subtask in control, as
follows:
Task Name
MNT The characters SYSOP
OST The LU name of the operator's terminal
NNT The APPL name of the OST that issued the
START DOMAIN command (the domain name
followed by a 3-digit number)
PPT The domain name parameter followed by the
characters PPT
HCT The LU name of the hardcopy printer
DST The name of the task specified by the TASK
statement in the CNMSTYLE member.
USERMSG 4 A pointer to a buffer in standard buffer format, consisting
of a buffer header (BUFHDR) followed by text. For
input-type exits, device dependencies have been removed.
In exit routines DSIEX14, XITDI for end-of-file, and
XITVN, this field is set to 0.

In DSIEX04, the buffer is in the format set up by the caller.

It has not yet been reformatted for the network log,
system log, or hardcopy log.
USEROPID 4 A pointer to an 8-byte area that contains a name related to
the subtask in control, as follows:
Task Name
MNT The characters SYSOP
OST The operator identifier
NNT The operator identifier
PPT The NCCFID DOMAINID parameter followed by
the characters PPT
HCT The LU name of the hardcopy printer
USERPDB 4 A field that points to a PDB or contains 0. The PDB
contains parse data that relates to the buffer to which
USERMSG points. For exit routines DSIEX02A, DSIEX04,
DSIEX07, DSIEX09, DSIEX10, DSIEX14, DSIEX16,
DSIEX16B, DSIEX17, DSIEX19, XITXL, and XITDI for
end-of-file, this field contains 0. A PDB is not available
when calling these exit routines.
USERSWB 4 A pointer to the SWB, which the exit routine uses as a
work area or to request services from the NetView
program. If necessary, another SWB can be obtained using
macro DSILCS.
USERTVB 4 A pointer to the TVB. The TVB contains information about
the subtask under which the exit routine was called. The
TVB obtains the addresses of the TIB, the MVT, and the
SVL (through the MVT).

Chapter 7. Control Blocks 153

DSIXRCMD

DSIXRCMD: RUNCMD Installation Exit Buffer

The RUNCMD installation exit buffer (DSIXRCMD) provides a mapping of the
command buffer that is passed to the RUNCMD installation exit DSIEX19 as
USERMSG.

The following fields are in DSIXRCMD:

Table 40. DSIXRCMD Field Descriptions
Field Name Length Description
RCMDUSER 8 User ID which is the source of the RUNCMD.
* 8 A reserved 8-byte field.
RCMDUTOK 80 Security product token for the source issuer of RUNCMD,
if available.
RCMDSPNM 8 The service point name entered on the RUNCMD.
RCMDAPPL 8 The service point application entered on the RUNCMD.
RCMDNTID 8 The NETID entered with the RUNCMD installation exit.
RCMDCLEN 2 Length of the service point command string.
RCMDCSTR The service point command string. The length of the string
varies, depending on the individual command string.

154 Programming: Assembler

Chapter 8. Macros
This chapter describes the purpose and coding of the NetView program macros.
You can use these macros to request various service facilities when writing your
own installation exit routines, command processors, and subtasks. You must be
running in problem program state and in user protection key to use these macros.
Appendix D, “Assembler Macros and HLL Service Routine Interfaces,” on page 293
lists the corresponding PL/I command for each of these macros.

NetView macros overwrite registers 0, 1, 14, and 15. Before issuing any macro,
except DSICBS, set register 13 to a standard 72-byte save area.

All return codes in this chapter are shown in decimal format.

Use only the operands documented in this book. Any undocumented operands
that a macro has are only for internal use by the NetView program and cannot be
used in user-written programs.

DSIAUTO: Invoke Automation Services

The DSIAUTO macro provides a way for a program running within the NetView
address space to pass a management services unit (MSU) directly to the active
automation table.

If there is an active automation table, the automation table statements are scanned
for appropriate matches with the MSU passed by DSIAUTO. Any actions specified
on matching automation statements are taken.

The PL/I and C equivalent to DSIAUTO is CNMAUTOTAB/CNMAUTO.

DSIAUTO issues a return code that indicates the result of the automation table
scan.

The following format for the DSIAUTO macro is as follows:

DSIAUTO

►► DSIAUTO DATA = atdata ►

label ( register )

► , SWB = swb ►◄
( register )

Where:
DATA
Specifies the register containing the address or the symbolic name of the data
item, which must be one of the following forms:
v A multiple-domain support message unit (MDS-MU)
v A control point management services unit (CP-MSU)
v A network management vector transport (NMVT)
This is a required operand.

© Copyright IBM Corp. 1997, 2015 155

DSIAUTO

SWB
Specifies either a register or the symbolic name of a fullword area containing
the address of a service work block (DSISWB).
This is a required operand.

Return Codes in Register 15

The following return codes are for the DSIAUTO macro:
0 One or more matches were found and the MSU was automated.
4 A match was not found and the MSU was not automated.
8 NetView automation inactive. There is no active automation table.
12 Storage failure.
16 Incorrect data item. The MSU was not recognized as one of the previously
described types.
20 No entries match this type. The automation table has no MSU-oriented
statements.
40 NetView internal failure.
100 Automated but rerouted. One or more matches were found and the MSU
was automated. The automation action was rerouted to an OST for
processing.
200 Automated and reroute failed. One or more matches were found and the
MSU was automated. The automation action was rerouted to an OST, but
the OST was not active.

The address for the NMVT must have a 2-byte length field preceding the X'41038D'
header. This length is similar to the 2-byte length field defined as the beginning of
an MDS-MU or CP-MSU. However, the NMVT length field reflects the length
starting at the X'41038D' header to the end of the NMVT. The length in MDS-MUs
or CP-MSUs reflects the length of the MSU starting at the length field. The
difference is that an NMVT length field does not include the length of the length
field itself.

For more information about the formats of architected vectors, refer to the SNA
library.

DSIBAM: Build Automation Message

The DSIBAM macro specifies the keyword=data tokens included in the alert
automation message generated by CNMS4284.

The DSIBAM macro can be issued ONLY from CNMS4284.

The following format is the syntax for the DSIBAM macro:

DSIBAM

156 Programming: Assembler

 DSIBAM

, CONTROL = N
►► DSIBAM DOMID = N ►
label Y , CONTROL = N
END Y
HIER = N
Y
MSGID = symbol
Subvector

, DATALIN = Y
► ►◄
, DATALIN = N
Y

Subvector:

SVID = symbol ►
, SVOCCUR = symbol

, XLATE = N
►
, SFID = symbol , XLATE = N
, SFOCCUR = symbol Y

Where:
CONTROL
Specifies whether add the keyword=data token to the control line of the alert
automation message.
N Do not put the keyword=data token on the control line. This is the default.
Y Put the keyword=data token on the control line.
DATALIN
Specifies whether to add the keyword=data token to a data line of the alert
automation message.
N Do not put the keyword=data token on a data line.
Y Put the keyword=data token on a data line. This is the default.
DOMID
Specifies whether to evaluate the domain ID in the major vector. You must
specify DOMID only once.
N Do not build DOMID=data token.
Y Build DOMID=data token.
END
Causes the table to end. You must specify END only once, and it must be the
last occurrence of DSIBAM.
HIER
Specifies whether to evaluate the hierarchy in the major vector. The data
portion of the HIER keyword=data token is formatted as a list of up to five
8-character resource names/resource type pairs (NAME1, TYP1, NAME2,
TYP2, ...). You must specify HIER only once.
N Do not build HIER=data token.

Chapter 8. Macros 157

DSIBAM

Y Build HIER=data token.

MSGID
Specifies the unique 8-character message ID for the alert automation message.
You must specify MSGID only once.
SFID
Specifies a 1-byte (2 alphanumeric characters) subfield ID. This subfield occurs
within the subvector specified by the SVID. A keyword=data token is built for
this subfield and added to the alert automation message.
SFOCCUR
Specifies the occurrence of the SFID to be found. This is a 1- or 2-character
numeric subvector occurrence number.
SVID
Specifies a 1-byte (2 alphanumeric characters) subvector ID. A keyword=data
token is built for this subvector and added to the alert automation message.
SVOCCUR
Specifies the occurrence of the SVID to be found. This is a 1- or 2-character
numeric subvector occurrence number.
XLATE
Specifies whether to translate the EBCDIC representation of hexadecimal data
to hexadecimal.
N Do not do the translation. This is the default.
Y Do the translation.

DSIBAMKW: Build Automation Message Keyword

The DSIBAMKW macro establishes register conventions for a call to subroutine
SR$TK in sample CNMS4284. SR$TK moves data to a keyword=data token for the
alert automation message generated by CNMS4284.

The DSIBAMKW macro can be issued only from CNMS4284.

The following format is the syntax for the DSIBAMKW macro:

DSIBAMKW

►► DSIBAMKW DATA = ( n ) , TYPE = HEX ►

label CHARS

► , LENGTH = ( n ) ►◄
, PREFIX = SV
SF
NO

Where:
DATA
Is the number representing the address of the data to be put into the
keyword=data token.
LENGTH
Is the number representing the fullword area containing the address of the
length of the data to be put into the keyword=data token.

158 Programming: Assembler

 DSIBAMKW

PREFIX
Specifies the characters to prefix DATA on the token.
TYPE
Specifies the data type to be moved:
CHARS
The data is in EBCDIC character format.
HEX
The data is in hexadecimal format.

DSICBS: Control Block Services

The DSICBS macro creates DSECTs for the control blocks required for user-written
programs during assembly.

DSICBS ensures that a control block is included only once, inner control blocks are
included if necessary, and each definition for an inner control block precedes the
definition of the outer control block. DSICBS also controls the format and printing,
or suppression, of DSECTs for the control blocks.

DSIMVT addressability is not required.

The following format is the syntax for the DSICBS macro:

DSICBS

,
, EJECT = YES
►► DSICBS ▼ ►
label cbname , EJECT = NO
YES

, DEFER = NO , PRINT = YES

► ►
, DEFER = ALL , PRINT = NO
INCLUDE YES
NO
THESE

, RSECT = TEST
► ►◄
, RSECT = NO
TEST
YES

Where:
cbname
Is the name of a control block, starting with DSI, to be included. Names must
be separated by commas.
DEFER
Defers control block expansions.
ALL
Specifies that all subsequent DSICBSs are not expanded until a DSICBS

Chapter 8. Macros 159

DSICBS

DEFER=INCLUDE is encountered. (If you specify this operand, be sure to

code DSICBS DEFER=INCLUDE later in the program.)
INCLUDE
Specifies that any deferred control block expansions are to be expanded at
this point in the program.
NO Specifies that the control blocks are to be expanded immediately. This is
the default.
THESE
Specifies that these control block expansions are delayed until a DSICBS
DEFER=INCLUDE is encountered.
EJECT
Specifies whether EJECT statements are performed between each control block
expansion and after the last expansion.
NO Specifies that EJECT statements are not performed.
YES
Specifies that EJECT statements are performed. This is the default.
PRINT
Specifies whether control blocks are to be printed (expanded) in the assembler
listing.
NO Specifies that the control block expansion is not to be printed.
YES
Specifies that the control block expansion is to be printed. This is the
default.
RSECT
Generates the appropriate section resumption.
TEST
Test for CSECT and RSECT and resume the appropriate section. This is the
default.
NO Generate CSECT resumption.
YES
Generate RSECT resumption.

DSICES: Command Entry Services

The DSICES macro uses a specified buffer, parse descriptor block (DSIPDB), or
load module name to locate a command processor address and can be used to
determine if a task is authorized to issue a command.

DSICES locates a system command entry (DSISCE) that corresponds to the

command verb and returns the DSISCE address to a user-provided fullword area.
In addition to performing an authorization check for the command, the macro can
check whether the command is a valid command list name and whether the
command is processed as a regular or immediate command.

DSIMVT addressability is required.

The following format is the syntax for the DSICES macro:

160 Programming: Assembler

 DSICES

DSICES

►► DSICES SWB = ( register ) ►

label symbolic_name

► , BFR = ( register ) , SCTADDR = ( register ) ►

symbolic_name symbolic_name
, PDB = ( register )
symbolic_name
, MODNAME = modulename

, CLISTCK = NO
► ►◄
, CLISTCK = NO
YES

Where:
BFR
Is the register, or symbolic name of a fullword area, containing the address of
the buffer that contains the verb to be analyzed. This buffer must have an
initialized BUFHDR.
CLISTCK
Specifies whether to check for a valid command list name if the command has
no CMDDEF statement in CNMCMD or its included members.
NO Specifies that you do not need to check for a command list name if a
CMDDEF statement is not found. This is the default.
YES
Specifies that you need to check for a command list name if a CMDDEF
statement is not found.
MODNAME
Specifies the module name to be located in the system command table. You can
specify the modulename as the field that contains the module name or as the
module name enclosed in single quotation marks.
PDB
Is the register, or symbolic name of a fullword area, containing the address of a
completed parse descriptor block (DSIPDB) to be used as input.
SCTADDR
Is the register containing the address of a user-provided fullword area, or the
symbolic name of that area, where the address of the system command entry
corresponding to the module name or verb is to be returned. The returned
pointer addresses an SCT entry (DSISCE) dummy control section (DSECT).
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB). SWBTIB identifies your task information block
(DSITIB), which identifies your task type.

Note:
1. If MODNAME is specified, the first entry that is found in the SCT
corresponding to the module name is returned. If the module name specified

Chapter 8. Macros 161

DSICES

has multiple definitions in CNMCMD or its included members, an unexpected

address can be returned. In this situation, use the BFR operand instead.
2. Authorization checking is not performed if MODNAME is used.
3. BFR, PDB, and MODNAME are mutually exclusive, and you must specify one
of the three.
4. You cannot specify CLISTCK with MODNAME.

Return Codes in Register 15

The following return codes for the DSICES macro are found in register 15:
0 The function is successful. One of the following conditions describe what
occurred:
v A regular command is found in the system command table and the
address of the SCT entry is returned.
v The verb is not found in the SCT (if you specify CLISTCK, a command
list is found with the specified name), and the dummy SCT entry for a
command list is returned.
4 The command that is found can be processed as a regular or immediate
command; the address is returned.
8 An immediate command is found in the system command table; the
address is returned.
12 The module is not found, or there is an incorrect verb length; no address is
returned.
16 The operator is not authorized to issue the command. This is caused by the
security definitions that are in place for this command. No address is
returned in SCTADDR.
This return code is not applicable if MODNAME was specified.
20 Either the command found is incompatible with the task type that called
the routine, and the address is returned; or you specified CLISTCK=YES
and the request is issued in an asynchronous exit, and the address is not
returned.
24 You specified CLISTCK=YES but the command or command list is not
found in DSISCT or DSICLD.
28 You specified CLISTCK=YES but storage requested for CLISTCK
processing is not obtained.
32 NetView internal error.
36 An unexpected return code was received from the security authorization
facility (SAF). Message BNH238E is issued with the SAF return code
inserted. This return code is not applicable if MODNAME was specified as
this specification causes no authorization checking to be performed.
40 Authorization to the command 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. This return code is not applicable if
MODNAME was specified as this specification causes no authorization
checking to be performed.
44 Authorization to the command is not granted because an unexpected
return code was received from the command authorization table. Message

162 Programming: Assembler

 DSICES

BNH199E is issued indicating the command identifier and the operator ID

being checked. This return code is not applicable if MODNAME was
specified as this specification causes no authorization checking to be
performed.
48 Authorization to the command 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 being
checked. This return code is not applicable if MODNAME was specified as
this specification causes no authorization checking to be performed.
52 Authorization to the command is not granted because the source ID is
blank in the NetView internal security information. Message BNH277E is
issued identifying the command being checked. This return code is not
applicable if MODNAME was specified as this specification causes no
authorization checking to be performed.

DSICVTHE: Convert to Hexadecimal

The DSICVTHE macro establishes register conventions for a call to subroutine
SR$HEX in sample CNMS4284. SR$HEX converts a hexadecimal input string to
EBCDIC character format for the alert automation message generated by
CNMS4284.

The DSICVTHE macro is issued ONLY from CNMS4284.

The following format is the syntax for the DSICVTHE macro:

DSICVTHE

►► DSICVTHE INPUT = ( register ) ►

label symbolic_name

► , LENGTH = ( register ) , OUTPUT = ( register ) ►◄

symbolic_name symbolic_name

Where:
INPUT
Is the register, or symbolic name of the fullword area, containing the address of
the input string to convert.
LENGTH
Is the register, or symbolic name of the fullword area, containing the address of
the length of the input string to convert.
OUTPUT
Is the register, or symbolic name of the fullword area, containing the address to
which the conversion of the input string is to be moved.

DSIC2T: Code Point Translation Service Reference

You can use NetView Bridge with a problem-management database to open
problem records when NetView alerts are received. When you use NetView Bridge
in this manner, translate the numeric code points received in the alert into readable
text. The NetView code point translation service is provided to perform this
translation.

Chapter 8. Macros 163

DSIC2T

The code point translation service routine is available to the NetView program in
REXX, PL/I, C, and assembly languages. The function performed is the same,
regardless of the language you choose to use.

The following format is the syntax for the DSIC2T macro:

DSIC2T

►► DSIC2T SWB = ( register ) ►

label symbolic_name

► , TXTAREA = ( register ) , MXTXTLN = ( register ) ►

symbolic_name symbolic_name

► , TABLE = ( register ) , CODE = ( register ) ►

symbolic_name symbolic_name

► , TXTLENG = ( register ) ►◄
symbolic_name

Where:
CODE
Is the register containing the address of the area that contains the code point to
be translated, or symbolic name of that area.
MXTXTLN
Is the register containing the address of the area that contains the maximum
length of the text that can be returned, or symbolic name of that area. This is
the maximum length of the txtarea field.
SWB
Is the register containing the address of a service work block, or symbolic
name of that area.
TABLE
Is the register containing the address of the area that contains the 8-character
name of the table to be used in the translation, or symbolic name of that area.
The following tables are valid:
SNAALERT
SNA alert description code point
SNACAUSE
SNA probable cause
SNADDATA
SNA detailed data
SNAFCAUS
SNA failure cause
SNAICAUS
SNA install cause
SNAREACT
SNA recommended actions
SNAUCAUS
SNA user cause

164 Programming: Assembler

 DSIC2T

TXTAREA
Is the register containing the address of the area that receives the text for the
translated code point, or symbolic name of that area.
TXTLENG
Is the register containing the address of the area that contains the length of the
text returned for the specified code point, or symbolic name of that area.

Note: If the alert text is truncated, it is truncated using the MXTXTLN field
value. Then the TXTLENG field contains the full alert text length.

Return Codes in Register 15

The following return codes are for the DSIC2T macro:
0 The function is successful.
4 Alert text is truncated at specified MXTXTLN length. TXTLENG contains
full alert text length.
8 Code point was not found. Length of TXTLENG is zero (0).
12 Table type is incorrect.

DSIDATIM: Date and Time

The DSIDATIM macro obtains and formats the date and time.

DSIDATIM places the date and time in an output area. You can use this macro to
obtain the time for the HDRTSTMP field of a message.

MVT addressability is required.

The following format is the syntax for the DSIDATIM macro:

DSIDATIM

►► DSIDATIM AREA = ( register ) ►

label symbolic_name

, FORMAT = EBCDIC
► ►◄
, FORMAT = BINARY
EBCDIC

Where:
AREA
Is the register containing the address of the area into which the date and time
are returned, or symbolic name of that area. This area does not have a buffer
header.
FORMAT
Specifies the format of the output.
BINARY
Returns the date and time in 8 bytes in packed decimal format as follows:
0CyydddFhhmmss0C

Chapter 8. Macros 165

DSIDATIM

Where 0C indicates the century. In the years 1900 through 1999, the value
of this field is 00. In the years 2000 through 2099, the value of this field is
01 yy is the last two digits of the year. ddd is the day. F is a 4–bit sign
character that enables the data to be unpacked and printed. hh is the hour,
mm is the minute, and ss is seconds. The ending X’0C’ indicates the data is
in packed decimal format.
EBCDIC
Returns the date and time in 17 bytes (including the space between date
and time) formatted as follows:
mm/dd/yy hh:mm:ss

Where mm is the month, dd is the day, yy is the year, hh is the hours, mm is

the minutes, and ss is the seconds. EBCDIC is the default.

Note: When using the BINARY form of DSIDATIM to initialize a HDRTSTMP, use
an 8-byte work area for the AREA, and move the low-order 4 bytes to HDRTSTMP
(X’hhmmss0C’).

DSIDEL: Delete User-Defined Module

The DSIDEL macro deletes user-defined load modules. You specify the name of the
module to be deleted. The following format is the syntax for the DSIDEL macro:

DSIDEL

►► DSIDEL EP = modulename ►◄
label EPLOC = ( register )
symbolic_name

Where:
EP Specifies the name of the module to be deleted.
EPLOC
Specifies the address of an 8-byte field that contains the module name to be
deleted. The module name is left-aligned and padded with blanks.

Return Codes in Register 15

The following return codes for the DSIDEL macro are found in register 15:
0 The module has been deleted.
Nonzero
The attempt to delete the module was unsuccessful.

Refer to your operating system macro reference for the system macro return code
description.

DSIDKS: Disk Services

You can use the DSIDKS macro to connect to a DDNAME, locate a member, and
read the records in that member. You can use this macro only to connect to data
sets with the following DDNAMEs:
BNJPNL1
BNJPNL2

166 Programming: Assembler

 DSIDKS

CNMPNL1
DSIARPT
DSIASRC
DSICLD
DSILIST
DSIMSG
DSIOPEN
DSIPARM
DSIPRF
DSIVTAM

The NetView program opens these data sets and keeps them open as long as
NetView is operating. You can then use DSIDKS to find and read any member in
any of the data sets concatenated under any of the DDNAMEs in your NetView
startup procedure.

You must have a copy of the DSECT for the data services block (DSIDSB) included
in your program. DSIMVT addressability is also required.

The following format is the syntax for the DSIDKS macro:

DSIDKS

►► DSIDKS SWB = ( register ) ►

label symbolic_name

► , DSBWORD = ( register ) , TYPE = CONN ►

symbolic_name FIND
DISC
READ

, INCL = NO
► , NAME = ( register ) ►◄
symbolic_name , INCL = NO
YES

Where:
DSBWORD
Is the register containing the address of a user-provided fullword area on a
fullword boundary, or symbolic name of that fullword area. When the macro
completes processing for TYPE=CONN, this area contains the address of the
DSB. For other disk service requests, this area specifies the DSB address
previously obtained by TYPE=CONN.
INCL
Specifies whether %INCLUDE statements are to be processed. An %INCLUDE
statement is a record type that enables another member or file to be embedded
into the member or file being read at the point that the %INCLUDE statement
is found.
INCL=YES specifies that any %INCLUDE statements found are to be processed
and the members on files specified on the %INCLUDE statements found are to

Chapter 8. Macros 167

DSIDKS

be embedded. INCL=NO specifies that any %INCLUDE statements found are

not to be processed. The INCL default is NO.
For DD names listed previously, other than DSICLD, INCL=YES also enables
the use of Data REXX in the member. Refer to IBM Tivoli NetView for z/OS
Programming: REXX and the NetView Command List Language for details.
NAME
For TYPE=CONN and TYPE=DISC, a register containing the address of an
8-character user area with the caller's definition name (DDNAME), or the
symbolic name of that area. The area is left-aligned and padded with blanks.
For TYPE=FIND, NAME is a register containing the address of an 8-character
user area that contains the name of the member to be read, or the symbolic
name of that area.
For TYPE=READ, NAME is not needed.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).
TYPE
Specifies the type of processing the service routine is to perform:
CONN
Specifies that the service routine is to connect to or access the caller's
definition name (DDNAME). The address of the DSB is returned in the
area specified by the DSBWORD operand. You must issue DSIDKS with
this option before you can choose any other options.
DISC
Specifies that the service routine is to disconnect from the DDNAME and
release the DSB.
FIND
Specifies that the service routine is to find the member specified by the
NAME operand. If the member is found, the first record is read. DSBBUFF
addresses the buffer containing this record. Do not specify this option
unless you also specify the CONN option.
READ
Specifies that the service routine is to read the next sequential record in the
member. Do not specify this option unless you also specify the FIND
option.

Return Codes in Register 15

The return codes and code meanings in register 15 are dependent on the “TYPE=”
specification.

The following return codes are for TYPE=CONN:

0 The function is successful. Data control blocks and I/O buffer are obtained
and initialized.
4 An incorrect data set name.
12 No storage was available for I/O buffer.

The following return codes are for TYPE=FIND:

168 Programming: Assembler

 DSIDKS

0 The function is successful. The member or file is found and the first record
is read.
4 The member or file is not found in the source statement library or in the
specified library, or an empty member or file is found.
8 The member or file is found but an I/O error occurred on the first read.
12 The specified definition name or data set has not been opened.
20 The specified control block identifier is not valid; the member or file is not
found.
28 There is a syntax error in the %INCLUDE statement.
36 There is an incorrect member name on the %INCLUDE statement.
40 There is an incorrect embed member, which can cause a deadlock
condition. (This occurs when a member embeds itself.)
44 An unrecoverable system error occurred. An internal NetView service
failed, because of a storage failure.
46 An I/O error is encountered while trying to include a member specified in
an %INCLUDE statement.
100 + xx
An error occurred during CLOSE processing. The NetView program
attempts to recover the data set after a failure during a previous FIND or
READ. Refer to the description of the xx return code under the CLOSE
macro in your operating system macro reference.
200 + xx
An error occurred during OPEN processing. The NetView program
attempts to recover the data set after a failure during a previous FIND or
READ. Refer to the description of the xx return code under the OPEN
macro in your operating system macro reference.

The following return codes are for TYPE=DISC:

0 The disconnect is successful; data and I/O buffers are freed successfully.
20 The specified control block identifier is not valid and no storage is freed.
46 An I/O error is encountered while trying to INCLUDE a member specified
in an %INCLUDE statement.

The following return codes are for TYPE=READ:

0 The function is successful; the record is read.
4 The end of data is reached.
8 An I/O error occurred during reading.
12 Reading of this record is prohibited; an I/O error can occur, the end of
data might be reached, or the caller did not issue TYPE=FIND first.
20 The specified control block identifier is not valid; the record is not read.
28 There is a syntax error in the %INCLUDE statement.
36 A member name on the %INCLUDE statement is not valid.
40 An embed member is not valid and can cause a deadlock condition. (This
occurs when a member embeds itself.)

Chapter 8. Macros 169

DSIDKS

44 An unrecoverable system error occurred. An internal NetView service

failed, because of a storage failure.
46 An I/O error is encountered while trying to include a member specified in
an %INCLUDE statement.
100 + xx
An error occurred during CLOSE processing. The NetView program
attempts to recover the data set after a failure during a previous FIND or
READ. Refer to the description of the xx return code under the CLOSE
macro in your operating system macro reference.
200 + xx
An error occurred during OPEN processing. The NetView program
attempts to recover the data set after a failure during a previous FIND or
READ. Refer to the description of the xx return code under the OPEN
macro in your operating system macro reference.

Refer to the IBM Tivoli NetView for z/OS Administration Reference for information
about how to code an %INCLUDE statement.

DSIFIND: Find Long-Running Command Storage

The DSIFIND macro retrieves a pointer to storage for a long-running command
processor and returns the storage address in register 1. A prior DSIPUSH
instruction names the storage pointer.

If two storage pointers are given identical names, DSIFIND retrieves the most
recent storage address with the specified name. You can issue DSIFIND in an
immediate command. See “DSIPUSH: Establish Long-Running Command” on page
223 and “DSIPOP: Remove Long-Running Command” on page 211 for more
information.

DSIMVT addressability is required.

The following format is the syntax for the DSIFIND macro:

DSIFIND

►► DSIFIND SWB = ( register ) ►

label symbolic_name

, CORR = NONE
► , LIST = ( register ) ►◄
symbolic_name , CORR = CMD
NONE

Where:
CORR
Defines the correlation option for the DSIFIND request.
When a RESUME routine is specified for DSIPUSH, the RESUME routine is
called with the correlation active at the time of the DSIPUSH regardless of the
CORR option on either the DSIPUSH or the DSIFIND.
The following list shows the options:

170 Programming: Assembler

 DSIFIND

CMD
Means that the correlation environment saved by DSIPUSH is retrieved
and becomes the current command correlation environment. The
correlation environment is saved if the CORR=CMD option was specified
on DSIPUSH, and there was no associated RESUME routine specified on
DSIPUSH, or if DSIPUSH specified an associated RESUME routine.
This function enables the DSIPSS output of a command using the DSIFIND
CORR=CMD to be treated as if it was issued by the command that issued
this DSIPUSH. The output in most cases is asynchronous when processed
by a NetView pipeline. Code a CORRWAIT stage in the pipeline.

Note: RESUME routines are a way to provide correlation and as a general

method of writing NetView functions. The CORR=CMD option is intended
for cases where a RESUME routine might be impractical.
NONE
Specifies that DSIFIND does not make the saved correlation environment
the current command correlation environment. NONE is the default when
the CORR keyword is omitted.
LIST
Is the register containing the address of the parameter list used by the service
routine, or symbolic name of that list. Do not specify this as register 1; register
1 contains the SWB address within DSIFIND. Do not put this list in the SWB
that is to be passed to DSIFIND.
The parameter list is mapped by SWBLRCPL and contains the following fields:
Table 41. LIST Parameters for the DSIFIND Command
Hex Offset Length Field
0 4 SWBLRCLN (length)
4 16 SWBLRCNM (name)

Where:
SWBLRCLN
Specifies the parameter list length. Set this halfword equal to SWBLRCFI
(decimal 20).
SWBLRCNM
Specifies the name of the storage to be located. The storage address is
returned in register 1. Specify this field exactly as you specified it in the
corresponding DSIPUSH macro. See “DSIPUSH: Establish Long-Running
Command” on page 223 for more information about specifying the name
field.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB). The task information block (DSITIB) address in
SWBTIB must be correctly set.

Return Codes in Register 15

The following return codes for the DSIFIND macro are found in register 15:
0 The function is successful; the storage pointer is retrieved and the storage
address is returned in register 1.

Chapter 8. Macros 171

DSIFIND

32 Macro invocation is not valid. Correct assembly errors before trying to run
the program.
36 The specified NAME is not found.

DSIFRE: Free Storage

You must use the DSIFRE macro to release storage that was obtained using the
DSIGET macro. Storage that was not obtained with DSIGET cannot be released
using DSIFRE. Optionally, DSIFRE dequeues the storage from the user's task vector
block (DSITVB).

Registers 2–12 can be used for register notation. DSIFRE always generates reentrant
code.

DSIMVT addressability is required.

The following format is the syntax for the DSIFRE macro:

DSIFRE

►► DSIFRE LV = ( n ) ►
label ( register )

, SP = 0
► , A = ( register ) ►
symbolic_name , SP = ( register )
number

, Q = NO
► ►
, Q = YES , TASKA = ( register )
symbolic_name

, MAINTSK = NO
► ►◄
, MAINTSK = YES

Where:
A Is the register, or symbolic name of a fullword area on a fullword boundary,
containing the address of the storage to be freed.
LV Is the number of bytes, or a register that contains the number of bytes, of
storage to be freed. This option is ignored if you specify Q=YES.
MAINTSK
Indicates whether the storage to be freed requires special handling to avoid
storage accounting problems. MAINTSK=YES indicates that the storage is
treated as if it was owned by the NetView main task.
Specify MAINTSK=YES and Q=NO under the following conditions:
v The storage is obtained by one task.
v This storage is to be freed by a different task.
v The storage is not a buffer transferred by DSIMQS.
MAINTSK is ignored when Q=YES.

172 Programming: Assembler

 DSIFRE

NO Specifies that the storage is not to be treated as if it was owned by the

NetView main task. This is the default.
YES
Specifies that the storage is to be treated as if it was owned by the
NetView main task.
Q Indicates whether the storage being released was obtained with DSIGET option
Q=YES. This storage is queued to your task's TVB and is subject to automatic
release upon task termination.
NO Specifies that storage to be released was obtained with DSIGET option
Q=NO. This is the default.
YES
Specifies that storage to be released was obtained with DSIGET option
Q=YES. If you obtained the storage in this way, the length is known to the
NetView program and the LV option is not necessary.
SP Is the subpool number, or a register loaded with the subpool number, from
which the storage is to be freed. Values in the range of 0–255 are acceptable; 0
is the default value.
TASKA
Is the register containing the address of the TVB, or symbolic name of the TVB
for this task. If you do not specify this operand, the default is DSITVB, and
addressability to the DSITVB is required.

Return Codes in Register 15

The following return codes for the DSIFRE macro are found in register 15:
0 The function is successful; storage is freed and dequeued.
4 A possible storage overlay is detected. This return code is accompanied by
the DWO115W message. Depending on the value you coded for
STORDUMP, a memory dump might be attempted.
8 A storage mapping failure was detected. This means that the length or
subpool on a piece of storage being freed does not match the length or
subpool of the storage when it was gotten, or the storage might have
already been freed. This error condition can result in an S378 abend.
12 The error conditions indicated by return codes 4 and 8 were both detected.
16 DSIFRE detected that a NetView storage management control block might
be overlaid, or it contains pointers that are not valid (which can be the
result of an overlay). The DWO115W message is issued, and depending on
the value of STORDUMP, a memory dump is attempted.
20 For storage subpools 0–15, of a size less than or equal to X'FE8' (decimal
4072), either DSIFRE Q=YES was issued for storage that was not obtained
with DSIGET Q=YES, or the storage specified on the DSIFRE (Q=YES or
Q=NO) has already been freed. The DWO115W message is issued with this
return code, and depending on the value of STORDUMP, a memory dump
can be attempted.
24 A zero length and zero address was specified on DSIFRE without the AQ
option.
40, 42, 44, 46
A NetView internal error was detected. A storage overlay memory dump

Chapter 8. Macros 173

DSIFRE

can be attempted, depending on the value of STORDUMP. Contact IBM

Software Support for programming assistance.

Note:
1. For all return codes, if a storage overlay memory dump is taken, register 7 at
the time of the memory dump contains the return code. For more information
about the contents of the registers at the time of the memory dump, see the
IBM Tivoli NetView for z/OS Troubleshooting Guide.
2. NetView-detectable DSIFRE Q=YES errors result in NetView user abend
ABENDU084. Most of these errors are a possible indication of a storage overlay.
The user abend and associated memory dump are taken to facilitate problem
determination.
3. If an ABENDSA78 occurs at task termination and this DSIFRE error (return
code 20 in register 15) occurs, a trace with OPT=STOR shows the DSIFRE trace
entries with a return code of 20.
As an additional aid if this abend occurs, the return address of any issuer of
DSIFRE Q=NO that results in a return code of 20 in the trace is stored in the
DSITVB control block for the task under which the DSIFRE was issued. The
saved address is in field TVBFREM (TVB + X'1B4').
4. If you are a programmer developing new code to run under NetView, this
return code indicates that you might have coded a DSIGET/DSIFRE pair
incorrectly, or might have coded one without the other.
For example, if you acquire storage using a system macro such as GETMAIN,
but release the storage with the DSIFRE macro, the issuer of DSIFRE receives a
return code 20. In this case, the return code 20 is not an error, but indicates that
you did not use DSIGET to acquire the storage. DSIFRE uses FREMAIN to free
the storage.

DSIFREBS: Call DSIFREBS Service

The DSIFREBS macro is provided to simplify the call to the DSIFREBF assembly
language called service routine. For an example of how to use it, see “Free
NetView Buffers Service Routine (DSIFREBF)” on page 267.

DSIGET: Get Storage

You can use the DSIGET macro to get storage. Optionally, you can use DSIGET to
queue the obtained storage to your task vector block (DSITVB). Storage obtained
with DSIGET is released using DSIFRE.

Registers 2–12 can be used for register notation. With DSIGET, you can queue
storage on the TVB chain so that the NetView program can free the storage at
logoff.

The following format is the syntax for the DSIGET macro:

DSIGET

►► DSIGET LV = ( n ) ►
label ( register )

174 Programming: Assembler

 DSIGET

► , A = ( register ) ►
symbolic_name , SP = ( register )
number

, LOC = RES , BNDRY = DBLWD , CLEAR = YES

► ►
, LOC = ANY , BNDRY = DBLWD , CLEAR = NO
BELOW PAGE
RES
TEST

, Q = NO
► ►
, Q = YES , TASKA = ( register )
symbolic_name

, MAINTSK = NO
► ►◄
, MAINTSK = YES

Where:
A Is the register containing the address of the fullword area on a fullword
boundary into which the address of the obtained storage is returned, or
symbolic name of that fullword area.
BNDRY
Specifies the alignment of obtained storage.
DBLWD
Specifies that obtained storage is to be aligned on a doubleword boundary.
This is the default.
PAGE
Specifies that obtained storage is to be aligned on a page boundary.
CLEAR
Specifies whether the allocated storage is to be initialized to 0.
NO Specifies that storage is not to be initialized.
YES
Specifies that storage is to be initialized. This is the default.
LOC
This operand specifies where to allocate storage.
ANY
Allocates storage anywhere.
BELOW
Allocates storage below 16 MB.
RES
Allocates storage that is consistent with the residency of the caller. This is
the default.
TEST
The caller of DSIGET has set the high-order bit of register 15 to indicate
the type of storage preferred. A 0 in the high-order bit means allocate
storage below 16 MB; a 1 means allocate storage anywhere.

Chapter 8. Macros 175

DSIGET

LV Is the number of bytes, or a register containing the number of bytes, of storage

to be obtained. The value must be positive.
MAINTSK
Indicates whether the storage to be obtained requires special handling to avoid
storage accounting problems. MAINTSK=YES indicates that the storage is
treated as if it is owned by the NetView main task.
Specify MAINTSK=YES and Q=NO when:
v The storage is obtained by one task.
v This storage is to be freed by a different task.
v The storage is not a buffer transferred by DSIMQS.
Multiple data buffers, such as those described by the DSIIFR macro, are
accounted for by the NetView program during DSIMQS. These buffers must be
obtained with MAINTSK=NO.
MAINTSK is ignored when Q=YES.
NO Specifies that the storage is not to be treated as if it was owned by the
NetView main task. This is the default.
YES
Specifies that the storage is to be treated as if it was owned by the
NetView main task.
Q Indicates whether the obtained storage is to be queued to your TVB. The
option specified for this operand must correspond to the option specified for
the Q operand in DSIFRE that is used to free the storage.
NO Specifies that storage is not to be queued. This is the default.
YES
Specifies that storage is to be queued.
SP Is the subpool number, or register containing the subpool number, from which
the storage is to be obtained. Values in the range of 0–255 are acceptable; 0 is
the default value.
Using a subpool in the range of 0–15 enables the NetView program to use its
storage management function for pooling storage. This improves performance
on individual requests of storage, but causes a slight increase in the amount of
storage used by the NetView program. Using a subpool in the range of 16–255
causes the NetView program to issue a GETMAIN for each storage request.
This lessens the amount of storage used, but slows performance.
TASKA
Is the register containing the address of the TVB for this task, or symbolic
name of that TVB. If you do not specify this operand, the default is DSITVB
and addressability to the DSITVB is required.

Return Codes in Register 15

The following return codes for the DSIGET macro are found in register 15:
0 The function is successful; storage was obtained.
4 No storage is obtained.
8 A negative or zero length was specified on the DSIGET call.

176 Programming: Assembler

 DSIGETDS

DSIGETDS: Data Queue Manipulation Service

You can use the DSIGETDS macro to retrieve single-line and multiline messages
and MSUs in the initial data queue (pointed to by TVBAIIFR).

The following format is the syntax for the DSIGETDS macro:

DSIGETDS

►► DSIGETDS SWB = swbname ►

label ( register )

► , DATAPTR = dataptr , DATALEN = datalen ►

( register )

► ►
, INDEX = indexvalue , LTYPE = lnetypearea

► ►
, BTYPE = btypearea , DOMID = domidarea

► ►
, TASKID = taskidarea , TOTLINE = totlinearea

► ►
, ORIGNET = orignetarea , ORIGLU = origluarea

► ►◄
, ORIGAPP = origapparea

Where:
BTYPE
Specifies a 1-byte area in which the buffer type (as in HDRMTYPE) is returned.
For an MSU, it is M. If the command processor is driven by automation of an
alert, the second element is the hierarchy list and the buffer type is H.
MSU has a HDRMTYPE of X'10'. When the line type (HDRLNTYP) is B'00', M
is returned. When the line type is B'01' (the hierarchy list), H is returned.
DATALEN
Specifies a 4-byte integer field where the length of the data (message text or
MSU) is returned.
DATAPTR
Specifies the name of the 4-byte pointer field in which the address of the
message text or MDS-MU data is returned. You can specify the name of the
data pointer or a register containing a pointer to the data pointer. Do not free
the storage pointed to by DATAPTR. If you need a copy, copy the data into
your own storage area.
DOMID
Specifies an 8-byte area in which the origin domain ID (as in HDRDOMID) is
returned. For an MDS-MU, this is the current NetView domain ID.
INDEX
Specifies a 4-byte integer field containing the number (index) of the line of the
message to be returned, or of the MDS-MU within a chain of reply MDS-MUs

Chapter 8. Macros 177

DSIGETDS

to be returned. If you do not specify index, or if you specify it with a value of

zero, the next available line or MDS-MU is returned.
LTYPE
Specifies a 1-byte area in which the line type is returned. For an MDS-MU or a
single-line message, it is blank. For an MLWTO, it can be set to the following
values:
C Control line
L Label line
D Data line
E End line without data
F End line with data
ORIGAPP
An 8-byte character field in which the origin application name from the MDS
header is returned if the data is an MDS-MU. If the data is not an MDS-MU,
blanks are returned.
ORIGLU
An 8-byte character field in which the origin LU or VTAM CP name from the
MDS header is returned if the data is an MDS-MU. If the data is not an
MDS-MU, blanks are returned.
ORIGNET
An 8-byte character field in which the origin network ID from the MDS header
is returned if the data is an MDS-MU. If the data is not an MDS-MU, blanks
are returned.
SWB
Specifies a 4-byte pointer field containing the address of the service work block
(DSISWB) control block. You can specify either the name of the SWB or a
register containing the pointer to the SWB.
SWBTIB must have the address of the task information block (DSITIB).
TASKID
Specifies an 8-byte area in which the origin task ID (as in HDRSENDR) is
returned. For an MDS-MU, this is the task ID of the MS transport DST.
TOTLINE
A 4-byte integer field in which the total number of lines (for example, total
number of lines in a MLWTO) is returned. For an MDS-MU, this is 1 or the
number of replies in the chain of MDS-MUs. For an automated alert, this is 2.

Return Codes in Register 15

The following list shows the return codes for the DSIHREGS macro, found in
register 15:
0 The requested function is performed (CNM_GOOD).
12 TIB specified is not valid.
80 Queue empty (CNM_QUEUE_EMPTY).

Note: Most of the return codes are declared in DSIRTN.

178 Programming: Assembler

 DSIHREGS

DSIHREGS: High-Performance Transport Application Registration

The DSIHREGS macro registers any application that wants to send data to or
receive data from another application through the high-performance transport
application program interface (API). Register the application before attempting to
send or receive data.

DSIHREGS 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.

In addition to registering the application, the registration includes the command

name of the command processor to be called when asynchronous unsolicited data
is routed to the application. This command processor runs under the task that
called the registration macro. Also, you can specify the logmode that this
application uses.

The service program you call keeps track of the registered applications to provide
routing. The NetView program verifies the command you specify as the command
to be driven when unsolicited data is received.

You can specify whether the current registration is replaced. When you replace
prior registrations, the later registration can replace the task or the command
processor. The logmode for the second registration request must be the same as the
first and cannot be changed by a later registration request. To change the logmode,
deregister the application and reregister it with the new logmode.

The following format is the syntax for the DSIHREGS macro:

DSIHREGS

►► DSIHREGS SWB = swbname ►

label ( register )

► , TYPE = REGAPPL , APPL = applname ►

DREGAPPL ( register )

► ►
, COMMAND = cmdname , LOGMODE = logmode
( register ) ( register )

, REPLACE = YES , NOTIFY = NONE

► ►
, REPLACE = NO , NOTIFY = ALL
YES ERROR
NONE

, PRI = LOW
► ►◄
, PRI = HIGH
LOW
NORMAL
TEST

Chapter 8. Macros 179

DSIHREGS

Where:
APPL
Is an 8-byte character field that specifies the application name that is being
registered or deregistered.
The identifier name can be one of the following values:
v An architecturally defined 4-byte value (padded with blanks to 8 bytes) for
management services (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).
The application names and their hexadecimal equivalents, for the NetView
program that reserves application name categories are as follows:
ALERT
X'23F0F3F1'
EP_OPS
X'23F0F1F6'
EP_SPCS
X'23F0F1F4'
LINKSERV
X'23F0F3F5'
MS_CAPS
X'23F0F1F1'
OPS_MGMT
X'23F0F1F7'
R_BRIDGE
X'30F0F5F9'
RMTCMD_O
X'30F0F7F2'
RMTCMD_R
X'30F0F5F5'
RMTCMD_S
X'30F0F7F0'
SPCS X'23F0F1F5'
STATUS
No hexadecimal equivalent
No character equivalent
X'23F0F1F0'
No character equivalent
X'23F0F0F1'
No character equivalent
X'30F0F7F3'

Note: If you use an architected name, you must supply a field name because
hexadecimal data cannot be specified in a literal string. The registration service
routine ignores any trailing blanks.
COMMAND
Is an 8-byte character field that specifies the command name of the command

180 Programming: Assembler

 DSIHREGS

processor that is driven with any data, received as a message unit, or has a
destination application name equal to the one in the applname operand.
COMMAND is either the command name or a register containing a pointer to
it. This field is required for registration requests but is not valid for
deregistration requests.
LOGMODE
Is an 8-byte character field that specifies the logmode that is used for sending
the application data. This name is a logmode that is defined to the local VTAM
and the receiving LU or control point (CP) with which this application
communicates.
If you specify a LOGMODE that is not defined in the local VTAM logmode
table, VTAM defaults this value to the first LOGMODE defined in the local
logmode table.

Note: Use LOGMODE only on the first registration request for an application.
If another command processor registers for an application that is already
registered, LOGMODE is ignored.
NOTIFY
Is a literal value that specifies whether this registration is to supply an MDS
error message if connectivity to other nodes is lost. NONE is the default.
ALL Specifies that this registration receives all the notifications that ERROR
provides, and in cases when the high-performance transport classifies a
session outage as normal and does not attempt to reestablish
connectivity.
NONE
Specifies that this registration does not receive any error notification.
NONE is the default.
ERROR
Specifies that this registration receives notification if there is a normal
or abnormal loss of connectivity to another node. A normal loss can
occur if you have outstanding transactions with the other node. An
abnormal loss can occur if you have a session outage and connectivity
cannot be reestablished.

Note: If two nodes in two networks have the same LU name, VTAM can
locate either one, depending on the active configuration.
PRI
Supplies the MQS priority for incoming requests. The MQS priority is used
when the MS or high performance transport uses the MQS for processing of
any received unsolicited MDS-MUs. The value is one of the four strings HIGH,
NORMAL, LOW, or TEST, The priority value must be entered as 8-bytes,
including blanks. For example:
’LOW ’
’HIGH ’
’NORMAL ’
’TEST ’

Note: The single quotation marks are shown only to demonstrate the 8-byte
field. Do not include them as part of the priority specification.
The following list shows the priorities:

Chapter 8. Macros 181

DSIHREGS

HIGH
Processing begins after any NORMAL requests currently in progress, but
before queued NORMAL or LOW requests.
LOW
Processing is preempted by HIGH and NORMAL priority requests. This is
the default.
NORMAL
Processing priority preempts a queue of LOW priority requests.
TEST
DSIMQS queues the request at either HIGH or LOW priority, according to
the destination task's command priority. Refer to the OVERRIDE command
in the NetView online help for an explanation of command priorities.
REPLACE
Is a 4-byte character field that specifies whether this registration is to
supersede any previous registration for this application.
YES Specifies that this registration replaces the current registration for this
application. YES is the default. If you specify YES, an application can
change the name of the command driven to process received data and
the task where the command is driven with unsolicited data.
NO Specifies that this registration does not replace the current registration
for this application.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).
TYPE
Is a 10-byte character field that specifies the type of request:
REGAPPL
Registers an application to the high-performance transport.
DEREGAPPL
Deregisters an application from the high-performance transport.

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 DSIHREGS is
called 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 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 DSIHREGS is called for the receiving application.

You can change the task under which DSIHREGS was called by registering the
application from the preferred task and specifying REPLACE=YES.

182 Programming: Assembler

 DSIHREGS

Return Codes in Register 15

The following return codes for the DSIHREGS macro are found in register 15:
0 The function is successful. The application (APPL) was registered or
deregistered. LOGMODE cannot be changed on a subsequent registration
request unless the application is first deregistered.
4 The attempt made to change the LOGMODE for an application that is
already registered is not valid.
16 LOGMODE is not specified, or the restricted logmode SNASVCMG is
used.
20 Deregistration unsuccessful; APPL is not registered.
24 Registration unsuccessful; no storage available.
44 Deregistration unsuccessful; issued from an installation exit.
104 Registration unsuccessful; APPL is already registered.
472 Registration/deregistration unsuccessful. The resource user queue is full.
476 Registration/deregistration unsuccessful; APPL name syntax is not correct.
480 Registration/deregistration unsuccessful; APPL is restricted.
580 Registration unsuccessful. LOGMODE does not match the existing
LOGMODE for APPL.
584 Registration unsuccessful. A value for LOGMODE is required.
500 + xx
Registration unsuccessful; failure in the internal NetView resource
manager.
9012 Registration unsuccessful; COMMAND not valid.
9016 Registration unsuccessful. The current task is not authorized for
COMMAND.
9020 Registration unsuccessful. The current task and COMMAND are not
compatible.

DSIHSNDS: Send High-Performance Message Unit

The DSIHSNDS macro enables NetView applications to send data to a specified
target through the high-performance transport. The high-performance transport
uses an LU 6.2 conversation, and VTAM selects the appropriate session for the
actual transmission. You can call DSIHSNDS only in applications registered
through DSIHREGS.

The data is sent in the form of an MDS-MU. You can supply the following
information:
v A completely built MDS-MU
v An MDS-MU that is missing one or more of the following values:
– A unit of work correlator (UOWC)
– An origin NETID
– An origin LUNAME
These are added by the service routine.
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.

Chapter 8. Macros 183

DSIHSNDS

Refer to the SNA library for more information about MDS-MUs and GDS variables.

The DSIHSNDS macro builds the necessary NetView MQS buffer with the
specified data and queues it to the high-performance transport.

The following format is the syntax for the DSIHSNDS macro:

DSIHSNDS

►► DSIHSNDS SWB = swbname ►

label ( register )

, DATATYP = MDSMU
► , DATA = dataarea ►
, DATATYP = MDSMU ( register )
NONMDSMU

► ►
, SUPCORR = dataarea , CORAREA = correlarea
( register ) ( register )

► ►
, SECONDS = timeout , REPCMD = replycmd
constant ( register )

► ►
, ORIGAPP = origappl , DESTNET = destnet
( register ) ( register )

► ►
, DESTLU = destlu , DESTAPP = destappl
( register ) ( register )

► ►
, MUTYPEA = mutype , PRI = priority
( register )

, SYNCH = NO_BUF
► ►◄
, SYNCH = NO_BUF
NO_UNBUF

Where:
CORAREA
Is a 52-byte varying length character field in which a new unit of work
correlator (X'1549') GDS variable is created and returned by the DSIHSNDS
macro. The length subfield (the first 2 bytes) indicates the length of the
correlator. The correlator length is always 52 bytes for this release of the
NetView program.
If you specify CORAREA for an MDS-MU, the NetView program creates the
unit of work correlator in this area and inserts it into the specified MDS-MU

184 Programming: Assembler

 DSIHSNDS

while copying it into the buffer for the high-performance transport. In this
case, NETID and LUNAME are inserted into the origin location (X'81')
subvector at the same time if they are not already present (if there are no X'01'
and X'02' subfields within the subvector). If you omit CORAREA, the
MDS-MU must be complete and ready to be transmitted as supplied.
For NONMDSMU specify either CORAREA or SUPCORR. If you specify
CORAREA, DSIHSNDS creates the unit of work correlator GDS variable in this
area and uses it in building the MDS header. The service routine uses the
supplied value in building the MDS header if you specify SUPCORR. No
validity checking is done for a correlator the caller supplies.
If this is an MDS reply or an MDS error message, do not use CORAREA,
because an MDS reply or error message returns the correlator sent with the
request. The invoking application supplies the original correlator either in the
MDS-MU or with the SUPCORR keyword.
CORAREA is mutually exclusive with the SUPCORR keyword.
You can specify either the name of the area or a register containing a pointer to
the area.
DATA
Is a varying length character field containing the data being sent. For either
MDSMU or NONMDSMU the first 2 bytes contains the entire length of the
data and the next 2 bytes contain the key. The maximum length of the data is
as defined in the SNA architecture for the data object being sent.
For an MDS-MU, all fields within the MDS-MU header must be properly
prepared before invocation (with the possible exception of the correlator and
the origin NETID and LUNAME). If the correlator is not contained in the data,
you must specify correlarea.
You can specify either the name of the data or a register containing a pointer
to the data.
DATATYP
Is an 8-byte character field indicating whether the data item specified with the
DATA keyword is an MDS-MU or a non-MDS-MU.
MDSMU
Indicates that the DATA keyword is an MDS-MU. MDSMU is the
default.
NONMDSMU
Indicates that the DATA keyword is not a complete MDS-MU because
it does not contain an MDS-MU header. The DSIHSNDS macro
envelopes this data in an MDS-MU header before sending it.
DESTAPP
Is an 8-byte character field that specifies the destination 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
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).
The DSIHSNDS macro truncates any trailing blanks before putting this value
in the MDS-MU header.

Chapter 8. Macros 185

DSIHSNDS

You can specify either the destination high-performance application name or a

register containing a pointer to the high-performance application.
This field is required for NONMDSMU.
DESTLU
Is an 8-byte character field that specifies the LU name of the destination LU.
Specify the 1– to 8–character LU name (padded with blanks to 8 characters)
using only the EBCDIC characters 0–9 and A-Z (capitals only).
The DSIHSNDS macro truncates any trailing blanks before putting this value
in the MDS-MU header.
This field is required for NONMDSMU.
DESTNET
Is an 8-byte character field that specifies the ID of the network of the
destination LU. Specify the 1– to 8–character NETID (padded with blanks to 8
characters) using only the EBCDIC characters 0–9 and A-Z (capitals only).
The DSIHSNDS macro truncates any trailing blanks before putting this value
in the MDS-MU header.
You can specify either the destination NETID name or a register containing a
pointer to the destination NETID.
If you do not specify the DESTNET keyword when using DSIHSNDS for
non-MDS-MU data types, the value of this field defaults to the NETID of the
local NetView program. Otherwise, this field is required for non-MDS-MU data
types.
MUTYPE
Is a 4-byte integer field that specifies the index number that identifies the type
of MDS-MU to build. The type identifies the MDS-MU as a request, a reply, or
an error message, and if 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
The DSIHSNDS macro uses the MUTYPE value to determine the settings for
the MDS message type and first and last message indicator bits in the flags
(X'90') MDS routing information subvector.
This is a required keyword for NONMDSMU.
ORIGAPP
Is 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
MS application programs.
v A 1- to 8-character installation-defined name (padded with blanks). You
must use the EBCDIC characters 0–9 and A-Z (capitals only).

186 Programming: Assembler

 DSIHSNDS

The DSIHSNDS macro truncates any trailing blanks before putting this value
in the MDS-MU header.
You can specify either the origin application name or a register containing a
pointer to the origin application.
This field is required for NONMDSMU.
PRI
Supplies the MQS priority for incoming reply or MDS error message resulting
from any outgoing MDS-MU. It must be the name or address of an 8-byte
(including blanks) character field that contains the preferred priority. Its value,
including blanks, can be:
’LOW ’
’HIGH ’
’NORMAL ’
’TEST ’
REPCMD
Is an 8-byte character field containing the name of the command to be driven
with the reply. You can specify REPCMD only in an application that is sending
REQUEST_WITH_REPLY, with the reply being received asynchronously.
If REPCMD is not specified when a high-performance application sends a
REQUEST_WITH_REPLY, the value defaults to the registered command of the
high-performance application at sending time. If the high-performance
application issues the DSIHREGS macro with the REPLACE(YES) option before
the reply is received, the reply is sent to the original registered command when
it comes in.
You can specify either the reply command processor name or a register
containing a pointer to the reply command processor.
This is an optional field. The default is the registered command for the
invoking application.
SECONDS
Is 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. If you specify a value of
X'FFFFFFFF' (-1), the maximum timeout value is used. The maximum value is
initialized to 86000 (24 hours). You can change these values with the
DEFAULTS command.
The following values are valid for SECONDS:
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 SECONDS keyword when using the DSIHSNDS
macro for a REQUEST_WITH_REPLY, the default timeout value is used.
Otherwise, this field is required for REQUEST_WITH_REPLY.
The parameter specified by SECONDS is either the variable name (timeout)
containing the time interval value, or the value itself.

Chapter 8. Macros 187

DSIHSNDS

SUPCORR
Is a varying length character field containing a complete unit of work
correlator (X'1549') GDS variable. The SUPCORR 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.
SUPCORR is not valid for an MDS-MU. If you use an existing unit of work or
create a new one, the MDS header contains the unit of work and the MDS-MU
must be ready to be transmitted as supplied. An MNOTE is returned if you
specify this keyword for an MDS-MU.
SUPCORR is optional for NONMDSMU. For NONMDSMU, specify either
SUPCORR or CORAREA. The supplied value is used to build the MDS header
if you specify SUPCORR. No validity checking is done for a correlator
supplied by the caller. If an MDS reply or an MDS error message is sent, you
must specify SUPCORR because an MDS reply or error message returns the
correlator sent with the request. The invoking application supplies the original
correlator either in the MDS-MU or with the SUPCORR keyword.
You can specify the correlator name or a register containing a pointer to the
data.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).
SYNCH
Specifies the buffering options available on requests_with_replies:
NO_BUF
Specifies to buffer replies until reply_last is received. This is the
default.
NO_UNBUF
Specifies to send each reply to the application as it is received.

Note:
1. Control is returned to the invoking program after DSIHSNDS successfully
queues the request to the high-performance transport.
2. For MDSMU, all fields within the MDS-MU header must be correct except for
origin NETID and LUNAME. The macro can determine and set these fields. If
the data does not contain the correlator, you must specify CORAREA.
3. For REPLY_ONLY, REPLY_NOTLAST, REPLY_LAST, and ERROR_MESSAGE,
you must specify SUPCORR to return the correlator sent with the request.
4. The high-performance transport implements a timeout value for the application
receiving the data. If the invocation of DSIHSNDS 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.
5. A request can time out in less than the specified interval if the receiving partner
has implemented a maximum timeout value of less than 24 hours, or the one
specified with the DEFAULTS command.
6. When VTAM is active, you can use DSIHSNDS to send data to another
application in the same domain.
7. If DESTNET is not the NETID determined by VTAM for the LU specified in
DESTLU, the send fails.
8. A high-performance application cannot send data to itself within the same
NetView program.

188 Programming: Assembler

 DSIHSNDS

Return Codes in Register 15

The following return codes for the DSIHSNDS macro are found in register 15:
0 Requested function was performed.
4 Task is terminating (TVBABEND/TVBLOGOF is on), and a
REQUEST_WITH_REPLY is sent.
24 No storage.
44 Send MU service is called in an asynchronous exit.
56 Timeout value is not valid.
88 MDS-MU length is not valid.
220 DSIHPDST task inactive.
400 Data type is not valid.
404 DATA missing or is not valid.
408 High-performance application cannot send data to the same
high-performance application within the same NetView program.
416 MS application not registered.
424 UOW missing or is not valid.
444 Destination network ID is missing or is not valid.
448 Destination LU name missing or is not valid.
452 Destination application name (DAN) missing or is not valid.
460 Reply is not valid.
464 Incorrect MUTYPE given.
472 User list is full.
556 Task does not have authorization to run the registered command associated
with the origin application name (OAN). Make sure that the task has
command authorization for the command that is specified on the
COMMAND operand of the DSIHREGS macro.
588 MDS error message does not have SNA condition report.
596 NETID is not available. The probable cause is that VTAM is not active.
1000 + x
The variable x is the return code from DSIMQS.
4000 + x
The variable x is the return code from DSIPUSH.
A return code of 24 or 28 from DSIPUSH indicates that DSIOLGFP is not
defined or is not defined properly in CNMCMD or its included members.
9000 + y
Reply command is not valid.
The variable Y is the return code from DSICES. Ensure that DSI6SNDP is
defined correctly in CNMCMD or its included members. If you specify a
reply command processor, ensure that it is also defined properly in
CNMCMD. If the sending application is an operations management served
application, make sure DSIOARCP is defined properly in CNMCMD.

Chapter 8. Macros 189

DSIID

DSIID: Store SYSMOD Level in CSECT

You can use the DSIID macro to store the SYSMOD level in an assembler module.
The DSIID macro expects the &SYSPARM field to be 8 characters or less and
contain the SYSMOD level. The DISPMOD command can be used to display the
module compile date and SYSMOD level.

The following format is the syntax for the DSIID macro:

DSIID

►► DSIID ►◄
label ONLYDC

Where:
ONLYDC
Specifies that only the DC statement is generated. If the ONLYDC keyword is
not specified, the code to branch around the DC statement is generated.

At the beginning of the CSECT, code the DSIID macro as follows to use DISPMOD
to display the information:
B MODENTRY
DC CL8’DSIMOD ’,C’-’
DC CL8’&SYSDATE’
DC CL8’&SYSTIME’
DSIID ONLYDC
MODENTRY DS 0H

DSIKVS: Keyword/Value Services

You can use the DSIKVS macro in a command processor to determine whether an
operator is authorized to use a given keyword or keyword and value pair.

The return code shown in register 15 indicates whether the operator who issued
the command has been authorized to issue it with the particular keyword, value,
or both.

MVT addressability is required.

The following format is the syntax for the DSIKVS macro:

DSIKVS

►► DSIKVS SWB = ( register ) ►

label symbolic_name

► , CMD = ( register ) , KEYWORD = ( register ) ►

symbolic_name symbolic_name
, SCTADDR = ( register )
symbolic_name

► ►◄
, VALUE = ( register )
symbolic_name

190 Programming: Assembler

 DSIKVS

Where:
CMD
Is the register containing the address of an 8-byte field with the command
name left-aligned and padded with blanks, or symbolic name of that field.
KEYWORD
Is the register containing the address of an 8-byte field, or the symbolic name
of an 8-byte field, that contains the keyword, left-aligned and padded with
blanks.
SCTADDR
Is the register, or symbolic name of a fullword area, containing the address of
the SCT entry for the command that is to be checked.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).
VALUE
Is the register containing the address of an 8-byte field, or the symbolic name
of an 8-byte field that contains a value, left-aligned and padded with blanks.
Specify VALUE when you want to check the value of a keyword.

Return Codes in Register 15

The following return codes for the DSIKVS macro are found in register 15:
0 The specified keyword and value, if given, are valid for the operator.
4 The operator is not authorized to use the keyword.
8 The specified value is not authorized for this operator.
12 A required parameter is missing, or a parameter specified in DSIKVS is not
valid.
16 Working storage is not obtained. No storage is available.
20 The operator is not authorized to use this keyword or this keyword and
value combination. This is issued when a command authorization table or
an SAF product is being used for command authorization.
24 An unexpected return code was received from the security authorization
facility (SAF). Message BNH238E is issued with the SAF return code
inserted.
28 Authorization to issue this 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.
32 Authorization to issue this 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.
36 Authorization to issue this keyword or keyword and value combination is
not granted because the NetView internal security information containing
the source ID of the command is not found. Message BNH277E is issued
identifying the command being checked.
40 Authorization to issue this keyword or keyword and value combination is

Chapter 8. Macros 191

DSIKVS

not granted because the source ID is blank in the NetView internal security
information. Message BNH277E is issued identifying the command being
checked.

Note: If both KEYWORD and VALUE are specified, the combination is checked.
Return code 20 indicates a failure of the combination.

DSILCS: Obtain/Release Control Blocks

The DSILCS macro performs one of the following actions:
v Obtains a service work block (SWB) for the caller and places the address of that
SWB in a fullword area specified by the CBADDR parameter
v Releases an SWB
v Obtains a command work block (CWB) for the caller and places the address of
that CWB in a fullword area specified by the CBADDR operand
v Releases a CWB
v Locates a task vector block (TVB) by operator identification or by LU name
v Locates, from a specified starting position, the next active TVB for a
NetView-NetView task (NNT), a hardcopy task (HCT), an operator station task
(OST), or an optional task
v Locates a TVB for an operator designated as a receiver of authorization
messages by the AUTH statement of a profile definition

Main vector table (MVT) addressability is required.

The following format is the syntax for the DSILCS macro:

DSILCS

►► DSILCS CBADDR = ( register ) ►

label symbolic_name

, LOC = RES
► , CWB = GET ►◄
FREE , LOC = ANY
, SWB = GET BELOW
FREE RES
TEST
, TVB = ( register ) , LU = ( register )
symbolic_name symbolic_name
, OPID = ( register )
symbolic_name
, NEXT = OST
HCT
NNT
OPT
PPT
, AUTHRCV = NO

, AUTHRCV = NO
YES

Where:

192 Programming: Assembler

 DSILCS

AUTHRCV
Specifies that the routine is to search for the first TVB to locate an operator
authorized to receive messages related to successful and unsuccessful logons
and lost station messages. AUTHRCV can be explicitly set to NO (the default)
only when SWB, CWB, or TVB are also specified.
CBADDR
For the GET and TVB options, this is a register containing the address of a
user-provided fullword area on a fullword boundary, or symbolic name of that
area. The specified SWB, CWB, or TVB address is returned to this area.
DSILCS gets global storage (non-queued) for CWB or SWB by issuing a
DSIGET with the Q=NO option.
For the FREE option, CBADDR contains the control block address as either a
register that contains the address, or a symbolic name of the control block.
CWB
Specifies the type of operation to be performed on the CWB.
FREE
Specifies that the caller wishes to release the CWB whose address is found
in the area specified by the CBADDR operand.
GET
Specifies that the caller needs a CWB. The address of the CWB is returned
to the area specified by the CBADDR operand. Before you request NetView
services, initialize the CWBTIB field with the address of your TIB.
LOC
Used with CWB=GET or SWB=GET, determines the residency of the work
block you are requesting.
ANY
Obtains a work block anywhere in storage.
BELOW
Obtains a work block below 16 MB.
RES
Obtains a work block in storage consistent with the residency of the caller.
This is the default.
TEST
The caller of DSILCS sets the high-order bit of register 15 to indicate the
type of storage preferred. A 0 in the high-order bit means allocate storage
below 16 MB, and a 1 means allocate storage anywhere.
LU Used with TVB, is the register containing the address of an 8-byte LU name
field, or symbolic name of that field. This name locates a TVB with a matching
LU name.
NEXT
Used with TVB, specifies the TVB to be located for the next task.
HCT
Specifies that the TVB associated with the next active hardcopy task is to
be located.
NNT
Specifies that the TVB associated with the next active cross-domain task is
to be located.

Chapter 8. Macros 193

DSILCS

OPT
Specifies that the TVB associated with the next optional task is to be
located.
OST
Specifies that the TVB associated with the next active operator station task
is to be located.
PPT
Specifies that the TVB associated with the next active primary program
operator interface task is to be located.
OPID
Used with TVB, is the register containing the address of an 8-byte operator
identification field, or symbolic name of that field. This name locates a TVB
with a matching operator identification.
SWB
Specifies the type of operation to be performed on the SWB.
FREE
Specifies that the caller wishes to release the SWB whose address is found
in the area specified by the CBADDR operand.
GET
Specifies that the caller needs an SWB. The address of an SWB is returned
to the area specified by the CBADDR operand. Before you request NetView
services, initialize the SWBTIB field with the address of your TIB.
TVB
Is the register containing the address of the TVB where the routine begins the
search. The routine searches for the TVB specified by LU, OPID, or NEXT, or
by the symbolic name of an area containing the address of this TVB.
TVB must be used with LU, OPID, or NEXT; and TVB must not be used with
SWB, CWB, or AUTHRCV=YES.
The address of the beginning of this TVB chain is found in the MVTTVB. The
TVB address that is found is placed in the area specified by CBADDR after the
routine has completed processing.

Return Codes in Register 15

The following return codes for the DSILCS macro are found in register 15:
0 The function was successful. The address was returned, or the control
block was released.
4 No active TVBs of the type specified were found.
8 If TVB was specified, the end of the TVB chain was reached, or an OPID
provided is not valid.
If SWB=GET or CWB=GET was specified, no storage was available.
If SWB=FREE or CWB=FREE was specified, a defective control block was
detected.
12 Incorrect parameters were passed to DSILCS.

Note:
1. When a GET request is made, the NetView program reuses an existing free
CWB or SWB rather than issuing a GETMAIN. Even if the user specifies

194 Programming: Assembler

 DSILCS

LOC=RES from a command processor above the line, if the only free control
blocks are below the line, the NetView program uses those control blocks.
2. The routine searches the address once to the end of the TVB chain. It does not
loop to the beginning of the TVB chain.
For more information about the AUTH statement and unsolicited message routing,
refer to the IBM Tivoli NetView for z/OS Administration Reference.

DSILOD: Load User-Defined Module

The DSILOD macro loads a user-defined module. You specify the name of the
module to be loaded.

The following format is the syntax for the DSILOD macro:

DSILOD

►► DSILOD EP = modulename ►
label EPLOC = ( register )
symbolic_name

► ►◄
, DCB = ( register )
symbolic_name

Where:
DCB
Is the register, or symbolic name of an area, containing the address of the data
control block (DCB) for a partitioned data set to be searched for the module.
The DCB must reside above 16 MB.
EP Specifies the name of the module to be loaded.
EPLOC
Is the register, or symbolic name of an 8-byte field, containing the modulename
to be loaded. The modulename is left-aligned and padded with blanks.

Return Codes in Register 15

The following return codes for the DSILOD macro are found in register 15:
0 The module has been loaded.
Nonzero
The module has not been loaded. Refer to your operating system macro
reference for information about system macro return codes.

Note:
1. You must specify EP or EPLOC, but not both.
2. If the module is successfully loaded, register 0 contains the load-point address
of the module. Register 1 contains the authority code in the high-order byte
and the module length in doublewords in the low-order 3 bytes.
3. If the module has not been loaded, register 15 contains the return code
returned by the system load facility. Register 1 contains the abend code and
register 0 contains the reason code for the abend.
4. The module is loaded in virtual storage consistent with the linkage editor
attribute RMODE.

Chapter 8. Macros 195

DSILOD

5. If AMODE=31, the module is called in 31-bit mode; otherwise it is called in

24-bit mode.

DSIMBS: Message Build Services

The DSIMBS macro puts variable text combined with message text into a buffer
that you provide. DSIMBS can determine the size of the buffer required to
accommodate the message.

You can supply variable fields to be inserted into NetView messages or unique
messages of your own with up to nine varying positional fields.

MVT addressability is required.

The following format is the syntax for the DSIMBS macro:

DSIMBS

►► DSIMBS SWB = ( register ) ►

label symbolic_name

► , MID = nnn PosFields ►

( register )
symbolic_name
* equate_name
, MSGA = ( pdb1addr , pdb2addr )

► , BFR = ( register ) ►
symbolic_name
, MSGSIZE = ( register )
symbolic_name

► ►◄
, MSGTBL = ( register )
symbolic_name , OPT = CONCAT

PosFields:

.
▼
, P n = ( text , length )
, padlng , side , fill

Where:
BFR
Is the register, or symbolic name of a fullword area, containing the address of
the buffer in which the edited message is to be returned. BFR must have an
initialized BUFHDR. The DSIMBS macro initializes the HDRMLENG,
HDRDOMID, and HDRTSTMP fields.
MID
Identifies the message to be edited for the user. You can specify the message:
v By the message number (nnn)
v In a register
v In a user area specified by a symbolic name

196 Programming: Assembler

 DSIMBS

v By the equate name preceded by an asterisk (*)

For example, for MSG999 EQU 999, specify MID=*MSG999.
MSGA
Specifies the registers used for variable field substitution in message texts:
pdb1addr
The address of the parse descriptor block (DSIPDB) or the symbolic name
of a fullword area with the address of the PDB. This address contains the
addresses and lengths of the variable fields to be substituted into the
message text.
pdb2addr
The address of the PDB or the symbolic name of a fullword area with the
address of the PDB. The message skeleton to be edited is located at this
address. This is not a NetView message; you supply the message.
MSGSIZE
Is the register containing the address of a user-provided fullword area, or
symbolic name of that area. Use MSGSIZE only to request the service routine
for determining the size of the buffer needed for the message to be edited.
When the routine completes processing, the required size is returned in this
area.
MSGTBL
Is the register, or symbolic name of a fullword, containing the address of a
user-defined NetView message definition module. Use the DSIMDS macro to
generate this table.
OPT
Specifies that the NetView program is to search DSIMDM for a specified
message identifier that cannot be found in the specified user-defined NetView
message definition module. If you omit OPT=CONCAT, the NetView program
searches only the user-defined NetView message definition module for the
message identifier.
Pn Used only in combination with the MID operand, specifies the positional fields
in a message that are to be replaced by user-supplied text. n is a number from
1 to 9. You must specify the first two values, text and length; the others are
optional.
fill
Is the fill character for the area to be padded. The default fill character is a
blank (X'40').
length
Is the length of the variable text to be substituted into the edited message.
The maximum length is 255 characters, specified in character format. It can
be a binary value in a register or in a user area specified by a symbolic
name. The user area must be a 4-byte fullword.
padlng
Is the length of the variable field to be padded with fill characters. This
length must be equal to or less than the length specified by the lngth
operand. The maximum length is 255 characters, specified in character
format. It can be a binary value in a register or in a user area specified by
a symbolic name. The user area must be a 4-byte fullword.

Chapter 8. Macros 197

DSIMBS

side
Specifies whether the fill characters are added to the left or right of the
data in the field. You can specify this value as L, for left-fill, or R, for
right-fill. The default is R.
text
Is the address of the variable text or the symbolic name of the area with
the text to be substituted into the edited message.
SWB
Is the register or symbolic name of a fullword area containing the address of a
service work block (DSISWB).

Return Codes in Register 15

The following return codes for the DSIMBS macro are found in register 15:
0 The function was successful. The edited message is in the provided buffer
and the length of the message is stored in the message length field of the
buffer header; or the size of the message buffer required has been
calculated and stored in the area specified by MSGSIZE.
4 The edited message is in the provided buffer, but the message skeleton
contained a parameter for which the caller did not supply text. The
message contains the characters &n where n can be any value 1–9.
8 Unsuccessful. The buffer overflowed, and the message has been truncated.
The size of the truncated message has been stored in the message length
field of the buffer header.
12 The message number specified is not found in the NetView or
user-specified NetView message definition module. Message 000I is edited
in the caller's buffer. If only the buffer size is requested, the size of
message 000I is returned.
16 The caller did not supply a buffer address.
20 Combined conditions 4 and 8 occurred.
24 Combined conditions 8 and 12 occurred.
28 A validity check failed on the user message definition module. The address
passed in the MSGTBL operand does not point to a message definition
module that was created with the DSIMDS macro.
32 The storage request failed.
36 I/O error.
40 Unexpected end of file found.

Note:
1. Because the variable field information is contained in pdb1addr, you cannot use
the P1...P9 operands with MSGA.
2. MID and MSGA are mutually exclusive.
3. BFR and MSGSIZE are mutually exclusive.

DSIMDS: Message Definition Services

The DSIMDS macro generates a message definition module to be used by the
DSIMBS macro to display messages in installation exits, command processors, and
subtasks.

198 Programming: Assembler

 DSIMDS

After you have coded a message definition module, you must assemble it and
link-edit it into a NetView load library. DSIMDS has no return codes.

DSIMVT addressability is not required.

Three forms of DSIMDS are required to generate a message definition module. The
following three formats describe these forms:
Format 1: Start Message Definition Module Statement
Format 2: Define Individual Messages Statement
Format 3: End Message Definition Statement

Each format must be coded in the sequence shown.

Format 1: Start Message Definition Module Statement

The syntax for the start message definition module statement follows:

DSIMDS

►► DSIMDS prefix , TYPE = START ►

label

, SEARCH = T , MAXLEN = 142

► ►◄
, SEARCH = B , MAXLEN = 71
D 142
T 213

Where:
MAXLEN
Defines the maximum message length. MAXLEN is determined by calculating
the length of pppxxxt msgtext (message number, type, a blank, and text).
MAXLEN is a multiple of 71. The valid maximum message size is 213
characters. If you do not specify MAXLEN, the message size defaults to 142
characters.
prefix
Is the required positional parameter that becomes the 3-character prefix for the
messages in the module. The prefix cannot conflict with the NetView message
prefixes:
AAU BNT EGV EZL FLB
BNH CNM EKG FKB FLC
BNI DSI EUY FKV FMG
BNJ DUI EXQ FKW FNA
BNK DWO EYV FKX IHS
SEARCH
Indicates where the messages can be found: in the message definition module,
on disk, or both. SEARCH causes a message definition module to be built. This
indicator becomes part of the message definition table.
B Indicates that some of the messages can be found in the message definition
module, and the others can be found on disk. Code individual message
statements using Format 2 of DSIMDS only for those messages that are not
defined on disk. See “Defining Messages on Disk” on page 201.

Chapter 8. Macros 199

DSIMDS

D Indicates that the messages can be found only on disk. Do not code
individual message statements using Format 2 of DSIMDS for the
messages. The individual messages are coded on disk. See “Defining
Messages on Disk” on page 201.
T Indicates that the messages can be found only in the message definition
module. T is the default.
TYPE
Specifies the beginning of generation for the message definition module.

Format 2: Define Individual Messages Statement

The syntax for the define individual messages statement follows:

DSIMDS

►► label DSIMDS xxx , ' message_text ' , TYPE = A ►◄

&& n I
D
E
W

Where:
label
Is an optional label.
message text
Is the text of the message added or changed.
&&n
Is a variable field for text insertion. The positional fields are specified by the
Pn parameter in the DSIMBS macro. You can specify &&1–&&9.
TYPE
Specifies the message type.
A Specifies an action message, one for which appropriate action must be
taken.
I Specifies that the message is for information only. No specific action is
required.
D Specifies that the action requires a choice or alternative.
E Specifies that the message indicates an error has occurred.
W Specifies that the message is a warning.
xxx
Is the message number. It can be any number 000-999. When DSIMBS is issued
to build the message, it creates the message identifier by concatenating your
3-character prefix, the message number, and the type.
When coding your message CSECT, code a message 000 statement to be issued
when an incorrect message number is specified. Message 000 has one insert
(&&1), which contains the incorrect message number. Use wording similar to
the NetView message DSI000I:
MSG000 DSIMDS 000,’MESSAGE &&1 ISSUED BUT DOES NOT EXIST IN
MESSAGE TABLE DSIMDM - CALL IGNORED’, TYPE=I

200 Programming: Assembler

 DSIMDS

Replace DSIMDM with the name of your NetView message definition module;
that is, the name specified on the DSIMDS TYPE=START statement. The
DSIMBS service routine substitutes the message number of the incorrect
message in place of &&1.

Note: When coding, be sure that the buffer passed to DSIMBS is large enough
to hold the message with all the inserts substituted. Otherwise, the message is
truncated.

Format 3: End Message Definition Statement

The syntax for the end message definition statement follows:

DSIMDS (example 2)

►► DSIMDS TYPE = END ►◄

label

Where:
TYPE
Specifies the end of the message definition module. This is the last statement
specified.
The TYPE=END statement is followed by an assembler END statement.

Defining Messages on Disk

Messages can be defined on disk instead of, or in addition to, defining them in the
message definition module. The following list shows the benefits of defining
messages on disk:
v The message coding is simpler and does not require assembling and link-editing
the message definition module when messages are added or changed.
v The NetView program reads in the messages when the DSIMBS macro is issued.
Messages can be changed while the NetView program is running, and the
changes take effect immediately.

Messages are coded in members in NetView DSIMSG data sets. The member
names are in the format of DSIpppxx, where:
ppp Is the message prefix that was defined on the DSIMDS start message
definition module statement.
xx Is the first 2 digits of the 3-digit message number. Within this member, you
can define up to 10 messages by incrementing the third digit of the
message 0-9 (xx0–xx9).

The syntax for the user messages follows:

DSIMDS (example 3)

►► xxxt message_text ►◄
& n

Where:

Chapter 8. Macros 201

DSIMDS

message text
Is the text of the message added or changed. To continue a message on a
second line, type an asterisk in column 72. See “User Message Definition
Module Examples” for an example.
&n Is an operand for optional information. The positional fields are specified by
the Pn parameter in the DSIMBS macro. You can specify &1–&9.
t Is the message type:
A Specifies an action message, one for which appropriate action must be
taken.
I Specifies that the message is only for information. No specific action is
required.
xxx
Is the message number. It can be any number 001–999.

Note: Messages issued from code running with TVBINXIT on cannot be read from
disk. You must define these messages in your message definition module with
Format 2 DSIMDS statements.

User Message Definition Module Examples

The following two examples define five user messages (USR001–USR005).

This example defines message USR001, which resides in a message definition

module called USRTABLE:
USRTABLE DSIMDS USR,TYPE=START,SEARCH=B
MSG000 DSIMDS 000,’USER MESSAGE &&1 ISSUED BUT DOES EXIST IN MESSAGE*
TABLE USRTABLE - CALL IGNORED.’,TYPE=I
MSG001 DSIMDS 001,’THIS IS USER MESSAGE 1’,TYPE=I
DSIMDS TYPE=END
END

The second example defines messages USR002–USR005, which reside in a NetView

DSIMSG data set under the member name DSIUSR00:
002I THIS IS USER MESSAGE 2
003A THIS IS USER MESSAGE 3, RETURN CODE = &1
004I THIS IS USER MESSAGE 4, &1 IS TODAY’S DATE
005I THIS IS USER MESSAGE 5, TIME IS &1

DSIMMDBS: Call DSIMMDB Service

The DSIMMDBS macro is provided to simplify the call to the DSIMMDB assembly
language called service routine. For an example of usage, see “Process Message
Data Block Routine (DSIMMDB)” on page 268.

DSIMQS: Message Queuing Services

The DSIMQS macro sends a user-supplied message or command to the message
queue of a task vector block (DSITVB).

This message or command is displayed on the operator's screen or hardcopy log,

depending upon which identification is specified. Buffers that are formatted as
internal function requests (IFRs) are not displayed. Instead, they cause the
receiving subtask to take the action requested by the IFR. Buffers that are
formatted as IFRs are not sent to the authorized receiver (see the description for

202 Programming: Assembler

 DSIMQS

the AUTHRCV operand). An IFR must have a BUFHDR extension regardless of the
BFRFLG value specified on the DSIMQS. The HDRTDISP in the BUFHDR must be
X'24'.

When DSIMQS is used to queue a command, the operator ID of the command

issuer (source) is queued along with the command. If DSIMQS is called from
within an installation exit, the SOURCEID is the identity of the task under which
the installation exit is running. If DSIMQS is called in a command processor, the
SOURCEID is the identity (TVBOPID) of the task that originated the command or
the existing SOURCEID at the time the command was issued.

DSIMVT addressability is required.

The following format is the syntax for the DSIMQS macro:

DSIMQS

►► DSIMQS SWB = ( register ) ►

label symbolic_name

► , BFR = ( register ) ►
symbolic_name

, BFRFLG = NO
► , TASKID = ( register ) ►
symbolic_name , BFRFLG = NO
PPT YES
, AUTHRCV = NO

, AUTHRCV = NO
YES
, LIST = ( register )
symbolic_name
Except

, STGACCT = TEST , PRI = NORMAL

► ►
, STGACCT = TEST , PRI = HIGH
YES LOW
NORMAL
TEST
( register )
symbolic_name

, CORR = NONE
► ►◄
, CORR = CMD
NONE

Except

, EXCEPT = ( pointer )
symbolic_name

Where:

Chapter 8. Macros 203

DSIMQS

AUTHRCV
Specifies that the first operator designated as the receiver of authorized
messages (by the AUTH statement of the profile definition) is to receive the
message. All messages sent to the authorized receiver are routed first to the
PPT to test for automation and message routing (using the ASSIGN command).
If not suppressed by automation or handled by routing, the messages are sent
to the authorized receiver, if one is logged on, or to the system console.
The AUTHRCV option is mutually exclusive from LIST and TASKID.
The AUTHRCV option is used only for messages. If the buffer to be sent is
formatted as an internal function request (DSIIFR) and it is not an automation
IFR containing a message, the DSIMQS macro fails with a return code 4
(incorrect buffer format) in register 15. NO is the default for this operand.
BFR
Is the register, or symbolic name of a fullword area, containing the address of a
buffer. (If DSIGET obtained this buffer, DSIFRE frees it after use. Use the same
option for the Q parameter for both DSIGET and DSIFRE.) BFR requires an
initialized BUFHDR.
BFRFLG
Specifies whether the subtask that sends the buffer has released control and
responsibility for it (BFRFLG=YES). With BFRFLG=YES, the buffer must
include HDRMCEXT with HDRSENDR initialized. BFRFLG=NO indicates that
the buffer is returned to the issuer of DSIMQS. The issuer must dispose of the
buffer.
When using DSIMQS BFRFLG=YES, consider the following items:
v Obtain all storage using DSIGET,Q=NO,SUBPOOL=0.
v Do not use addresses of non-buffered data that are freed by other tasks in
buffers. This practice causes inaccurate storage accounting.
For assembler programs containing addresses of data, specify
MAINTSK=YES on the DSIGET request for the data pointed to by the
buffers. For the buffers, do not specify MAINTSK=YES on DSIGET. Send
only data contained in the buffer using DSIMQS BFRFLG=YES.
DSIGET MAINTSK=YES is intended to keep storage accounting accurate
where normal storage management cannot be used, for example, when
DSIGET is used to obtain storage in one task, free the same storage using
DSIFRE in another task, and not transfer the buffer using DSIMQS.
v Use the Automation Internal Function Request (AIFR) buffer structure,
IFRAUTO in DSIIFR, to send multiple buffers. All buffers in an AIFR must
be separately obtained using DSIGET,Q=NO,SUBPOOL=0. For more
information about DSIIFR, see “DSIIFR: Internal Function Request” on page
120.
v When using DSIMQS BFRFLG=YES, specify STGACCT=YES if at all
possible.
CORR
When CORR=NONE is coded, no correlation is provided for the buffer being
sent. NONE is the default.
When CORR=CMD is coded, the data being sent is treated as a command by
the receiving task. Any output (for example, DSIPSS TYPE=OUTPUT) from
that command is returned to the environment from which the message
queuing service (MQS) is issued. There are two environments:

204 Programming: Assembler

 DSIMQS

1. If the MQS occurred within a pipeline (within a command running under

the NetView stage), the pipeline is the environment. The output (from the
other task) is introduced into the pipeline through CORRWAIT.
2. If not in a pipeline, then the environment is the task from which the MQS
was issued.
Under DST, execution of DSRB-based functions DSIZCSMS and DSIZVSMS
preserves environment information. Output produced from the command that
is notified of completion of a DSIZCSMS or DSIZVSMS function is processed
using the same rules as the command that issued the DSIZCSMS or
DSIZVSMS.
Example Scenario 1:
OPER1 runs CMD1 outside of a pipeline. CMD1 sends (MQS CORR=CMD)
another command, CMD2, to another task such as DST1. CMD2 then issues a
message through DSIPSS TYPE=OUTPUT. This output is displayed at OPER1.
Example Scenario 2:
Using the same commands as in Example Scenario 1, OPER1 issues (from
within a command list):
PIPE NETVIEW CMD1 | CORRWAIT 10 | TAKE 2 | STEM THEDATA
The first two outputs from CMD2 are found in the stem variables. Any further
output from CMD2 is discarded.
EXCEPT
Specifies an 8-character field that contains an operator or group ID, left-aligned
and padded with blanks, that does not receive the message. You can specify
this operand only if you specify LIST.
LIST
Is the pointer to, or symbolic name of, a fullword area containing the address
of a list of operator IDs or group IDs to receive the message. Operators are
assigned to groups using the ASSIGN command. Refer to the NetView online
help for more information about the ASSIGN command.
The LIST option is mutually exclusive from AUTHRCV and TASKID. For this
operand:
v If you specify 1ST as the LIST type, the first logged-on operator in the list
receives the message. (The first logged-on operator can be in a group.) The
receiving operator ID is returned in the MQSENTTO field in the SWB.
v If you specify ALL as the LIST type, and a return code of 0 is received, the
message is sent to all specified operators and groups of operators in the list
who are logged on. While the message is sent to all specified logged-on
operators, it is not necessarily received.
v If you specify multiple operator or group IDs, the last two fields (shown in
the following ID list) must be repeated for each operator or group listed.
The following ID list contains hexadecimal offsets:
0 1ST or ALL (3 bytes)
3 Number of IDs in list (1 byte)
4 Unused (8 bytes)
C Operator or group ID (8 bytes)
See “Return Codes in Register 0” on page 206 for the return codes in register 0
when the LIST option is specified.

Chapter 8. Macros 205

DSIMQS

PRI
Specifies a priority for message processing by the destination task. The value is
one of the four strings HIGH, NORMAL, LOW, OR TEST, or a register or name
of a fullword area containing one of the values defined in DSISWB: MQSHI,
MQSNORM, MQSLO, or MQSTEST. The default value is NORMAL. A message
or command sent at HIGH priority begins processing after any normal
message currently in progress, but before other queued NORMAL messages. A
message or command sent at NORMAL priority similarly pre-empts a queue of
LOW priority messages. When you specify TEST, DSIMQS queues the message
at either high or low priority according to the destination task's command
priority. Refer to the OVERRIDE command in the NetView online help for an
explanation of command priorities.
Any command that is currently running can be interrupted at that point in
processing where control is returned to NetView. For example:
v A running command processor is not interrupted. The newly queued
command (no matter which priority queue) runs when the command
processor returns to the command facility after issuing a DSIPUSH macro (if
the command is a compound command processor) or when the processor
finishes.
v A running command list (REXX or command list language) can be
interrupted under several conditions. For example, an interruption can occur
just after a command list begins processing and is scheduled by the NetView
program but is not yet running. Other examples are when a command list
issues a command or performs an &WAIT or WAIT.
Of the tasks supplied with the NetView product, only destination task types
OST, PPT, and NNT recognize priority. For destination tasks that do not
indicate support for multiple priorities, DSIMQS automatically converts all
messages to NORMAL priority.
STGACCT
Specifies whether the storage specified by BFR was obtained using DSIGET.
STGACCT is only valid when BFRFLG=YES.
YES
Indicates that the storage specified by BFR was obtained using DSIGET.
TEST
Indicates that the origin of the storage specified by BFR is unknown.
Specify STGACCT=TEST when you cannot determine if the buffers were
obtained using DSIGET. TEST is the default.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).
TASKID
Is the register containing the address of a user-provided 8-byte area, or
symbolic name of that area, or PPT for the primary POI task. The area contains
the 8-character operator identification (TVBOPID) of the task for which the
message is to be queued.
The TASKID option is mutually exclusive from AUTHRCV and LIST.

Return Codes in Register 0

The following return codes for the DSIMQS macro can appear in register 0 if the
LIST option is used:

206 Programming: Assembler

 DSIMQS

0 At least one operator was active and all active operators received the
buffer.
12 The attempt to obtain buffer storage failed and one or more active
operators did not receive the buffer.
23 The message was routed to the first 255 active operators or groups, or
both, in the list.
26 One or more tasks in the list do not support MQS with Receipt buffer. The
buffer has been sent to all tasks in the list capable of receiving it.

Return Codes in Register 15

The following return codes for the DSIMQS macro are found in register 15:
0 The function was successful; the message is queued.
4 The buffer length was either:
v Not greater than 0
v Less than the combined length of HDRBLEN plus HDRTDISP
v Greater than 32000
8 The operator ID designated as the receiver of authorized messages was not
found.
12 A buffer was could not be obtained or dynamic resource control failed.
16 The NetView program is terminating; the external request cannot be
completed.
20 The SWB address is not valid.
22 The list specified with the LIST option contained no operator IDs. It
contained only unassigned group IDs.
23 Messages were routed to the first 255 operators or groups, or both.
24 The value specified for priority was not valid.
26 The internal function request for the command to be run contains the
IFRAUTBC or IFRAUTBN fields. The task that receives this command has
no MQS receipt support and cannot process these fields.
28 A message stack inquiry failed.
32 NetView program internal error.

Note: When a command procedure written in REXX or NetView command list

language is running, NetView services all message queues, except the low-priority
queue, at three points:
v Initially, before the first instruction
v After the execution of any NetView command
v Throughout the period of any wait state (for &WAIT, &PAUSE, or WAIT)

Because of this, two command lists queued at the same time to the high- or
normal-priority queues appear to run in reverse order. The first one is initiated,
then before it runs its first instruction, it is preempted, and the second command
runs. To have command lists run in the order queued, always queue them at low
priority.
For more information about the AUTH statement and unsolicited message routing,
refer to the IBM Tivoli NetView for z/OS Administration Reference.

Chapter 8. Macros 207

DSINOR

DSINOR: Resource Object Data Manager

The DSINOR service routine enables interaction with a specified resource object
data manager (RODM). All RODM application programming interface (API)
functions are supported through this interface, including querying for data,
changing data, and triggering methods.

The following format is the syntax for the DSINOR macro:

DSINOR

►► DSINOR ACB = ( register ) ►

label symbolic_name

► , TIF = ( register ) , RESP = ( register ) ►

symbolic_name symbolic_name

► , FUNC = ( register ) , SWB = ( register ) ►

symbolic_name symbolic_name

► WAITF ►◄
WAITT

WAITF

, WAITF = N

, WAITF = N
Y

WAITT

, WAITT = ( register )
number

Where:
ACB
Is a RODM access control block following the format of the RODM API.
The access block contains the following fields:
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.
The name is left-aligned and must be padded with blanks (X'40') to 8
characters.
signon_token
Specifies the RODM sign-on token to be used within the call.
DSINOR ignores this field and fills it with the signon token received
by DSIQTSK when it initially connects to the RODM being accessed.
Because DSINOR overrides this field, you can ignore it.

208 Programming: Assembler

 DSINOR

user_appl_id
This field specifies the application name of the caller.
DSINOR 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.
FUNC
Specifies 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.
RESP
Specifies a response block following the format of the RODM API response
block control structure.
SWB
Specifies a register, or the symbolic name of a fullword area, containing the
address of a caller's NetView service work block (SWB) control block.
TIF
Specifies a transaction information block following the format of the RODM
API transaction information block and contains the following fields.
WAITF
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. The following list shows the recognized values:
N Do not wait for checkpoint completion. This is the default.
Y Wait for checkpoint completion.
WAITT
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 called. The expected 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.

Return Codes in Register 15

The following return codes for the DSINOR macro are found in register 15:
0 The function was successful
4 RODM not under control of RODM access and control component
8 DSINOR or DSIGET failure. Internal macro call failure; possible storage
problem.
12 Incorrect parameters received
20 Checkpoint in progress

Note:
1. DSINOR 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.

Chapter 8. Macros 209

DSINOR

Refer to the IBM Tivoli NetView for z/OS Administration Reference for a
description of the DSIQTSKI keywords.
2. For an application that uses DSINOR in a command processor, provide a
keyword (which can be authority-checked) for controlling the level of access to
RODM.
3. An application can connect to RODM with an option specifying that RODM
can truncate its responses if the application's response block is smaller than
RODM's 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 DSINOR from
having to deal with overflow cleanup.
4. DSINOR returns two sets of return codes. The caller can use either set. 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 theIBM Tivoli NetView for z/OS Resource Object Data
Manager and GMFHS Programmer's Guide. This document also contains
information about the function block format, the RODM response block, and a
description of the RODM API transaction information block.
The second set is in register 15 upon return from DSINOR.

DSIPAS: Parameter Alias Services

The DSIPAS macro receives a command parameter as input and searches the
system command table (DSISCT) to determine whether the entered parameter is an
alias for the actual parameter.

If the parameter is an alias, the regular value is returned to a user-provided area. If

it is not an alias, the input value is returned to the user area. If the value is not
valid, blanks are returned to the input area.

DSIMVT addressability is required.

The following format is the syntax for the DSIPAS macro:

DSIPAS

►► DSIPAS SWB = ( register ) ►

label symbolic_name

► , PDB = ( combo ) , OUT = ( register ) ►◄

symbolic_name

Where:
OUT
Is the register containing the address of a user-provided 8-byte area to which
the NetView equivalent of the input operand is returned if found; or the
symbolic name of that user area.
PDB
Specifies two values. One value is the address of a PDB and the other value is
the entry number of the field in the PDB to be examined.
combo
The value for combo can be specified using any of the following forms:

210 Programming: Assembler

 DSIPAS

v pdbname, entname
v pdbname, (entreg)
v pdbname, 'ENTRY'
v (pdbreg), entname
v (pdbreg), (entreg)
v (pdbreg),'ENTRY'
entname
Is the symbolic name of a fullword that contains the entry number,
right-aligned, and padded with binary zero.
entreg
Is the register containing the entry number and padded with binary zero.
ENTRY
Is a constant that specifies the entry number.
pdbname
Is the symbolic name of a fullword that contains the address of the PDB.
pdbreg
Is the register that contains the address of the PDB.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).

Note: PDBCMDA must contain the address or pointer to an entry in the SCT.

Return Codes in Register 15

The following return codes for the DSIPAS macro are found in register 15:
0 A regular operand value was returned.
4 No equivalent was found; the same operand is returned.
8 Incorrect operand; blanks are returned.

DSIPOP: Remove Long-Running Command

The DSIPOP macro removes a long-running command element that DSIPUSH
placed on the stack.

The element canceled is the one nearest the top of the stack with the name
specified in the parameter list. If a calling command procedure is suspended by
DSIPUSH, use DSIPOP to let the command procedure continue at the next
instruction. The command procedure continues when the RESUME routine or
currently running command returns control to the OST or PPT.

Do not use DSIPOP while in a LOGOFF routine, an ABEND reinstate routine, or

an immediate command.

See “DSIFIND: Find Long-Running Command Storage” on page 170 and

“DSIPUSH: Establish Long-Running Command” on page 223 for more information.

DSIMVT addressability is required.

The following format is the syntax for the DSIPOP macro:

Chapter 8. Macros 211

DSIPOP

DSIPOP

►► DSIPOP SWB = ( register ) ►

label symbolic_name

► , LIST = ( register ) ►◄
symbolic_name COMPCDE

COMPCDE

, COMPCDE = ( register )
symbolic_name

Where:
COMPCDE
Specifies the value of the completion code for the long-running command
being removed. You can specify the value as a register, symbolic name of a
fullword area, or a fullword literal. The value is meaningful only if the
long-running command being removed specified a RESUME routine and only
if the process that created the long-running command element (using
DSIPUSH) was directly called from another long-running command. If you do
not specify COMPCDE, the following list shows the default values:
0 If the long-running command being removed is in control on top of the
stack at the time DSIPOP is called. This is the usual case.
-5 If the long-running command being removed is not at the top of the
stack. NetView command procedures and certain related commands
treat negative 5 (-5) as a CANCEL request.
You can be certain that your long-running command is at the top of the stack
when it is resumed.

Note: NetView command procedures are long-running commands. If you have

written a long-running command to be called from a command procedure, you
can pass a return code to it using the COMPCDE keyword. If a long-running
command makes a direct call to schedule a command procedure, you can
obtain its return code upon resumption from CWBRCODE.
LIST
Is the register containing the address of a parameter list used by the service
routine, or symbolic name of that list. Do not specify this as register 1; register
1 contains the SWB address within DSIPOP. Do not put this list in the SWB
that is to be passed to DSIPOP.
The parameter list contains the following fields:
Table 42. LIST parameters for the DSIPOP Command
Hex Offset Length Field
0 4 SWBLRCLN (Length)
4 16 SWBLRCNM (Name)

Where:

212 Programming: Assembler

 DSIPOP

SWBLRCLN
Specifies the parameter list length. Set SWBLRCLN equal to SWBLRCPO
(decimal 20).
SWBLRCNM
Specifies the name of the storage to be dequeued and freed. Specify this
field exactly as you specified it in the corresponding DSIPUSH macro. This
16-byte field is used as is. Instructions for specifying the name field are
under “DSIPUSH: Establish Long-Running Command” on page 223.
SWB
The register, or symbolic name of a fullword area, that contains the address of
a service work block (DSISWB). The TIB address in SWBTIB must be correctly
set.

Return Codes in Register 15

The following return codes for the DSIPOP macro are found in register 15:
0 The function was successful; the long-running command processor element
is dequeued.
16 The request was issued while in an immediate command, or while the
NetView program was in an exit, a LOGOFF, or an ABEND reinstate
routine.
32 Incorrect macro call. Fix assembly errors before trying to run the program.
36 The specified NAME was not found.

DSIPOS: ECB Post Services

The DSIPOS macro indicates the completion of an event by posting an event
control block (ECB).

DSIMVT addressability is required.

The following format is the syntax for the DSIPOS macro:

DSIPOS

►► DSIPOS ecbaddress ►◄
label , compcde

Where:
compcde
Is the value of the completion code to be placed in the ECB (0–16777215) or in
a register (0, 2–12) that contains the value. If you specify a register, code it in
parentheses. If you do not specify a value, 0 is assumed.
ecbaddress
Is the symbolic name of an ECB or register (1–12) that contains the address of
the ECB. If you specify a register, enclose it in parentheses.

Note: These parameters are positional; they must be specified in the indicated
order.

Chapter 8. Macros 213

DSIPRS

DSIPRS: Parsing Services

The DSIPRS macro parses commands using specified or assumed delimiters, or
determines the size of the parse table required to parse the input buffer. DSIPRS
must be issued in pairs. Specify the PDBSIZE in the first issuance, to determine the
parse descriptor block (DSIPDB) length necessary to parse the command. The
second issuance actually passes the command into a buffer long enough to hold
the PDB.

The parse table describes the data contained in the buffer. DSIPRS finds delimiters
in the data and formats the PDB to indicate data segments separated by the
delimiters. You can call DSIPRS again to build the parse table in a user-provided
area.

DSIMVT addressability is required.

The following format is the syntax for the DSIPRS macro:

DSIPRS

►► DSIPRS SWB = ( register ) ►

label symbolic_name

► , BFR = ( register ) , PDBSIZE = ( register ) ►

symbolic_name symbolic_name
, PDB = ( register )
symbolic_name

, FIRST = YES , SUB = NO

► ►◄
, FIRST = NO DELIM , SUB = NO
YES YES

DELIM

, DELIM = ( ▼ ' delimiter ' )

Where:
BFR
Is the register, or symbolic name of a fullword area, containing the address of
the buffer to be used for input. BFR must have an initialized BUFHDR.
DELIM
Used to specify delimiters instead of NetView default values. NetView default
delimiters are blank, comma, period, and equal sign. Blank is always
considered a delimiter, even if you specify your own delimiters.
FIRST
Indicates whether the first word of the input buffer can be delimited only by a
blank (YES) or by any delimiter (NO). YES is the default.

214 Programming: Assembler

 DSIPRS

PDB
Is the register containing the address of a fullword pointing to the area where
the parse table is to be built, or symbolic name of that area. The parse table
must include a user-initialized DSICBH header that contains the control block
identification and length before the data can be parsed. The name of the
constant set to PDBCBH is CBHPDB.
PDBSIZE
Is the register containing the address of a fullword area to which the size of
the parse table is to be returned, or symbolic name of that area.
SUB
Indicates whether all text within single quotation marks is to be parsed as one
element (YES) or not (NO). This option treats everything between single
quotation marks as one element, provided the first quotation mark is preceded
by a delimiter and the last quotation mark is followed by either a blank or
comma. NO is the default.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).

Return Codes in Register 15

The following return codes for the DSIPRS macro are found in register 15:
0 The function was successful. The required size of the table was returned in
PDBSIZE, or the command was parsed and the parse table was built.
4 The input buffer was parsed, but there was no data in the input buffer (0
length data) or the data in the input buffer was all blanks. Only the buffer
address and number of entries (0) are returned in the parse table.
8 The parse table was too small for the input buffer. A partial parse table is
built and the number of entries is set to the number that the parse table
can hold. Increase the size of the parse table.
12 Unbalanced quotation marks. Returned only if SUB=YES is specified.
16 The number of characters between two consecutive delimiters in the input
buffer was greater than 255.
20 An unpaired double-byte character set (DBCS) delimiter of DBCS data
bytes was found in the input buffer. For example, one of the following
conditions might have occurred:
v The end of the input buffer was found before the DBCS data-ending
delimiter shift-in (X'0F').
v A second DBCS data-beginning delimiter shift-out (X'0E') was found
before the DBCS data-ending delimiter shift-in (X'0F').
v An odd number of DBCS data bytes were found between DBCS data
delimiters.
100 No PDB or an incorrect PDB was passed; or no PDBSIZE or an incorrect
PDBSIZE was passed.

Note: You must specify the operands DELIM, FIRST, and SUB, identically, in the
pair of DSIPRS parse commands issued. Otherwise, the second parse can fail or the
storage can be overlaid.

Chapter 8. Macros 215

DSIPRS

Parsing Services Module Examples

In the following examples, DSIPRS is issued to pass the given character string with
the default delimiters and SUB=YES.

Example 1
RETURN CODE IS ’NONZERO’!

DSIPRS returns the UNBALANCED QUOTES return code, if you specify

SUB=YES.

Example 2
RETURN CODE IS ’GOOD’, CONTINUE.

The following PDB table is built:

Table 43. An Example of a PDB Table When SUB=YES in a DSIPRS Command
PDBTYPE PDBLENG PDBDISP TOKEN VALUE
� 6 24 RETURN
� 4 2B CODE
� 2 30 IS
, 4 34 GOOD
. 8 3B CONTINUE

Example 3
RETURN CODE IS (X’00’), CONTINUE.

The following PDB table is built:

Table 44. An Example of a PDB Table When SUB=YES in a DSIPRS Command
PDBTYPE PDBLENG PDBDISP TOKEN VALUE
� 6 24 RETURN
� 4 2B CODE
� 2 30 IS
' 2 33 (X
' 2 36 00
, 1 39 )
. 8 3C CONTINUE

DSIPSS: Presentation Services

The DSIPSS macro writes a message to an operator's screen or sends messages to
another NetView program. The presentation service routines called by DSIPSS
control screen formats, organize data into a specific form for each device, and send
the data.

DSIMVT addressability is required.

The following format is the syntax for the DSIPSS macro:

216 Programming: Assembler

 DSIPSS

DSIPSS

►► DSIPSS SWB = ( register ) ►

label symbolic_name

► , TYPE = OUTPUT ►
, APPLID = ( register ) FLASH
symbolic_name IMMED
XSEND
SCRSIZE
WINDOW
ASYPANEL
CANCEL
PSSWAIT
TESTWAIT

► ►
, ECBLIST = ( register ) , BFR = ( register )
symbolic_name symbolic_name

► ►◄
, SIZE = ( register ) , PANEL = ( register )
symbolic_name symbolic_name

Where:
APPLID
Is the register containing the address of an 8-byte area that contains the name
(left-aligned and padded with blanks) of the application program to which the
data is to be sent, or symbolic name of that 8-byte area. This name is the same
as the name specified on the START command when a session is started.
Specify APPLID only when you specify TYPE=XSEND.
BFR
Is the register, or symbolic name of a fullword area, containing the address of a
user-provided buffer. This buffer contains the data to be processed. Use BFR
only for TYPE=FLASH, TYPE=OUTPUT, TYPE=IMMED, and TYPE=XSEND.
BFR must have an initialized BUFHDR.
ECBLIST
For TYPE=PSSWAIT, this is the register, or symbolic name of a fullword area,
containing the address of an ECB list. An ECB list is a list of addresses of
user-defined ECBs that is copied and combined with another ECB list. The
NetView program waits for this combined list. When one of the events
associated with this list is posted, control is returned to the next sequential
instruction. The input ECB list is made up of fullword ECB addresses. The last
address in the list must have the first bit set on to specify that this is the last
entry.
PANEL
For TYPE=ASYPANEL, a register containing the address of a parameter list, or
the symbolic name of that list. You can use one the following types of
parameter lists:
v Settable PF keys enabled; the NetView program manages the PF keys on the
panel. Use the DSIASYPN macro to create the parameter list. The macro
comments explain how to code your parameters.
v Settable PF keys not enabled; your code manages hardcoded PF keys. Use
the parameters shown in Table 45 on page 218.

Chapter 8. Macros 217

DSIPSS

The parameter list for panels without settable PF keys is formatted as shown in
Table 45.
Table 45. PANEL Parameters for the DSIPSS Command
Bytes (Decimal) Bytes (Hex) Description
0 (0)
4 (4) ECB address
8 (8) Output data stream address
12 (C) User input area address
16 (10) Output length | Input area length
20 (14) Data length address

If you request asynchronous full-screen output, the output data stream address
field contains the address of a 3270 data stream, including a 3270 command,
write control character (WCC), and orders to be written to the terminal. Code
the command using remote EBCDIC values. The output length field indicates
the length, in bytes, of the 3270 data stream (32767 bytes maximum). If output
is requested, the ECB address, input area length, user input area address, and
data length address fields are not used.
To read asynchronous full-screen input from a terminal, the ECB address area
contains the address of an ECB to be posted when the asynchronous input is
received. The user input area address contains the address of a user area into
which the full-screen panel data is read. If the length of the data being read is
greater than the user input area, the data is truncated in that area. The input
area field indicates the length of the input data area in bytes (32767 bytes
maximum). The data length address field contains the address of a halfword
field set to the amount of data read when the ECB is posted.
SIZE
For TYPE=SCRSIZE, this is the register, or symbolic name of a fullword area,
containing the address of a user-provided fullword area to contain the size of
the display screen, in row-column format. For example, a 1920-character screen
is defined as X'00180050', because the screen is 24 rows (X'0018') by 80
characters (X'0050').
For TYPE=WINDOW, this is a register containing the address of a 12-byte area,
or symbolic name of that area. The window size is returned in binary to the
area. The window size is the number of lines available for output on the
screen. The size varies depending on screen size and the number of input lines
specified on the INPUT command. The syntax for the area is:
Table 46. SIZE Parameters of the DSIPSS Command
Bytes (Decimal) Bytes (Hex) Description
0 (0)
2 (2) Minimum window size, rows
4 (4) Minimum window size, columns
6 (6) Current® window size, rows
8 (8) Current window size, columns
10 (A) Maximum window size, rows
12 (C) Maximum window size, columns

218 Programming: Assembler

 DSIPSS

SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).
TYPE
Type of presentation services routine to be called:
ASYPANEL
Specifies that the issuing routine assumes control of the screen. Input and
output are formatted as 3270 data stream commands. Notification of input
availability is done asynchronously by the posting of event control blocks
(ECBs).
After a DSIPSS TYPE=ASYPANEL, input to the terminal is treated as input
to the process issuing the ASYPANEL request until a DSIPSS
TYPE=CANCEL or a DSIPSS TYPE=OUTPUT is issued.
For normal operations, presenting a panel to a user and processing
responses to it, specify both output data and input parameters in the
PANEL parameter list. Using separate DSIPSS TYPE(ASYPANEL) macros
for output and input introduces the possibility that operator input data can
be discarded before the input DSIPSS is processed.
Full-screen mode is not supported for unattended operator tasks, including
those associated with a system console.
CANCEL
Cancels pending asynchronous full-screen input. Use this option when
changing the characteristics of the asynchronous full-screen processor, such
as the ECB address or the panel address. TYPE=CANCEL is valid only
from an OST. You can call this option regardless of whether a DSIPSS
TYPE=ASYPANEL is active or the input from TYPE=ASYPANEL has been
posted as complete.
After TYPE=CANCEL is issued, no further input is received from the
terminal until TYPE=OUTPUT, TYPE=IMMED, or TYPE=ASYPANEL is
issued.
Issue DSIPSS TYPE(CANCEL) only when a program is going to free up or
change the storage areas used for output, input, ecb, or parmlist for a
previously issued DSIPSS TYPE(ASYPANEL), usually at the end of a
program. If a full-screen command processor is long running, “ending”
assumes issuing a DSIPOP and a return to the NetView program rather
than postponing the return. Issuing unneeded CANCELs can cause
operator input to be discarded between the CANCEL and the next
TYPE(ASYPANEL) or TYPE(OUTPUT).
FLASH
These messages are not suppressed by &WAIT or WAIT processing or
NetView automation, nor are they logged. These messages are not exposed.
You can log them before calling DSIPSS if you choose. They are displayed
regardless of the STIFLE state.
IMMED
Specifies that the routine is to send a message to the operator work
station's immediate message area. The maximum message length before
truncation occurs is 70 characters. Use this option only in immediate
command processors or the DSIEX01 installation exit routine. When you
specify this operand, no message header information is sent to the display

Chapter 8. Macros 219

DSIPSS

screen. TYPE=IMMED terminates full-screen mode and causes subsequent

terminal input to be treated as commands, except for the output of the
following commands:
v BROWSE (member or netlog)
v NLDM
v NPDA
v STATMON
v VIEW (NOINPUT option or special variables)
TYPE=IMMED also does not stop the output of DSIPSS TYPE=ASYPANEL
using PANEL parmlist-2.
DSIPSS calls DSIEX02A, message copy (ASSIGN), and logging functions.
OUTPUT
Specifies that the routine is to send a message to the operator's terminal.
Do not use this option:
v In immediate command processors
v In installation exit routines with TVBINXIT set on
v In installation exit DSIEX12
The maximum message length before truncation is 32000 characters for an
OST and 256 characters for an NNT. Upon completion of the macro, the
length of the text in the HDRMLENG field of the BUFHDR is set to the
length of the data after any trailing blanks have been truncated.
A command can be sent from an NNT to its associated OST if a DSIPSS
TYPE=OUTPUT passes either a HDRTYPEX buffer or a HDRTYPEI,
IFRCODAI buffer with IFRAUTBA and IFRAUTBL pointing to a
HDRTYPEX buffer.
DSIPSS calls DSIEX02A, message copy (ASSIGN), and logging functions.
PSSWAIT
Specifies that a command is to wait for a list of its own events (ECBs) and
a list of events related to the functioning of the task under which the
command is running. Use TYPE=PSSWAIT only when a command is called
as a resume routine. When the command is initially called or when called
as an abend routine or when called as a logoff routine, do not use the
TYPE=PSSWAIT call. See “DSIPUSH: Establish Long-Running Command”
on page 223 for more information about resume, abend, and logoff
routines. TYPE=PSSWAIT is valid wherever regular commands can run.

Note: Use the DSIWAT macro if the above conditions prevent use of
TYPE=PSSWAIT. However, some events related to function of the task can
be ignored during such a wait.
SCRSIZE
Specifies that the routine is to return the screen size in row-column format.
TESTWAIT
Enables a command processor to test whether an event occurred that
interrupts the asynchronous full-screen command processor.
TYPE=TESTWAIT is only of use if issued by a command processor driven
as a resume or abend routine. A logoff routine cannot issue a DSIPSS
macro. TYPE=TESTWAIT is valid only from an OST. Use this option before
issuing a DSIPSS TYPE=ASYPANEL to determine if the asynchronous
full-screen panel input/output (I/O) can be attempted. If you use DSIPSS

220 Programming: Assembler

 DSIPSS

TYPE=PSSWAIT to wait for events, this option can prevent unnecessary

screen I/O by enabling testing before panel I/O is requested.
WINDOW
Requests information about the size of the output area of the standard
screen. This option is valid only from an OST. Under any other task, the
request is considered null; register 15 contains a return code of 0, but no
function is performed. Three output area sizes are returned:
v Minimum
v Current
v Maximum
You can use the minimum window size to produce panels that are
independent of the current window size. The current window shows the
panel size currently in effect. The maximum window size is useful for
calculating the maximum storage needed to produce title-line panels.
XSEND
Specifies that the routine is to send data to another NetView program with
which a session exists. Sessions are started with the START DOMAIN
command. The maximum data length before truncation is 240 characters.

Return Codes in Register 15

The following return codes for the DSIPSS macro are found in register 15:
0 The function was successful; the message is written. For TYPE=PSSWAIT,
an ECB has been posted. Check the ECB list to determine which event has
completed. For TYPE=ASYPANEL, the send or receive request has passed
NetView syntax and buffer checking and has been sent to VTAM; it does
not indicate the success or failure of VTAM completion of the receive. You
must check the ECB post code to determine the success or failure of the
ASYPANEL request. The post code is put into the ECB specified in the
panel parameter list.
4 For TYPE=XSEND, no request parameter list (RPL) was found and no data
was sent.
8 Parameter error. There is an error in the formatting of the message buffer
header. For TYPE=XSEND, the session is not active and no data is sent. For
TYPE=ASYPANEL, the parameter list is inconsistent. If you specify the
output buffer, you must also specify the length. If you specify the input
ECB, you must specify the input area address, input area length, and the
data length address of the returned length.
12 The NetView program does not have enough storage available to complete
the request. No output is sent, and the input command processor cannot
be scheduled.
16 DSIPSS TYPE=OUTPUT was issued for an immediate command or in an
IRB exit routine. Use DSIPSS TYPE=IMMED or DSIMQS instead.
20 No terminal session exists. For TYPE=ASYPANEL, the panel request came
from a task other than an OST. No input is received. For TYPE=CANCEL,
the panel request came from a task other than an OST.
36 For TYPE=ASYPANEL, a temporary error occurred. The contents of the
panel have been modified. Reformat the panel using an Erase/Write or
Erase/Write Alternate 3270 command. Then retry the request.
40 A permanent I/O error occurred. Do not retry the request. No output is

Chapter 8. Macros 221

DSIPSS

sent, and no input processor is scheduled. For TYPE=ASYPANEL, no input

is received. For TYPE=CANCEL, the NetView program is unable to restart
normal terminal activity.
48 For TYPE=ASYPANEL, no I/O is scheduled because the command
processor issued a second DSIPSS TYPE=ASYPANEL requesting input
before the previous request had completed.
56 For TYPE=PSSWAIT or TYPE=TESTWAIT, at least one NetView ECB was
posted.
68 For TYPE=OUTPUT or TYPE=IMMED, a message being processed for the
RMTCMD command failed to be transmitted. This error can occur when
the DSIUDST task is inactive.

The following ECB post codes for PSS TYPE=ASYPANEL are found in the ECB if
you specified one:
0 The function was successful; the requested data is available.
12 The NetView program does not have enough storage available to complete
the request. The output data was sent, but the input data is not available.
36 A temporary error occurred during a full-screen read. Retry the request.
The output data was sent, but the input data is not available.
40 A permanent error occurred during a full-screen read. Do not retry the
request. The output data was sent, but the input data is not available.
52 The requested input was canceled by DSIPSS TYPE=CANCEL. Do not
retry the request immediately. The output data was sent, but the input data
is not available.

Note:
1. The DSIPSS macro no longer supports TYPE=PANEL. If you have an
application that uses the DSIPSS macro with TYPE=PANEL, rewrite the
application using TYPE=ASYPANEL.
2. The DSIPSS macro of any type other than CANCEL issued by code running on
a task that is ending (TVBTERM is on) is rejected with a return code of 40 (I/O
error).
3. FIRST, MIDDLE, LAST, and ONLY (supported in previous NetView releases)
are converted to a form similar to title-line output, with limited formatting
capabilities.
4. You can change applications using the SEG option to use the title-line
processing to improve the appearance of the output.
5. You can convert applications using FIRST, MIDDLE, LAST, or ONLY options to
use title-line, ASYPANEL, or the VIEW command for enhanced panel
management.
6. If your data is formatted as an automation internal function request (AIFR), it
must be in buffers located in subpool 0 which were obtained by DSIGET with
Q=NO specified. DSIPSS frees the AIFR structure. If your data is not formatted
as an AIFR, there is no restriction on the type of storage used, and the storage
is not freed; you must free it.
7. If an AIFR (IFRCODAI) is used, see the bits for IFRAUPHI and IFRAUPLO
(“AIFR–Automation Internal Function Request” on page 121) in the DSIIFR
structure description for a means to control the queueing priority of the
command being sent from the NNT to OST.

222 Programming: Assembler

 DSIPUSH

DSIPUSH: Establish Long-Running Command

The DSIPUSH macro can perform the following related functions:
v Establish named storage.
A storage pointer passed to DSIPUSH is associated with a 16-character name
chosen by the DSIPUSH caller. After a successful DSIPUSH, you can use the
DSIFIND macro to obtain the storage pointer from the name. All task types
supporting commands (PPT, OST, NNT, and DST) also support named storage.
v Establish a resumable command.
A resumable command can return to its caller with the assurance that the
specified RESUME routine is called when the task's asynchronous event handler
has completed processing. For example, you can exit to allow queued messages
to be processed. You can also exit after queuing a simulated terminal command.
All NetView components behave in this manner. Task types supporting regular
commands also support resumable commands (PPT, OST, and NNT).
v Establish an event routine.
An event routine is a regular command that is called whenever some ECB is
posted. Specifying an ECB address on the DSIPUSH macro specifies that your
SWBLRCRE routine is called promptly when the ECB is posted and only when
the ECB is posted.

These functions are task-level operations, global for the task where they occur, but
invisible from all other tasks. All requests define recovery and termination
procedures. (See note 1 on page 228.)

DSIMVT addressability is required.

When a command issues DSIPUSH for a RESUME routine, the following rules
apply:
v If a command called by a command procedure (NetView command list
language, REXX, or high-level language) specifies MAJOR when issuing
DSIPUSH, the command procedure is suspended at that point until the RESUME
routine is removed by DSIPOP.
v If such a command specifies MINOR when invoking DSIPUSH, the RESUME
routine is called following the completion of the command procedure.
A command can schedule a command procedure and obtain a return code by
taking the following steps:
1. Call DSIPUSH for its own RESUME routine.
2. Make a direct call to schedule the command procedure.
3. Upon return from the direct call, exit to enable the command procedure to
complete.
4. When the RESUME routine gains control, check the return code from the
command procedure in CWBRCODE.

Do not use RESUME or ABEND reinstate routines under a DST.

Do not use the DSIPUSH function while running in a LOGOFF or ABEND

reinstate routine, or while the TVBINXIT flag is on.

The following format is the syntax for the DSIPUSH macro:

Chapter 8. Macros 223

DSIPUSH

DSIPUSH

►► DSIPUSH SWB = ( register ) ►

label symbolic_name

► , LIST = ( register ) ►
symbolic_name , ECB = ( register )
symbolic_name

, PROMOTE = NO , CORR = RESUME

► ►◄
, PROMOTE = GROUP , CORR = CMD
NEWGROUP RESUME
NO NO
YES

Where:
CORR
Defines the correlation option for the DSIPUSH request.
The following list shows the options:
CMD
The current command correlation environment is saved even if no
RESUME routine was specified. The correlation environment can then be
reactivated later using DSIFIND. (When DSIFIND CORR=CMD is used, the
saved correlation environment becomes the current one.)
In applications where a RESUME routine was not used, this function
enables the DSIPSS output of a command using DSIFIND CORR=CMD to
be treated as if it was issued by the command that issued this DSIPUSH.
The output is in most cases asynchronous, when processed by a NetView
pipeline. Ensure that you code a CORRWAIT stage in the pipeline.
NO No correlation is done for the DSIPUSH request.
RESUME
DSIPUSH saves the current command correlation environment only if a
RESUME routine is specified. RESUME is the default when the CORR
keyword is omitted.
ECB
Is either a register containing the address of an ECB or the symbolic name of a
fullword area containing the address of an ECB. Specifying ECB means that
you want the command specified in SWBLRCRE to be called promptly when
the ECB is posted and only when the ECB is posted.
When you specify ECB, the command specified by SWBLRCRE is called an
event routine. The event routine must clear the ECB to prevent looping. If a
storage pointer was specified with the DSIPUSH startup (SWBLRCST value),
this value is passed to the event routine in register zero upon startup.
LIST
Is the register containing the address of a parameter list used by the service
routine, or symbolic name of that list. Do not specify this as register 1; register
1 contains the SWB address within DSIPUSH. Do not put this list in the SWB
that is to be passed to DSIPUSH. DSIPUSH reads, but does not write to, your

224 Programming: Assembler

 DSIPUSH

parameter list; nevertheless, reentrant code demands that you put the
parameter list in dynamic storage if your code updates any part of it (such as
the storage pointer) at run time.
The parameter list contains the fields shown in Table 47.
Table 47. LIST Parameters for the DSIPUSH Command
Hex Offset Length Field
20 8 SWBLRCAB = ABEND reinstate routine
30 4 SWBLRCFG = Flags
28 8 SWBLRCLG = LOGOFF routine
0 4 SWBLRCLN = Length
4 16 SWBLRCNM = Name
18 8 SWBLRCRE = RESUME routine
14 4 SWBLRCST = Storage address

Where:
SWBLRCAB
Specifies the load module name of the ABEND reinstate routine. This name
must not be 0 for tasks other than DST tasks. This name must be 0 for DST
tasks. The load module named must have a corresponding CMDDEF
statement. If more than one CMDDEF statement is coded for a module
name, the last CMDDEF statement found is used. The ABEND routine
must not be an immediate command. See note 6 on page 228.
SWBLRCFG
Indicates whether the DSIPUSH execution is minor or major. Bit 0 is the
indicator bit; it is defined when a RESUME routine is specified. When bit
0=1, a minor DSIPUSH is performed. When bit 0=0, a major DSIPUSH is
performed. See “RESUME Routines” on page 69 for more information
about major and minor invocations. When no RESUME routine is specified,
this field is ignored.
SWBLRCLG
Specifies the load module name of the LOGOFF routine. This name must
not be 0. The load module named must have a corresponding CMDDEF
statement. If you code more than one CMDDEF statement for a module
name, the last CMDDEF statement found is used. The LOGOFF routine
must not be an immediate command. See note 6 on page 228.
SWBLRCLN
Specifies the parameter list length. Set SWBLRCLN equal to SWBLRCPU
(decimal 52).
SWBLRCNM
Associates a name with your long-running command or storage address.
Use this name on subsequent calls to DSIFIND or DSIPOP. Ensure that the
name is unique within a particular task, and that a duplicate name used
under another task does not interfere. A second use of DSIPUSH for
named storage with the same name under the same task temporarily hides
the first storage pointer. The first storage pointer becomes accessible
through DSIFIND after DSIPOP is issued for the duplicate name.

Chapter 8. Macros 225

DSIPUSH

The name can be any combination of bits, as long as you specify the name
identically for all macro calls with the same name. Names beginning with
DSI are reserved for NetView names. The name field is used as is; it is not
padded or justified.
SWBLRCRE
Specifies the load module name of the RESUME routine. If this field is 0,
no RESUME routine is indicated. The load module named must have a
corresponding CMDDEF statement. If more than one CMDDEF statement
is coded for a module name, the last CMDDEF statement found is used.
The RESUME routine must not be an immediate command. See Note 6 on
page 228.
SWBLRCST
You can use this operand to associate a storage address with the specified
name. However, the NetView program makes no use of the value specified.
It is returned only when DSIFIND is called, specifying the same name.
PROMOTE
When you specify YES or NEWGROUP, a search is made of all currently
stacked long-running commands. If a long-running command with the same
name is found, the entire related group associated with that long-running
command is made the active group. Any parent procedure that has started the
long-running command processor is processed for cancellation.
The NetView program cancels a long-running command by resuming it with a
-5 completion code in CWBRCODE. The decision to cancel is left to the
long-running command processor. Cancelable long-running commands issue a
DSIPOP and return to the NetView program. The NetView program cancels
NetView command lists and high-level language (HLL) procedures in this way
when a -5 completion code is returned to them. Noncancelable procedures
ignore the -5 return code and are not automatically canceled by the NetView
program.
When you specify GROUP, the effect is the same except that the parent
procedure is not canceled. You can use the GROUP option only to complete a
previously running long-running command as shown in the following scenario:
1. A NetView command procedure calls a user command (for example,
COMMANDX). COMMANDX performs the following steps:
v Issues a DSIPUSH to push itself onto the task long-running command
queue
v Sends a request to another task using the DSIMQS macro
v Returns to the NetView program
2. The request running under the second task completes and returns a
response in the form of a command (for example, COMMANDY) to the
originating task.
3. The originating task runs COMMANDY, which does a DSIPUSH
PROMOTE=GROUP for COMMANDX. This makes COMMANDX and
associated long-running commands the active group. COMMANDY then
ends and returns to the NetView program.
4. COMMANDX resumes and completes.
5. Because PROMOTE=GROUP was specified and NEWGROUP or YES was
not specified, the parent of COMMANDX (the original NetView command
procedure) is given control when COMMANDX completes. Any other use
of the GROUP option can produce unpredictable results, including the
following scenarios:

226 Programming: Assembler

 DSIPUSH

v Incorrect panels were presented to the operator.

v Commands were lost.
v Return codes to and from long-running commands were processed
incorrectly.
v Storage associated with a long-running command was mishandled.
If the group does not exist, the request is treated as an ordinary DSIPUSH and
a stack element is created.
The storage specified in the invocation becomes the current storage associated
with the specified name (SWBLRCNM) and previous storage associated with
the name is returned to the caller in register 0.
When you specify PROMOTE=NO, or when the PROMOTE operand is
omitted, no search is performed. The DSIPUSH is considered new and a
long-running command (possibly a duplicate) is created. PROMOTE=NO is the
default.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB). The task information block (DSITIB) address in
SWBTIB must be correctly set.

Return Codes in Register 15

The following return codes for the DSIPUSH macro are found in register 15:
0 The function was successful; the long-running command request is queued.
4 Storage is not available for the request.
8 The ABEND reinstate or LOGOFF routine is required but was not
specified.
12 The request was issued from an incorrect task:
v RESUME request issued under DST
v ABEND request issued under DST
v DSIPUSH issued and task is not an OST, NNT, DST, or PPT
16 The request was issued while in an immediate command or while the
NetView program is in an exit, or in the middle of a LOGOFF routine or
ABEND reinstate routine.
20 The RESUME routine is a command list, or the CMDDEF statement did
not pass validity checking, or the operator's authority does not permit
access to the RESUME routine.
Verify that the first CMDDEF statement for this command in CNMCMD or
its included members is not of the immediate type.
24 The ABEND reinstate routine is a command list, or the CMDDEF statement
did not pass validity checking, or the operator's authority does not permit
access to the RESUME routine.
Verify that the first CMDDEF statement for this command in CNMCMD or
its included members is not of the immediate type.
28 The LOGOFF routine is a command list, or the CMDDEF statement did not
pass validity checking, or the operator's authority does not permit access to
the RESUME routine.

Chapter 8. Macros 227

DSIPUSH

Verify that the first CMDDEF statement for this command in CNMCMD or
its included members is not of the immediate type.
32 The macro call is not valid. Fix assembly errors before trying to run the
program.

Note:
1. DSTs always end after any failure (abend). Thus recovery routines are not
appropriate under DSTs.
2. When a command procedure is canceled for any reason, its return code is -5.
3. WAIT and PAUSE statements in a command procedure called by a
long-running command do not cause premature calling of the RESUME routine.
The RESUME routine is not scheduled until the command procedure completes.
4. HLL command processors cannot be pushed as ABEND, LOGOFF, or RESUME
routines.
5. Do not code a RESUME routine to use DSIPUSH PROMOTE to move itself to
the top of the long-running command stack. This causes the NetView program
to treat the DSIPUSH PROMOTE as a no-operation routine. A RESUME routine
can, however, specify another routine on a DSIPUSH PROMOTE invocation.
6. Command authorization checking is not done on routines specified by
SWBLRCAB, SWBLRCLG, or SWBLRCRE. If command authorization checking
is required, the long-running command procedure issuing the DSIPUSH can be
protected.
7. If register 15 contains return code 20, 24, or 28, register 0 contains a secondary
return code. Under “DSICES: Command Entry Services” on page 160, see
“Return Codes in Register 15” on page 162 for an explanation of the return
code in register 0.

Note: For more information, refer to the RESET command in IBM Tivoli NetView
for z/OS Programming: PL/I and C and the NetView online help.

DSIQOS: Query Operator Services

The DSIQOS macro determines whether an operator is defined to the NetView
program, and whether the operator is presently logged on.

The following format is the syntax for the DSIQOS macro:

DSIQOS

►► DSIQOS SWB = ( register ) ►

label symbolic_name

► , OPID = ( register ) ►◄
symbolic_name

Where:
OPID
Is the register containing the address of an 8-byte, left-aligned operator
identification field, or symbolic name of that field. Ensure that the contents of
the operator identification field are in uppercase.

228 Programming: Assembler

 DSIQOS

SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).

Return Codes in Register 15

The following return codes for the DSIQOS macro are found in register 15:
0 The operator ID is defined to the NetView program and is presently
logged on.
4 The operator ID is defined to the NetView program but is not presently
logged on.
8 The operator ID is not defined to the NetView program but is presently
logged on.
12 The operator ID is not defined to the NetView program.

DSIQRS: Query Resource Services

The DSIQRS macro determines whether a resource or a view is in any of the active
spans that an operator can access. The return code from the macro indicates
whether the specified operator ID is authorized to access the resource or view.

DSIMVT addressability is required.

The following format is the syntax for the DSIQRS macro:

DSIQRS

►► DSIQRS SWB = ( register ) ►

label symbolic_name

► , OPID = ( register ) ►
symbolic_name

► , RESOURCE = ( register ) ►
symbolic_name , RESLENG = ( register )
symbolic_name
, VIEW = ( register ) , VIEWLENG = ( register )
symbolic_name symbolic_name
RodmData

, ACCLVL = ALTER
► ►◄
, ACCLVL = ALTER
CONTROL
READ
UPDATE

RodmData:

, RODMOBID = ( register ) , RODMRET = ( register ) ►

symbolic_name symbolic_name

Chapter 8. Macros 229

DSIQRS

► , RODMREAS = ( register )
symbolic_name , RODMNAME = ( register )
symbolic_name

Where:
ACCLVL
Specifies the access level being checked for an operator's access to a resource. If
ACCLVL is not specified, the default of ALTER is used. The ACCLVL can have
one of the following values:
ALTER
Multiwrite access. This is the default.
CONTROL
Multiread and single-write access.
READ
Information-only access. This is the access level of commands such as LIST
or DISPLAY.
UPDATE
Change access. This is the access level of commands such as VARY,
MODIFY, REPLY, or generic GMF actions such as activate and deactivate.

The resource specified must be in an active span that was started by the
operator at the specified ACCLVL or higher. For example, to access a resource
at the UPDATE level, you must have a span active that contains that resource,
at least at the UPDATE level.

Note: For more information about defining and starting spans at specific
levels, refer to the IBM Tivoli NetView for z/OS Security Reference.
OPID
A register containing the address of an 8-byte area, or a symbolic name of that
area. The area contains the address of an 8-character NetView operator ID.
RESLENG
A register containing the address of a fullword area, or a symbolic name of
that area. The area contains the length of the name represented by the
RESOURCE keyword. If RESLENG is not specified, the default resource length
is the minimum of 8 or the actual length of the resource name.
RESOURCE
A register containing the address of an area, or a symbolic name of that area.
The area contains the address of the name of a resource to be matched against
the contents of the operator's active spans. If you do not specify RESLENG and
the resource name is less than 8 characters in length, the resource name is
padded with blanks.
RODMNAME
A register containing the address of an 8-byte area, or a symbolic name of that
area. The area contains the address of the 8-character hexadecimal RODM
name.
RODMOBID
A register containing the address of an 8-byte area, or a symbolic name of that
area. The area contains the address of the 8-byte hexadecimal RODM object ID.

230 Programming: Assembler

 DSIQRS

RODMREAS
A register containing the address of a fullword area, or a symbolic name of
that area. The area contains the address of the 4-byte RODM reason code.
RODMRET
A register containing the address of a fullword area, or a symbolic name of
that area. The area contains the address of the 4-byte RODM return code.
SWB
A register containing the address of a fullword area, or a symbolic name of
that area. The area contains the address of a service work block (DSISWB).
VIEW
A register containing the address of an area, or a symbolic name of that area.
The area contains the address of the name of a view to be matched against the
contents of the operator's active spans. VIEWLENG is required if VIEW is
specified.
VIEWLENG
A register containing the address of a fullword area, or a symbolic name of
that area. The area contains the length of the name represented by the VIEW
keyword.

Return Codes in Register 15

The following return codes for the DSIQRS macro are found in register 15:
0 The NetView operator has access to the resource at the specified level.
64 The NetView operator does not have access to the resource at the specified
level.
68 No name was defined for this RODM object.
101 RODM query failure.
104 The length of the resource name or view name is not valid. For example,
the length is zero (0).
128 The operator specified in OPID is not logged on to the NetView program.
160 No spans are defined to the NetView program.
200 Internal storage failure.
204 Request is not valid. For example, a query is made on a view name while
SECOPTS.SPANAUTH=*NONE* is used.

MNOTES Issued
v MNOTE 8, REQUIRED KEYWORD SWB MISSING
v MNOTE 8, REQUIRED KEYWORD OPID MISSING
v MNOTE 8, INVALID VALUE FOR ACCLVL. VALUES ARE READ, UPDATE,
CONTROL OR ALTER.
v MNOTE 8, KEYWORD MISSING - ONE OF THE FOLLOWING REQUIRED:
RESOURCE, RODMOBID OR VIEW
v MNOTE 8, BOTH RESOURCE AND RODMOBID CODED, ONLY ONE IS
VALID
v MNOTE 8, RODMNAME NOT VALID WITH RESOURCE
v MNOTE 8, BOTH RESOURCE AND VIEW CODED, ONLY ONE IS ALLOWED
v MNOTE 8, VIEWLENG NOT VALID WITH RESOURCE

Chapter 8. Macros 231

DSIQRS

v MNOTE 8, RODMRET NOT VALID WITH RESOURCE

v MNOTE 8, RODMREAS NOT VALID WITH RESOURCE
v MNOTE 8, BOTH RODMOBID AND VIEW CODED, ONLY ONE IS ALLOWED
v MNOTE 8, VIEWLENG NOT VALID WITH RODMOBID
v MNOTE 8, RESLENG NOT VALID WITH RODMOBID
v MNOTE 8, RODMREAS MUST BE SPECIFIED WITH RODMRET
v MNOTE 8, RODMRET MUST BE SPECIFIED WITH RODMREAS
v MNOTE 8, VIEWLENG MUST BE SPECIFIED WITH VIEW
v MNOTE 8, RESLENG NOT VALID WITH VIEW
v MNOTE 8, RODMNAME NOT VALID WITH VIEW
v MNOTE 8, RODMRET NOT VALID WITH VIEW
v MNOTE 8, RODMREAS NOT VALID WITH VIEW

DSIRDS: Resource Definition Services

The DSIRDS macro is no longer supported. This macro still exists for migration.
For span authority checking, use the DSIQRS macro. See “DSIQRS: Query Resource
Services” on page 229.

If you have any programs that call DSIRDS, rewrite them. If you reassemble any
code that calls the version of DSIRDS that is shipped with this NetView release,
the assembly fails with a return code of 8. This gives you a pointer to the places in
your programs that need to be rewritten.

If you do not reassemble your own applications, any application that calls DSIRDS
will fail with a return code of 28.

DSIRXEBS: Get an EVALBLOK

The DSIRXEBS macro is an interface for getting an evaluation block (EVALBLOK).

You can use the NetView DSIRXEBS macro or the TSO/E IRXRLT macro.

The size of the EVALBLOK data area is passed. The header size is added to the
data size, the appropriate doubleword area is obtained, and the area is initialized.
Parameters are passed in the system work block (DSISWB) that you provide. If you
pass an EVALBLOK address in the EVBPTR, that block is freed before the new
block is obtained. For additional information about DSIRXEBS, see Chapter 6,
“Writing User Function Directories,” on page 97.

DSIMVT addressability is required.

The following format is the syntax for the DSIRXEBS macro:

DSIRXEBS

►► DSIRXEBS SWB = ( register ) ►

label symbolic_name

► , LENGTH = ( register ) , EVBPTR = ( register ) ►

symbolic_name symbolic_name

232 Programming: Assembler

 DSIRXEBS

► , ENVBPTR = ( register ) ►◄
symbolic_name

Where:
ENVBPTR
Is the register, or symbolic name of a fullword area, containing the address of
the TSO/E environment block address.
EVBPTR
Is the register, or symbolic name of a fullword area, containing the address
where the EVALBLOK address is placed when it is obtained. If this area is not
0 (X'00') initially, it is assumed that it contains an EVALBLOK address to be
freed.
LENGTH
Is the register, or symbolic name of a fullword area, containing the address
where the EVALBLOK data size is obtained. The data size is the number of
bytes of data that are returned by the function.
SWB
Is the register, or symbolic name of a fullword area, containing the address of
an SWB.

Return Codes in Register 15

The following return codes for the DSIRXEBS macro are found in register 15:
0 The function was successful; the address of the EVALBLOK was returned
in EVBPTR. If an EVALBLOK address was passed, the block was freed.
8 Storage was insufficient to obtain the EVALBLOK. If an address of an
EVALBLOK was passed, the storage was freed.
12 A request was made and found not valid. One of the required operands
was not correctly specified.
20 Processing was not successful. A new evaluation block was not allocated.
28 Processing was not successful. A valid language processor environment
could not be located for the current task.

DSISRCMV: Search for Subvector or Subfield

The DSISRCMV macro establishes register conventions for a call to subroutine
SR$SUB in sample CNMS4284. SR$SUB searches a major vector for a subvector, or
a subvector for a subfield. SR$SUB returns the address of the subvector or subfield
if it is found.

The following format is the syntax for the DSISRCMV macro:

DSISRCMV

►► DSISRCMV ►
label

► MVADDR = ( register ) PRSVAD SearchChoice SVOCCUR ►◄

name
SVADDR = ( register ) PRSFAD , SFID = name SFOCCUR
name , SEQ = Y

Chapter 8. Macros 233

DSISRCMV

SearchChoice

, SVID = name
, SEQ = Y

PRSVAD:

, PRSVAD = ( register )
name

SVOCCUR:

, SVOCCUR = name

PRSFAD:

, PRSFAD = ( register )
name

SFOCCUR:

, SFOCCUR = name

Where:
MVADDR
Is the register, or symbolic name of a fullword area, containing the address of
the major vector.
PRSFAD
Is the register, or symbolic name of a fullword area, containing the address of
the last subfield found. This is an optional operand. If you code PRSFAD, the
search starts from this address rather than the address of the subvector
(SVADDR).
PRSVAD
Is the register, or symbolic name of a fullword area, containing the address of
the last subvector found. This is an optional operand. If you code PRSVAD, the
search starts from this address rather than the address of the major vector
(MVADDR).
SEQ
Specifies the search type to be performed.
Y Specifies to search sequentially for the next subfield or subvector. If you
specify both MVADDR and PRSVAD, the sequential search starts at the
address specified by PRSVAD. If you specify both SVADDR and PRSFAD,
the sequential search starts at the address specified by PRSFAD.

234 Programming: Assembler

 DSISRCMV

SFID
Is the symbolic name of a 1-byte hexadecimal field containing the subfield type
for which to search.
SFOCCUR
Is the symbolic name of a 2-byte (halfword) hexadecimal field containing the
subfield occurrence for which to search.
SVADDR
Is the register, or symbolic name of a fullword area, containing the address of
the subvector.
SVID
Is the symbolic name of a 1-byte hexadecimal field containing the subvector
type for which to search.
SVOCCUR
Is the symbolic name of a 2-byte (halfword) hexadecimal field containing the
subvector occurrence for which to search.

Note: Issue the DSISRCMV macro only from the CNMS4284 sample.

DSISYS: Operating System Indicator

The DSISYS macro is used for testing the current operating system by setting
global variables, as shown in Table 48. This macro is used in programs that are to
be run on multiple operating systems, to vary compilation according to the current
system. This macro enables system-dependent code to be placed in common
programs.

The following format is the syntax for the DSISYS macro:

DSISYS

►► DSISYS ►◄
label

&DSISYSE
Is a global variable that must be declared. &DSISYST is set at compilation time
by the DSISYS macro to determine if the current operating system is an
ESA-type operating system. Use the AIF assembler statement to test its value.
&DSISYST
Is a global variable that must be declared. &DSISYST is set at compilation time
by the DSISYS macro to reflect the current operating system. Use the AIF
assembler statement to test its value. The following list shows the values:
Table 48. Example of &DSISYSE Response to the DSISYS Command
Operating System &DSISYST &DSISYSE
z/OS MVS/XA MVS/ESA

DSITECBS: Manage a Dynamic ECB List for DSTs

The DSITECBS macro adds or deletes an ECB to or from a task's ECB list.

Chapter 8. Macros 235

DSITECBS

DSITECBS enables a DST to dynamically manage the ECB and specify the
command processor that is called when the ECB is posted.

MVT addressability is required.

The following format is the syntax for the DSITECBS macro:

DSITECBS

►► DSITECBS SWB = ( register ) ►

label symbolic_name

► , FUNC = ADD , ECBPRC = ( register ) ►

DELETE symbolic_name

► , ECB = ( register ) ►
symbolic_name , MAXCALL = ( register )
symbolic_name

► ►◄
, ENV = ( register )
symbolic_name

Where:
ECB
Is the register, or symbolic name of the fullword area, containing the address of
the area that contains the ECB address.
ECBPRC
Is the register, or symbolic name of the fullword area, containing the address of
the area that contains the name of the ECB command processor. This
parameter is required if you specify FUNC = ADD.
ENV
Is the register, or symbolic name of the fullword area, containing the address of
the environment area you want to accompany the ECB address and the ECB
processor. The environment address is returned when the ECB is posted.
FUNC
Specifies the function you want to perform. There is no default. Select one of
the functions:
ADD
Adds an ECB to the task's ECB list.
DELETE
Deletes an existing ECB from the list.
MAXCALL
Is the register, or symbolic name of the fullword area, containing the address of
the area that specifies a binary value for the maximum number of times the
ECB processor is called for the indicated ECB before other ECBs can be
serviced.
SWB
Is the register, or symbolic name of the fullword area, containing the address of
a service work block.

236 Programming: Assembler

 DSITECBS

Return Codes in Register 15

The following return codes for the DSITECBS macro are found in register 15:
0 The function was successful.
4 The load module name was not found in CNMCMD or its included
members.
8 The ECB address is already in the list.
12 There is insufficient storage to push the ECB.
16 An SWB cannot be obtained for internal work.
20 The ECB to be deleted was not found in the ECB list.
24 This task type is not valid; use a DST.

DSIVARS: Variable Services

The DSIVARS macro accesses, sets, and references NetView task global and
common global variables. Task global variables enable communication among
command lists, command processors, and installation exits running on the same
NetView task. Common global variables enable communication among command
lists, command processors, and installation exits running on all NetView tasks.

You can also use DSIVARS to set and reference local variables of the program that
called the assembler program that uses DSIVARS, if the assembler program was
called from a command procedure written in the NetView command list language,
REXX, PL/I, or C; or from a PL/I or C installation exit.

MVT addressability is required.

Note: Although the length limits for task and common global variable names and
values are 250 and 31000 bytes, respectively, the Save/Restore database (managed
by the DSISVRT task) limits are lower. Refer to the GLOBALV SAVE command for
more detailed information. For double-byte character sets (DBCS), the maximum
number of double-byte characters between the shift-out (X'0E') and shift-in (X'0F')
control characters is 15499.

The following format is the syntax for the DSIVARS macro:

DSIVARS

►► DSIVARS SWB = ( register ) ►

label symbolic_name

► , VARTYPE = CALLER , REQUEST = GET ►

TGLOBAL PUT
CGLOBAL

► , VARNAME = ( register ) ►
, NUMVARS = ( register ) symbolic_name
symbolic_name

► , VARLEN = ( register ) , VALUE = ( register ) ►

symbolic_name symbolic_name

Chapter 8. Macros 237

DSIVARS

► , VALLEN = ( register ) , VALRETL = ( register ) ►◄

symbolic_name symbolic_name

Where:
NUMVARS
Specifies the register, or symbolic name of a fullword area, containing the
number of variables to be processed. The parameter NUMVARS is optional.
If you do not specify a value for NUMVARS, the default is 1. Do not use a
value of 0.
REQUEST
Specifies which NetView variable operation to perform. The parameter
REQUEST is required.
GET
Retrieves a copy of the current value of the variable and returns it into the
area specified by VALUE, up to the length specified by VALLEN. Upon
return, VALRETL is set to the actual length of the returned value.
If the variable value is longer than the length specified by VALLEN, the
value is truncated and return code 4 is issued. If the variable has not been
previously set, VALRETL is set to 0.
PUT
Sets the value specified by VALUE and VALLEN of the variable name
specified by VARNAME and VARLEN into the variable pool specified by
VARTYPE.
SWB
Specifies the register, or symbolic name of a fullword area, containing the
address of a service work block (SWB). Set the SWBTIB field to indicate your
task information block (TIB). The SWB parameter is required.
VALLEN
For GET requests, VALLEN specifies the address of an area containing a list of
fullword values that contain the maximum length of values to be returned into
the matching VALUE area or the symbolic name of the list of fullword values.
If the length of the actual variable value is greater than the length specified by
VALLEN, the returned value is truncated and return code 4 is issued.
The actual length of the variable value is set in the VALRETL area. This storage
is in autodata or another addressable storage area because the DSIVARS
service writes a value to it.
For PUT requests, VALLEN specifies the address of an area containing a list of
fullword values that contain the length of the matching VALUE area that is
assigned to the variable or the symbolic name of the list of fullword values.
The maximum value length is 31000. If you specify a value length of 0, the
value of the variable is set to null.
VALRETL
For GET requests, VALRETL specifies the address of an area containing a list
of fullword fields or the symbolic name of the list of fullword fields. The
DSIVARS service sets the fullword fields to the actual length of the value
returned for each variable.
If a variable value is truncated, the VALRETL field for that variable contains
the actual length of the variable value, and the VALLEN field for that variable
contains the truncated length of the variable value.

238 Programming: Assembler

 DSIVARS

The parameter VALRETL is required for GET requests and ignored for PUT
requests.
VALUE
For GET requests, VALUE specifies the address of an area containing a list of
fullword addresses of storage locations to which the variable values are
returned as a result of the DSIVARS operation or the symbolic name of the list
of fullword addresses. This storage is in autodata or another addressable
storage area because the DSIVARS service writes a value to it. The parameter
VALUE is required.
For PUT requests, VALUE specifies the address of an area containing a list of
fullword addresses of storage locations that contain the variable values to be
associated with the variable names specified by VARNAME or the symbolic
name of the list of fullword addresses.
VARLEN
Specifies the address of an area containing a list of fullword variable name
lengths for the DSIVARS macro or the symbolic name of the list of fullword
variable name lengths. The parameter VARLEN is required.
A variable name can be from 1 to 250 characters.
VARNAME
Specifies the address of an area containing a list of fullword addresses of
storage locations that contain the variable names for the DSIVARS macro or the
symbolic name of the list of fullword addresses. The parameter VARNAME is
required.
Valid characters for variable names are A–Z, 0–9, @, #, $, ¢, ., !, ?, and _. Do not
use a number or a period as the first character in a variable name.
VARTYPE
Specifies the type of NetView variable to be referenced. The parameter
VARTYPE is required.
CALLER
Specifies the local variable pool of the calling command procedure or
installation exit that is accessed. The command procedure can be written in
REXX, NetView command list language, PL/I, or C.
You can use VARTYPE=CALLER only if the assembler program invoking
the DSIVARS macro was called from a command procedure or installation
exit written in PL/I or C. Specifying a VARTYPE of CALLER from an
assembler installation exit is not supported. Using VARTYPE=CALLER you
can set a variable to be referenced by the command procedure upon return
from an assembler command processor.
CGLOBAL
Specifies that the NetView common global variable pool can be accessed.
TGLOBAL
Specifies that the NetView task global variable pool can be accessed.

Return Codes in Register 15

The following return codes are for the DSIVARS macro:
0 Operation specified was successfully completed.
4 For a GET request, one or more variable values returned were truncated.
The actual value length was greater than that specified by VALLEN for
those variables.

Chapter 8. Macros 239

DSIVARS

8 For VARTYPE=CALLER, this macro was issued from a command processor

that was not called from a command procedure or high-level language
installation exit. VARTYPE=CALLER can be used only to access the calling
command procedure or the HLL program variable pool.
12 The number of variables specified is not valid. The value specified for
NUMVARS must be greater than 0.
16 Variable name is not valid. One or more variable names specified
contained characters that are not valid or had a length greater than 31
characters.
20 Value length not valid. One or more variable lengths specified are too long
(for a PUT request), or are less than 0 (for a GET or PUT request). You
must specify a variable value length no larger than 255 for PUT requests,
and 0 or greater for all requests.
24 Environment not valid. Global variables cannot be accessed while running
in asynchronous exit mode. The NetView program determines
asynchronous exit mode by examining the TVBINXIT flag.
28 Storage failure.

Note:
1. In the NetView command list language, variable names are limited to 11
characters, and more restrictions apply to the characters used in the variable. If
the variable name you specify is referenced in the NetView command list
language, the name can be no longer than 11 characters, and can only contain
characters that are acceptable in that language.
2. Variables are indicated in the NetView command list language by an
ampersand (&) at the front of the name. Do not use an ampersand to specify a
VARNAME.
3. For NetView common global variable requests using DSIVARS, the NetView
common global variable pool is locked for the duration of the DSIVARS
processing from other NetView tasks accessing it. This ensures that if multiple
variables are specified on one DSIVARS macro invocation, the common global
values are constant at that time.
4. Specifying a VARTYPE of CALLER from an assembler installation exit is not
supported and can cause unpredictable results. If there is an active command
procedure on the task running the installation exit, a variable can be set in the
running command procedure. The return code in this case is 0.

For more information about using NetView variables in NetView command list
language and REXX command lists, and about using NetView variables in PL/I
and C, refer to IBM Tivoli NetView for z/OS Programming: REXX and the NetView
Command List Language and IBM Tivoli NetView for z/OS Programming: PL/I and C.

DSIWAT: ECB Wait Services

The DSIWAT macro causes a subtask to wait for completion of an event.

The following format is the syntax for the DSIWAT macro:

240 Programming: Assembler

 DSIWAT

DSIWAT

►► DSIWAT ECB = ( register ) ►◄

label symbolic_name
ECBLIST = ( register )
symbolic_name

Where:
ECB
Is the register (2–12) containing the address of an aligned fullword to be used
as an event control block (ECB), or symbolic name of that aligned fullword.
ECBLIST
Is the register containing the address of a contiguous list of fullword addresses
of ECBs, or symbolic name of that list. The last entry in the list of ECB
addresses has the high-order bit 0 set to 1 to indicate the end of the list.

The following example shows how you can code DSIWAT:

DSIWAT ECBLIST=LISTAREA
:
ECB1 DC F’0’
ECB2 DC F’0’
LISTAREA DC A(ECB1)
DC A(ECB2)
DC A(ECB3)
DC A(ECB4+X’80000000’)
:
ECB3 DC F’0’
ECB4 DC F’0’

Execution resumes when any one of the ECBs is posted, and you can use the
DSIPOS macro to post an ECB.

Note:
1. If your code is going to run on any NetView task other than a user-optional
task:
v Do not call DSIWAT to wait on any event that can take a long time to
complete.
v Do not repeatedly issue DSIWAT for your own ECB. Process the ECB and
reissue the DSIWAT.
2. All NetView tasks must have adequate time to process their own internal work,
primarily represented by an internal ECB list. User code that can run for an
extended period or be redriven repeatedly must periodically return to the
NetView program to enable the task to do this internal work.
This can be done by writing your code as a long-running command processor.
(For more information, see Chapter 4, “Writing Command Processors,” on page
59.) Alternatively, you can call DSIPSS with the TYPE=PSSWAIT attribute, which
waits on your ECBs and the NetView task ECBs and then returns to the
NetView program when a return code of 56 is received. For more information,
see “DSIPSS: Presentation Services” on page 216.

Chapter 8. Macros 241

DSIWCS

DSIWCS: Write Console Services

The DSIWCS macro writes a message to the system operator's console. Do not use
this macro to produce a double-byte character string (DBCS) message. DBCS
messages are not supported by the operating systems.

If the message length is greater than 120 characters, it is continued in single-line

message DSI899I. The message buffer must have an initialized buffer header.

This macro issues the DSIWLS macro to log the write to the console. The route
code that is used is the value specified on the ROUTECDE statement in the
CNMSTYLE member.

MVT addressability is required.

The following format is the syntax for the DSIWCS macro:

DSIWCS

►► DSIWCS SWB = ( register ) ►

label symbolic_name

► , BFR = ( register ) ►◄
symbolic_name

Where:
BFR
Is the register, or symbolic name of a fullword area, containing the address of a
buffer with the message. This buffer must have an initialized BUFHDR.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).

Return Code in Register 15

The following return code is for the DSIWCS macro:
0 The function was successful; the message was sent to the system console.

DSIWLS: Write Log Services

The DSIWLS macro writes a record to the network log, CanzLog log, the hardcopy
log, the MVS system log, an external log, or a NetView sequential log, depending
on the use of the DEFAULTS command, OVERRIDE command, DSIEX02A exit, or
DSIEX04 exit, as follows:
v Without the EXTLOG parameter, the DSIWLS macro can send records to the
network log, CanzLog log, MVS system log, the operator's hardcopy device or,
with the SAMREC parameter, to a NetView sequential log. For the network log,
the record can be truncated, depending on the user-defined VSAM record size.
For the MVS system log, system truncation rules apply.
v With the EXTLOG parameter, the DSIWLS macro sends records to an external
task that can log the data.

MVT addressability is required.

242 Programming: Assembler

 DSIWLS

The following format is the syntax for the DSIWLS macro:

DSIWLS

►► DSIWLS SWB = Options ►

label

► , BFR = Options ►◄
, HCT = Options
, EXTLOG = ' xxx '
( register )
symbolic_name
, SAMREC = Options , SAMLEN = Options , SAMTASK = Options

Options:

( register )
symbolic_name

Where:
BFR
Is the register, or symbolic name of a fullword area, containing the address of a
user-provided input buffer. This buffer contains the record that is to be logged.
This buffer must have an initialized BUFHDR.
EXTLOG
Indicates that the buffer is to be logged externally under the DSIELTSK
subtask.
You can accomplish external logging in one of the following ways:
v Write to a system management facility (SMF) data set. The data to be logged
is a standard SMF record, with an SMF record type greater than or equal to
128. The DST XITXL installation exit is called before writing the record to
SMF.
v Write to a data set other than SMF. This option is not restricted to any
particular operating system. Code and install the DST XITXL installation
exit. This installation exit then performs the actual logging.
register
Is the register that contains the address of a 3-byte area that represents the
last 3 letters in the name of an external logging command processor.
symbolic name
Is the symbolic name of a 3-byte area that represents the last 3 letters in
the name of an external logging command processor.
xxx
Are 3 characters that become the last 3 characters of the command name
used to select the command processor that logs the data. The first
characters of the verb must begin with DSIEL. For example, if
EXTLOG=’ABC’, the CMDDEF statement in CNMCMD is:
CMDDEF.DSIELABC.MOD=DSIELSMF
CMDDEF.DSIELABC.TYPE=D
HCT
Is the register, or symbolic name of a fullword area, containing the hardcopy
task's TVB address.

Chapter 8. Macros 243

DSIWLS

SAMLEN
Is a keyword that either points to or names a 4-byte length of the record to be
logged. If the value of SAMLEN is greater than 32000, the record to be logged
is truncated and the macro returns a nonzero return code.
The BLKSIZE for a sequential logging task must be at least as large as
SAMLEN plus 42, or the record to be logged is truncated. SAMLEN is required
with SAMREC.
SAMREC
Is a keyword that either points to or names the record that is written to the
NetView sequential log that is controlled by the task indicated by the
SAMTASK keyword. Unlike the BFR keyword, this operand only points to the
data that is to be logged. NetView services put the record into the correct
format for scheduling the record to the sequential log task.
SAMTASK
Is a keyword that either points to or names an 8-byte NetView task name that
is defined to do sequential logging. This task can be verified for sequential
logging capability. The SAMTASK keyword is required with the SAMREC
keyword.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).

Return Codes in Register 15

If you do not specify EXTLOG or SAMREC, the following return codes for the
DSIWLS macro are found in register 15:
0 The function was successful; the record has been sent to the network log,
CanzLog log, and to the hardcopy log.
4 No storage is available for logging.
8 Successful log to the hardcopy log; network log or CanzLog log are not
active, or both are not active.
12 Successful log to the network log and CanzLog log; hardcopy log is not
active for this task.
16 The hardcopy log for this task, the network log, and the CanzLog log are
all inactive.

If you specify SAMREC, the following return codes can be returned:

0 The function was successful; the record has been queued to the sequential
log task.
4 No storage is available.
16 The task is not active, no data set is available, or the specified task is not a
sequential log task.
32 DSIWLS called with a length that is not valid or the buffer pointer is zero.

If you specify EXTLOG, the following return codes can be returned:

0 The function was successful. A copy of the caller's buffer is queued to the
external logging task (DSIELTSK).
4 No storage is available for copying the user input buffer for logging.

244 Programming: Assembler

 DSIWLS

24 No external logging command processor was found.

28 DSIMQS failed attempting to send the log record to the external logging
task.

Note:
1. You must specify either BFR or SAMREC, but not both.
2. You can specify either EXTLOG or HCT with BFR, but not both.

DSIZCSMS: CNM Data Services

The DSIZCSMS macro is a data services macro. It requests and sends CNM data
over the communication network management interface (CNMI).

DSIZCSMS embeds the caller's network services request or response unit (RU) in a
forward RU that is passed to the SSCP over the access method's CNMI. The SSCP
then sends the embedded RU to the specified destination.

MVT addressability is not required.

The following format is the syntax for the DSIZCSMS macro:

DSIZCSMS

►► DSIZCSMS SWB = ( register ) ►

label symbolic_name

► , DSRB = ( register ) INPUT ►

symbolic_name

, RTYPE = REPLY
► ►◄
OPTION TYPE , RTYPE = REPLY SECONDS
RESPONSE

OPTION

, OPTION = NOCNM
NOPRID
SALT

TYPE

, TYPE = CHAIN
RU
NOEMBED

SECONDS

, SECONDS = ( register )
symbolic_name

Chapter 8. Macros 245

DSIZCSMS

INPUT:

INPUT , LENGTH = ( register ) , RU = ( register ) ►

symbolic_name symbolic_name

► , RULENG = ( register ) , DEST = ( register ) ►

symbolic_name symbolic_name

►
, TARGET = ( register )
symbolic_name

INPUT

, INPUT = ( register )
symbolic_name

Note:

See the description for TYPE for information about conditions that apply to
CHAIN, NOEMBED, and RU.

For information about conditions that apply to OPTION, SALT, REPLY, SECONDS,
and DEST, see their respective descriptions.

Where:
DEST
Is the register, or symbolic name of a fullword user area, containing the
address of the network destination to which the embedded RU is sent. This
network destination is 8 characters long, left-aligned, and padded with blanks
if necessary.
DSRB
Is the register, or symbolic name of a fullword area, containing the address of a
data services request block (DSIDSRB) to be passed to the CNMI service
routine (DSIZCSMM).
INPUT
Is the register, or symbolic name of a fullword storage location, containing the
address of a user input buffer. The input buffer must be large enough to
contain a 24-byte buffer header plus the length of the RU to be sent (if a
forward RU is to be built, add 28 bytes to the size of the input buffer). This
buffer contains a buffer header followed by text. It also holds the deliver RU
that is returned by the access method. To enable command processors or
installation exit routines that operate in 24-bit addressing mode to access the
buffer, it resides below 16 MB. To receive a reply over the CNMI, the buffer
accommodates at least a 32-byte reply (a 24-byte NetView buffer header and an
8-byte positive or negative response).
LENGTH
Is the register, or symbolic name of a fullword storage location, containing the
length in binary of the input buffer.
OPTION
Enables nonstandard forward RUs to be sent by CNMI services.

246 Programming: Assembler

 DSIZCSMS

NOCNM
Indicates that a forward RU is sent that does not contain a CNM header, or
procedure-related ID (PRID). An example is a forward RU containing NS
IPL command types of INIT, TEXT, and FINAL.
NOPRID
Indicates that a forward RU is sent that does not contain a
procedure-related ID (PRID) in the CNM header. An example is a REQMS
that does not require a reply RECFMS because of user protocols.
SALT
Indicates that a forward RU is sent that is associated with a target. This
flag alerts VTAM that a target to the SNA address list translation (SALT) is
required for an NMVT to be transported using a forward RU.
RU Is the register, or symbolic name of a fullword storage location, containing the
address of a user area. The area is an RU that is to be embedded within the
forward RU.
RULENG
Is the register, or symbolic name of a fullword user area, containing the length
in binary of the embedded RU buffer. The RULENG cannot exceed 32743
decimal bytes.
RTYPE
Describes the response required for the request.
REPLY
Indicates that a REPLY RU is required for completion of the request. This is
the default.
RESPONSE
Indicates that a positive response is sufficient to complete the request.
SECONDS
Specifies the number of seconds to wait before canceling the outstanding
request. The number must have a positive value no greater than 86400. If you
do not specify the SECONDS operand or the value is 0, no timeout function is
performed (an indefinite wait is possible). If you specify SECONDS, you
cannot specify any of the following keywords and values:
v TYPE=RU
v TYPE=CHAIN
v OPTION=NOCNM
v OPTION=NOPRID
If you specify SECONDS and RTYPE=REPLY, specify DEST.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB) to be passed to the CNMI service routine
DSIZCSMM.
TARGET
Is the register, or symbolic name of a fullword user area, containing the
address of the network component that is the object of the embedded RU, or
symbolic name of that network component. This network component is 8
characters long, left-aligned, and padded with blanks if necessary.
TYPE
Controls the processing for the RU:

Chapter 8. Macros 247

DSIZCSMS

CHAIN
Indicates that the DSRB has received data and remains in use to accept
further RUs associated with the specific request. If you specify
TYPE=CHAIN, the SWB and DSRB operands are required; all other
operands are not valid. This operand is not valid with an unsolicited
DSRB.
NOEMBED
Indicates that a forward RU is not to be built for this request.
RU Indicates that the input RU is not to be embedded in a forward RU.

Return Codes in Register 15

The following major return codes for the DSIZCSMS macro are found in register
15:
0 The function was successful; data was sent to VTAM.
4 The requested function was performed.
8 The input buffer was too small to build a forward RU.
12 An error was found in a parameter specification.
16 The program did not run under a data services task.
20 The RULENG exceeded the maximum RU length required.

Minor Return Codes in Register 0

The following minor return codes for the DSIZCSMS macro are found in register
zero (0):
0 The function was successful.
4 The SWB was not valid.
8 The DSRB was not valid.
12 The DSRB that was passed was in use.
16 An unsolicited DSRB was passed.
20 An operator ID specified in the DSRB was not valid.
24 Reserved.
28 There was insufficient storage to process the request.
32 The CNMI is inactive.
36 The request was rejected by the access method.
40 An installation exit rejected the request.
44 Data truncation occurred during the installation exit processing.
48 The specified SECONDS value was not valid.

CNM Data Services Module Examples

The following examples show how you can specify the DSIZCSMS macro.

248 Programming: Assembler

 DSIZCSMS

DSIZCSMS SWB=SWBADDR,DSRB=DSRBADDR,INPUT=RAQDDR, C
LENGTH=FORWDLEN,RU=READYRU,RULENG=READLEN, C
DEST=DESTNAME,RTYPE=REPLY,SECONDS=TIMEOUT

Figure 16. Example 1

In Example 1, the data is sent across the CNMI to DESTNAME. READYRU

contains the request RU that is to be sent. The reply information is returned in the
RQADDR buffer. After TIMEOUT seconds, the request is canceled. If an associated
reply is received later, it is discarded.

DSIZCSMS SWB=SWBADDR,DSRB=DSRBADDR,INPUT=RAQDDR, C
LENGTH=FORWDLEN,RU=READYRU,RULENG=READLEN, C
DEST=DESTNAME,RTYPE=REPLY.

Figure 17. Example 2

In Example 2, the data is sent across the CNMI to DESTNAME. READYRU

contains the request RU that is to be sent. The reply information is returned in the
RQADDR buffer. The request remains outstanding until a reply is received.

Note:
1. Specify either OPTION or TYPE keywords, but not both.
2. When RTYPE=REPLY, do not specify OPTION=SALT. Specify only one of the
following keywords and values:
v OPTION=NOCNM
v OPTION=NOPRID
v The keyword SECONDS
3. Specify TARGET if OPTION=SALT.
4. Specify only one of the following keywords and values:
v OPTION=NOCNM
v OPTION=NOPRID
v The keyword SECONDS
5. If TYPE=CHAIN, SWB and DSRB are required.
6. If TYPE does not equal CHAIN, SWB, DSRB, INPUT, RU, and DEST are
optional.
7. Specify either TYPE=CHAIN or the keyword SECONDS, but not both.
8. If you specify TYPE=NOEMBED, do not enter TARGET or DEST.
9. If you specify TYPE=RU, do not enter SECONDS, TARGET, DEST, or
RTYPE=RESPONSE.
10. For major return codes of 8 or 20, register 0 contains the RULENG.

Note: For more information about SNA RUs, refer to the SNA library.

DSIZVSMS: VSAM Data Services

The DSIZVSMS macro is a data services macro. It requests VSAM services for a
data services command processor (DSCP).

DSIZVSMS provides access to VSAM services that perform input/output to the

specified problem determination file or data set. The operands provide access for
data recording, data retrieval, and data deletion.

MVT addressability is not required.

Chapter 8. Macros 249

DSIZVSMS

The following format is the syntax for the DSIZVSMS macro:

DSIZVSMS

►► DSIZVSMS SWB = ( register ) ►

label symbolic_name

► , DSRB = ( register ) , FUNC = GET ►

symbolic_name PUT
POINT
ENDREQ
ERASE

► ►
, KEYLEN = 1
, KEY = ( register )
symbolic_name , KEYLEN = ( register )
symbolic_name

► ►◄
, OPTION = ( Options ) , DATAREA = ( register )
symbolic_name

Options:

, SEQ , ARD , FWD , NUP , KEQ , FKS

, DIR , LRD , BWD , NSP , KGE , GEN
, SKP , UPD

Where:
DATAREA
Is the register containing the address of a user work buffer, or symbolic name
of that buffer. The buffer must be large enough to contain the maximum size
record in the file or data set. The buffer is used by VSAM in the processing of
records. This buffer contains an initialized BUFHDR, followed by text.
DSRB
Is the register, or symbolic name of a fullword, containing the address of a
data services request block (DSIDSRB). The DSRB contains request information
such as request parameter list (RPL), ACB, ECB, and fields used by the data
services task VSAM service routine for VSAM I/O.
FUNC
Describes the VSAM request macro to be issued.
KEY
Is the register containing the address of the VSAM key to be used for access to
the requested data, or symbolic name of a fullword that contains the key.
Because DSIZVSMS restores the key to its original location, the key must also
be in NetView-accessible storage.
KEYLEN
Is the register, or symbolic name of a fullword, containing the length in bytes
of the key pointed to by KEY. The default key length is 1.
OPTION
Specifies the type of access to the file through requests defined by the NetView
request parameter list (RPL). Options are arranged in groups. The first time the

250 Programming: Assembler

 DSIZVSMS

RPL is set up, you must specify one, and only one, option from each group.
Later, you can specify one option from one or more groups. Separate multiple
options with commas.
This OPTION operand has no defaults. This operand is not valid when you
specify FUNC=ERASE or FUNC=ENDREQ.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB). The SWB contains a save area, work area, and
task information block (DSITIB) address data. The caller must initialize the
SWBTIB field in the SWB with a valid TIB address.

Return Codes in Register 15

The following major return codes for the DSIZVSMS macro are found in register
15:
0 Successful completion of VSAM function.
4 Manipulative macro error occurred during processing.
8 An error occurred in the EXECUTE form of a manipulative macro. An
operand was not in the list.
12 Unsuccessful completion.
16 DSIZVSMS was issued while not running under a DST.

Minor Return Codes in Register 0

The following minor return codes for the DSIZVSMS macro are found in register
zero (0):
0 Successful completion.
4 The specified DSRB was not valid or in use.
8 An ACB was unavailable or was not open. This can be because of a SWITCH
taskname,T command having been issued.
12 Resume verb processing error.
16 An installation exit rejected the request.
20 The VSAM I/O request was not valid or there was an I/O scheduling
error.
24 Data truncation occurred during substitution of data in an installation exit;
or control block storage was not obtained.
28 An installation exit returned a return code that was not valid.

For more information about specifying FUNC and OPTION, and for an
explanation of RPL feedback codes, refer to the DFSMS library.

DSI6REGS: LU 6.2 Registration

The DSI6REGS macro registers a management services (MS) application name with
the MS transport, or a served application name with operations management.

The registration includes the command name of the command processor to be

called when unsolicited or asynchronous solicited data is routed to an MS
application or served application. The NetView task where the service routine is

Chapter 8. Macros 251

DSI6REGS

running is registered as the task where the command is to run when unsolicited
data is received. The called service program keeps track of the registered
applications and served applications internally to provide routing.

Before accepting the registration request, the NetView program verifies that the
task has the authority to issue the specified command to be driven with data
received.

An MS application or operations management served application can also indicate

on the registration request that it wants to be informed of any focal point
information for a specified focal point category. In addition, an MS application can
specify whether it is a focal point application.

The registration request can specify whether it replaces a current registration for
the MS application or served application. When the request replaces prior
registration, subsequent registration requests can change the task or command
processor that is to receive unsolicited data or the focal point category of interest.
Concurrent requests from multiple tasks are sequenced at points of potential
conflict. An application can register as both an MS application and an operations
management served application. A registration of one type does not affect the
registration of the other type.

Deregistration terminates the NetView MS transport's awareness of the MS

application or operations management's awareness of the served application. No
further data can be sent or received by the application using the NetView MS
transport except outstanding replies.

The service routine returns control to the invoking component after it has
processed the registration or deregistration request.

The DSI6REGS macro can be called only from a task within the NetView address
space.

The following format is the syntax for the DSI6REGS macro:

DSI6REGS

►► DSI6REGS SWB = swbname ►

label ( register )

► , TYPE = REGMSAPPL , APPL = applname ►

DEREGMSAPPL ( register )
REGOMSERVD
DEREGOMSERVD

, FOCALPT = NO
► ►
COMMAND FPCAT , FOCALPT = NO
YES

252 Programming: Assembler

 DSI6REGS

, REPLACE = YES , NOTIFY = NONE

► ►
, REPLACE = NO , NOTIFY = ALL
YES ERROR
NONE

, PRI = LOW
► ►◄
, PRI = HIGH
LOW
NORMAL
TEST

COMMAND

, COMMAND = cmdname
( register )

FPCAT

, FPCAT = fpcategory
( register )

Where:
APPL
Is an 8-byte character field that specifies the MS application or served
application name that is being registered or deregistered.
For an MS application, this identifier is the name to be used in the Application
ID (X'03') subfield of the origin or destination location name fields of the
multiple-domain support message unit (MDS-MU) header as described in the
SNA library. It is either one of the architecturally defined fullword values
(padded with blanks to 8 bytes) for management services application
programs, or a 1- to 8-character installation-defined name (padded with
blanks). Installation-defined names use only the EBCDIC characters 0–9 and
A-Z (capital letters only).
For a served application, this identifier is the name to be used in the
application name fields (X'50' and X'60') within routing and targeting
instruction (R&TI) general data stream (GDS) variables within CP-MSUs. The
name within this applname field is either an architected served application
name, made up of hexadecimal and EBCDIC characters, or an
installation-defined name, using only the EBCDIC characters 0 - 9 and A - Z
(capital letters only). In either case, the name is padded with blanks to 8
characters. If you use an architected name, supply a field name because
hexadecimal data in a string literal is not supported. The CNMREGIST service
routine truncates any trailing blanks before placing the name in a registration
table.
The NetView program reserves application names categories for the following
application names:
Reserved Name
Hex Equivalent

Chapter 8. Macros 253

DSI6REGS

ALERT
X'23F0F3F1'
EP_OPS
X'23F0F1F6'
EP_SPCS
X'23F0F1F4'
HMON_DST
X'30F0F8F5'
HMON_OST
X'30F0F8F4'
LINKSERV
X'23F0F3F5'
MDS_ROUT
X'23F0F1F0'
MS_CAPS
X'23F0F1F1'
OPS_MGMT
X'23F0F1F7'
R_BRIDGE
X'30F0F5F9'
RMTCMD_O
X'30F0F7F2'
RMTCMD_R
X'30F0F5F5'
RMTCMD_S
X'30F0F7F0'
SPCS X'23F0F1F5'
STATUS
No hexadecimal equivalent
No character equivalent
X'23F0F0F1'
No character equivalent
X'30F0F7F3'
This is a required operand.
COMMAND
Is an 8–byte character field that specifies the name of the command procedure
that is driven with any data that has a destination name equal to the one in
the applname operand. The only exception is for replies to requests that
specified a command on the CNMSENDMU invocation. The data is received as
a message unit. This is either a command name or a register containing a
pointer to it.
This operand is required for registration requests and not valid for
deregistration requests.
FOCALPT
A fullword character field that specifies whether the MS application is a focal
point application.

254 Programming: Assembler

 DSI6REGS

NO Specifies that the MS application is not a focal point application. This is the
default.
This operand is required for registration requests and not valid for
deregistration requests.
YES
Specifies that the MS application is a focal point application. A value of
YES is appropriate only for an MS application registration. It is not
acceptable for an operations management served application.

Note:
1. If an MS application registers as a focal point application and later the
same MS application registers again with a focalpt of NO, the
application still receives focal point data from any node that did not
attempt to send while the application was deregistered.
2. When you specify YES, the focal point category name is the application
name specified in applname. If you specify fpcategory as well, it must be
the same.
FPCAT
An 8-byte character field that specifies the focal point category about which the
registrant wants to receive focal point information. Focal point category names
are the applnames of MS applications that are focal point applications
(registered with FOCALPT = YES). They are specified as described under
APPL.
If a focal point for this category exists at the time of registration, the command
processor specified with the cmdname operand is scheduled to run under the
current task. On the initial data queue of the command processor is an
MDS-MU with a control point management services unit (CP-MSU) containing
an MS capabilities (MS_CAPS) major vector with a X'E1' subvector informing
the application of its focal point information. Whether a focal point exists
initially or not, all subsequent changes in the focal point information for the
fpcategory are conveyed to the registering application from the MS_CAPS
application or from EP_OPERATIONS_MGMT function in the same way using
an X'E1' subvector in an MS capabilities major vector.
The NetView program provides focal-point applications for the following focal
point categories:
v ALERT_NETOP (X'23F0F3F1')
v OPERATIONS_MGMT_NETOP (X'23F0F1F7')
v SPCS (X'23F0F1F5.')
This operand is required for registration requests and is not valid for
deregistration requests.
NOTIFY
Is a literal value that specifies whether this registration is to supply an MDS
error message if connectivity to other nodes is lost. NONE is the default.
ALL
Specifies that this registration receives all the notifications that ERROR
provides, and in cases when the high-performance transport classifies a
session outage as normal and does not attempt to reestablish connectivity.
ERROR
Specifies that this registration receives notification if there is a normal or
abnormal loss of connectivity to another node. A normal loss can occur if

Chapter 8. Macros 255

DSI6REGS

you have outstanding transactions with the other node. An abnormal loss
can occur if you have a session outage and connectivity cannot be
reestablished.
NONE
Specifies that this registration does not receive any error notification.
NONE is the default.
PRI
Supplies the MQS priority for incoming requests. The MQS priority is used
when the MS or high performance transport uses the MQS for processing of
any received unsolicited MDS-MUs. The value is one of the four strings HIGH,
NORMAL, LOW, or TEST, The priority value must be entered as 8-bytes,
including blanks. For example:
’LOW ’
’HIGH ’
’NORMAL ’
’TEST ’

Note: The single quotation marks are shown only to demonstrate the 8-byte
field. Do not include them as part of the priority specification.
The following list shows the priorities:
HIGH
Processing begins after any NORMAL requests currently in progress, but
before queued NORMAL or LOW requests.
LOW
Processing is preempted by HIGH and NORMAL priority requests. This is
the default.
NORMAL
Processing priority preempts a queue of LOW priority requests.
TEST
DSIMQS queues the request at either HIGH or LOW priority, according to
the destination task's command priority. Refer to the OVERRIDE command
in the NetView online help for an explanation of command priorities.
REPLACE
Specifies whether this registration supersedes a previous registration.
NO Specifies that this registration cannot replace any current registration for
the same application. If the same MS application or operations
management served application is already registered, the service routine
returns a return code of 2.
This operand is required for registration requests and not valid for
deregistration requests.
YES
Specifies that this registration replaces any current registration for the same
application. This is the default. If you specify YES, an application can:
v Change the name of the command driven to process data received
v Change the name of the task where the command is driven with
unsolicited data
v Change whether the application is to receive focal point information
SWB
Is the symbolic name, or register of a fullword area, containing the address of
the SWB. This is a required operand.
256 Programming: Assembler
 DSI6REGS

TYPE
Specifies the type of request:
REGMSAPPL
Register an MS application to the NetView MS transport.
REGOMSERVD
Register a second-level application to operations management. This
makes the application a served application of operations management.
DEREGMSAPPL
Deregister an MS application.
DEREGOMSERVD
Deregister an operations management served application.

Return Codes in Register 15

The following return codes for the DSI6REGS macro are found in register 15:
0 The function was successful. The application (APPL) was registered or
deregistered.
20 Deregistration unsuccessful. APPL is not registered.
24 Registration unsuccessful. No storage available.
44 Deregistration unsuccessful; issued from an asynchronous exit.
104 Registration unsuccessful. APPL is already registered.
472 Registration/deregistration unsuccessful. The resource user queue is full.
476 Registration/deregistration unsuccessful. APPL name syntax is not correct.
480 Registration/deregistration unsuccessful. APPL name is restricted.
484 Registration/deregistration unsuccessful. FPCAT name syntax is incorrect.
488 Registration/deregistration unsuccessful. FPCAT has an incompatible
value.
592 Registration/deregistration unsuccessful. Incorrect NOTIFY value.
9012 Registration unsuccessful. COMMAND not valid.
9016 Registration unsuccessful. The current task is not authorized for
COMMAND.
9020 Registration unsuccessful. The current task and COMMAND are not
compatible.

Note:
1. When an operations management served application is registering, the only
valid value for fpcategory is OPERATIONS_MGMT_NETOP (X'23F0F1F7'). This
is either a fpcategory field or a register containing a pointer to it.
2. If two nodes in two networks have the same LU name, VTAM can locate either
one, depending on the active configuration.
3. The NetView task where an MS application or an operations management
served application receives an MDS-MU is determined as follows:
v For a multiple-domain support (MDS) reply, the task is the task under which
the requesting MS application or operations management served application
was running.
v For a request MDS-MU:

Chapter 8. Macros 257

DSI6REGS

– For an MS application, the task is the registered task for the MS

application.
– For an operations management served application, the task is determined
from the destination instance identifier in the R&TI if it is
present.Otherwise, the task is the registered task for the served
application.
v For an MDS error message:
– If the unit of work correlator (UOWC) matches an active unit of work in
one of the active transaction lists:
- For an outgoing request, the task is the task under which the requesting
MS application or operations management served application that
received the request was running.
- For an incoming request, the task is the task under which the MS
application or operations management served application that received
the request was running.
– If the UOWC does not match an active unit of work, the task is the
registered task for the MS application or operations management served
application.

DSI6SNDS: Send a Message Unit

The DSI6SNDS macro enables MS applications or operations management served
applications on the NetView program to send data to a specified target in the same
domain or any LU in any domain. DSI6SNDS is not available if DSI6DST is
inactive.

Invoking this service routine causes the requested data to be given to the NetView
MS transport. The NetView MS transport uses an LU 6.2 conversation, and VTAM
selects the appropriate session for the actual transmission.

The data to be sent is in the form of an MDS-MU. You can supply the following
information for the MDS-MU header:
v A completely built MDS-MU.
v An MDS-MU that is missing one or more of the following values:
– A unit-of-work correlator (UOWC)
– An origin NETID
– An origin LUNAME
These are added by the service routine.
v Data (for example, a CP-MSU) and sufficient other parameters for the service
routine to build an MDS-MU header.

If the destination MS application is OPERATIONS_MGMT_NETOP or

EP_OPERATIONS_MGMT, the invoking program must include the routing and
targeting instructions (R&TI) GDS variable within the CP-MSU embedded in the
MDS-MU being sent.

The DSI6SNDS macro builds the necessary NetView message queueing service
(MQS) buffer with the specified data and enqueues it for the NetView MS
transport.

The service routine returns control to the invoking component after it has
successfully queued the request to the NetView MS transport.

258 Programming: Assembler

 DSI6SNDS

The following format is the syntax for the DSI6SNDS macro:

DSI6SNDS

, DATATYP = MDSMU
►► DSI6SNDS SWB = swbname ►
label ( register ) , DATATYP = MDSMU
NONMDSMU

► , DATA = dataarea ►
( register )

► ►
SUPCORR CORAREA SECONDS REPCMD ORIGAPP

► ►
DESTNET DESTLU DESTAPP MUTYPE PRI

, SYNCH = NO_BUF
► ►◄
, SYNCH = NO_BUF
NO_UNBUF

SUPCORR

, SUPPCORR = suppliedcorr
( register )

CORAREA

, CORAREA = correlarea
( register )

SECONDS

, SECONDS = timeout
constant

REPCMD

, REPCMD = replycmd
( register )

ORIGAPP

, ORIGAPP = origappl
( register )

DESTNET

, DESTNET = destnet
( register )

Chapter 8. Macros 259

DSI6SNDS

DESTLU

, DESTLU = destlu
( register )

DESTAPP

, DESTAPP = destappl
( register )

MUTYPE

, MUTYPE = mutype

PRI

, PRI = priority
( register )

Where:
CORAREA
Is a 52-byte varying length character field in which a new unit of work
correlator (X'1549') GDS variable is created and returned by the DSI6SNDS
macro. The length subfield (the first 2 bytes) indicates the length of the
correlator. The correlator length is always 52 bytes for this release of the
NetView program.
If you specify CORAREA for an MDS-MU, the NetView program 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. In this
case, NETID and LUNAME are inserted into the origin location (X'81')
subvector at the same time if they are not already present (if there are no X'01'
and X'02' subfields within the subvector). If you omit CORAREA, the
MDS-MU must be complete and ready to be transmitted as supplied.
For NONMDSMU specify either CORAREA or SUPCORR. If you specify
CORAREA, DSI6SNDS creates the unit of work correlator GDS variable in this
area and uses it in building the MDS header. The service routine uses the
supplied value in building the MDS header if you specify SUPCORR. No
validity checking is done for a correlator the caller supplies.
If this is an MDS reply or an MDS error message, do not use CORAREA,
because an MDS reply or error message must return the correlator sent with
the request. The invoking application must supply the original correlator either
in the MDS-MU or with the SUPCORR keyword.
CORAREA is mutually exclusive with the SUPCORR keyword.
You can specify either the name of the area or a register containing a pointer to
the area.
DATA
Is a varying length character field containing the data being sent. For either
MDSMU or NONMDSMU, the first two bytes must contain the entire length of

260 Programming: Assembler

 DSI6SNDS

the data and the next two bytes must contain the key. The maximum length of
the data is as defined in the SNA architecture for the data object being sent.
For an MDS-MU, all fields within the MDS-MU header must be properly
prepared before invocation (with the possible exception of the correlator and
the origin NETID and LUNAME). If the correlator is not contained in the data,
specify correlarea.
You can specify either the name of the data or a register containing a pointer
to the data.
DATATYP
Is an 8-byte character field that indicates that the data item specified with the
DATA keyword is an MDS-MU or a non-MDS-MU.
MDSMU
Indicates that the DATA keyword is an MDS-MU. MDSMU is the
default.
NONMDSMU
Indicates that the DATA keyword is not a complete MDS-MU because
it does not contain an MDS-MU header. The DSIHSNDS macro
envelopes this data in an MDS-MU header before sending it.
DESTAPP
Is an 8-byte character field that specifies the destination application name.
The application name can be one of the following values:
v An architecturally defined fullword value (padded with blanks to 8 bytes)
for MS application programs.
v A 1- to 8-character installation-defined name (padded with blanks). Use the
EBCDIC characters 0–9 and A–Z (capitals only).
The DSI6SNDS macro truncates any trailing blanks before putting this value in
the MDS-MU header.
You can specify either the destination application name or a register containing
a pointer to the destination application. The macro automatically translates the
following destination application names to hexadecimal format:
v EP_OPS
v OPS_MGMT
v ALERT
DESTAPP is required for NONMDSMU.
DESTLU
Is an 8-byte character field that specifies the LU or VTAM CP name of the
destination LU or VTAM CP. Specify the 1- to 8-character LU or VTAM CP
name (padded with blanks to 8 characters) using only the EBCDIC characters
0–9 and A–Z (capitals only). If DESTLU is not specified, the default is the CP.
The DSI6SNDS macro truncates any trailing blanks before putting this value in
the MDS-MU header.
This field is required for NONMDSMU.
DESTNET
Is an 8-byte character field that specifies the ID of the network of the
destination LU or VTAM CP name. You must specify the 1- to 8-character
NETID (padded with blanks to 8 characters) using only the EBCDIC characters
0–9 and A–Z (capitals only).

Chapter 8. Macros 261

DSI6SNDS

The DSI6SNDS macro truncates any trailing blanks before putting this value in
the MDS-MU header. If you specify 8 blanks as the value, the effect is the same
as not specifying the keyword. The default is the network name determined by
VTAM based on the LU or VTAM CP name of the remote node you specify
with the DESTLU keyword.
You can specify either the destination NETID name or a register containing a
pointer to the destination NETID.
If you do not specify the DESTNET keyword when using DSI6SNDS for
NONMDSMU data types, the value of this field defaults to the NETID
determined by VTAM. Otherwise, this field is required for NONMDSMU data
types.
MUTYPE
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. The
following types are defined as constants:
REQUEST_WITH_REPLY
1
REQUEST_WITHOUT_REPLY
2
REPLY_ONLY
3
REPLY_NOTLAST
4
REPLY_LAST
5
ERROR_MESSAGE
6
The DSI6SNDS macro uses the MUTYPE value to determine the settings for
the MDS message type and first and last message indicator bits in the flags
(X'90') MDS routing information subvector.
This is a required keyword for NONMDSMU.
ORIGAPP
Is 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 fullword value (padded with blanks to 8 bytes)
for MS application programs.
v A 1- to 8-character installation-defined name (padded with blanks). You
must use the EBCDIC characters 0–9 and A–Z (capitals only).
The DSI6SNDS macro truncates any trailing blanks before putting this value in
the MDS-MU header.
You can specify either the origin application name or a register containing a
pointer to the origin application.
This field is required for NONMDSMU.
PRI
Supplies the MQS priority for incoming reply or MDS error message resulting

262 Programming: Assembler

 DSI6SNDS

from any outgoing MDS-MU. It must be the name or address of an 8-byte

(including blanks) character field that contains the preferred priority. Its value,
including blanks, can be:
’LOW ’
’HIGH ’
’NORMAL ’
’TEST ’
SYNCH
Specifies the buffering options available on requests_with_replies:
NO_BUF
Specifies to buffer replies until reply_last is received. This is the
default.
NO_UNBUF
Specifies to send each reply to the application as it is received.
REPCMD
Is an 8-byte character field containing the name of the command to be driven
with the reply. You can specify REPCMD only in an application that is sending
REQUEST_WITH_REPLY, with the reply being received asynchronously.
If REPCMD is not specified when a high-performance application sends a
REQUEST_WITH_REPLY, the value defaults to the registered command of the
high-performance application at sending time. If the high-performance
application issues the DSIHREGS macro with the REPLACE(YES) option before
the reply is received, the reply is sent to the original registered command when
it comes in.
You can specify either the reply command processor name or a register
containing a pointer to the reply command processor.
This is an optional field. The default is the registered command for the
invoking application.
SECONDS
Is a fullword 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 time-out
values are 120 and 86400 seconds, respectively. If you specify a value of
X'FFFFFFFF' (-1), the maximum timeout value is used. The maximum value is
initialized to 86000 (24 hours). You can change these values with the
DEFAULTS command.
The following values are valid for SECONDS:
1 ... X
Where X is the maximum timeout value
0 Indicates the default time-out value
-1 Indicates the maximum timeout value
If you do not specify the SECONDS keyword when using the DSI6SNDS
macro for a REQUEST_WITH_REPLY, the default time-out value is used.
Otherwise, this field is required for REQUEST_WITH_REPLY.
SUPCORR
Is a varying length character field containing a complete unit of work

Chapter 8. Macros 263

DSI6SNDS

correlator (X'1549') GDS variable. The SUPCORR 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.
SUPCORR is not valid for an MDS-MU. If you use an existing unit of work or
create a new one, the MDS header must contain the unit of work and the
MDS-MU must be ready to be transmitted as supplied. An MNOTE is returned
if you specify this keyword for an MDS-MU.
SUPCORR is optional for NONMDSMU. For NONMDSMU, specify either
SUPCORR or CORAREA. The supplied value is used to build the MDS header
if you specify SUPCORR. No validity checking is done for a correlator
supplied by the caller. If an MDS reply or an MDS error message is sent,
specify SUPCORR because an MDS reply or error message must return the
correlator sent with the request. The invoking application must supply the
original correlator either in the MDS-MU or with the SUPCORR keyword.
You can specify the correlator name or a register containing a pointer to the
data.
SWB
Is the register, or symbolic name of a fullword area, containing the address of a
service work block (DSISWB).

Return Codes in Register 15

The following return codes for the DSI6SNDS macro are found in register 15:
0 Requested function was performed.
4 Task is terminating (TVBABEND/TVBLOGOF is on), and a
REQUEST_WITH_REPLY is sent.
24 No storage.
44 Send MU service is called in an asynchronous exit.
56 Time-out value is not valid.
88 MDS-MU length is not valid.
220 DSI6DST task inactive.
400 Data type is not valid.
404 DATA missing or is not valid.
408 MS application cannot send data to the same MS application within the
same NetView program.
416 MS application not registered.
420 Operations management served application not registered.
424 UOW missing or is not valid.
428 R&TI missing or is not valid.
432 Origin application name (OAN) missing or is not valid.
436 Destination application name (DAN) is not valid.
440 OAN is not valid.
444 Destination network ID missing or is not valid.
448 Destination LU name missing or is not valid.

264 Programming: Assembler

 DSI6SNDS

452 Destination application name missing or is not valid.

456 OII in R&TI does not match TVBOPID.
460 Reply is not valid.
464 Incorrect MUTYPE given.
472 User list is full.
548 Operations management served application cannot send data to the same
operations management served application within the same NetView
program.
556 The task does not have authorization to run the registered command
associated with the origin application name or OAN.
560 The operations management served application cannot send MDS error
message. Routing report is sent instead.
588 MDS error message does not have SNA Condition Report.
596 NETID is not available. The probable cause is that VTAM is not active.
1000 + x
The variable x is the return code from DSIMQS.
4000 + x
The variable x is the return code from DSIPUSH.
A return code of 24 or 28 from DSIPUSH indicates that DSIOLGFP is not
defined or is not defined properly in CNMCMD or its included members.
9000 + y
Reply command is not valid.
The variable Y is the return code from DSICES. Ensure that DSI6SNDS is
defined correctly in CNMCMD or its included members. If you specify a
reply command processor, ensure that it is also defined properly in
CNMCMD. If the sending application is an operations management served
application, make sure DSIOARCP is defined properly in CNMCMD.

Note:
1. For MUs sent within the same NetView program, the send services uses the
NetView LU name as the origin LU.
2. A request can time out in less than the specified interval if the receiving
partner has implemented a maximum time-out value of less than 24 hours, or
the one specified with the DEFAULTS command.
3. The parameter specified by SECONDS is either the variable name (timeout)
containing the time interval value, or the value itself.
4. Control is returned to the invoking program after DSI6SNDS successfully
queues the request to the MS transport.
5. For MDSMU, all fields within the MDS-MU header must be correct except for
origin NETID and LUNAME. The macro can determine and set these fields. If
the data does not contain the correlator, you must specify CORAREA.
6. For REPLY_ONLY, REPLY_NOTLAST, REPLY_LAST, and ERROR_MESSAGE,
you must specify SUPCORR to return the correlator sent with the request.
7. The MS transport implements a timeout value for the application receiving the
data. If the invocation of DSI6SNDS specifies a time-out value greater than the
time-out value set by the transport at the receiving node, the sending
application might time out in less than the specified interval.

Chapter 8. Macros 265

DSI6SNDS

8. When VTAM is active, you can use DSI6SNDS to send data to another
application in the same domain.
9. If DESTNET is not the NETID determined by VTAM for the LU specified in
DESTLU, the send fails.
10. An MS application or operations management served application cannot send
data to the same application within the same NetView system.

266 Programming: Assembler

Chapter 9. Called Service Routines
This chapter explains called service routines and lists interfaces for the assembler
language.

Overview of Called Service Routines

Called service routines are services that the NetView program provides. These
routines are similar to the ones provided by NetView macros (such as DSIPSS), but
they are called directly through branch and link. These routines adhere to standard
linkage conventions.

The called service routines are supported in both 24-bit and 31-bit addressability
mode. Use these routines in 31-bit mode whenever possible. Using 24-bit mode
uses more storage below the 16-megabyte line and increases system usage.

Upon routine entry, the registers contain the following information:

1 The address of a standard parameter list.
The list consists of addresses to parameter data. The parameter data is
specified by the individual routine descriptions. The end of the list must be
indicated by the last address having the high-order bit set to binary 1. All
other addresses must have that bit set to binary zero.
2–12 Unspecified.
13 The address of a standard 72-byte save area.
14 The return address at the time of the call.
15 The address of the service routine to be called. The DSISVL control block
typically has the addresses of the services defined in it.

On routine return, register 15 contains a return code. All other registers are
reserved.

In addition, fields defined by the service routine description in the parameter list
can be used for return values.

Free NetView Buffers Service Routine (DSIFREBF)

You can use this service routine to free NetView buffer structures, such as
automation internal function request buffers. This routine provides a method for
freeing a buffer structure without concern for the number of buffers that are
related. This is especially helpful for upgrading existing programs to handle the
structured automation internal function request (AIFRs) with DSIAIFRO
automation extensions.

You can also use this routine to free a chain of buffers that use HDRNEXTM as the
chaining field, provided the chain is terminated with a zero value in the last buffer.
If a buffer on the chain is an AIFR structure, all buffers chained to the AIFR
structure are freed, using all of the defined buffer pointers within the IFRAUTO
mapping.

© Copyright IBM Corp. 1997, 2015 267

DSIFREBF

The DSIFREBS macro is provided for calling DSIFREBF. By using DSIFREBS you
do not have to calculate the offset of DSIFREBF in the SVL.

The format for the DSIFREBS macro is:

LA 13,savearea
LA 1,plist Your parameter list
DSIFREBS Call DSIFREBF
LTR 15,15 Check for errors
BNZ ERROR

Where:
plist
Is a standard parameter list in the following format:
Word 1
The address of a fullword containing the TVB address for the task.
Word 2
The address of a fullword containing the address of the buffer chain to be
freed.
savearea
Is a standard 72-byte save area, usually at the start of the code.

Return Code
The following return code is for the DSIFREBF routine:
0 The requested function was performed.

Abend Code
The following abend code is for the DSIFREBF routine:
18 The DSIFREBF service was unable to free one of the chained buffers.

Note:
1. The DSIFREBF service routine requires that the parameter list contain 31-bit
addresses of the parameters. The address to be freed must be a valid 31-bit
address.
2. Buffers being freed must be in subpool zero, and they must be obtained with
the Q=NO option of DSIGET.
3. HDRNEXTM in the buffer to be freed is zero unless a chain of buffers is to be
freed.
4. The linkage registers of this routine are standard.

Process Message Data Block Routine (DSIMMDB)

This routine accepts an MDB and a source object, transforms them into an AIFR,
and processes the result as in normal NetView message processing. A source object
is optional, and you can indicate no source object by using an address of zero.
Also, specify a 16-byte field, which is used as a correlator value.

Any program in the NetView address space, except those running in an

asynchronous exit, can call the process message data block (MDB) service routine.
However, you cannot run this routine if TVBINXIT is on.

268 Programming: Assembler

 DSIMMDB

This service routine runs on the NetView task of the invoking program and returns
control to the caller after it scans the NetView automation table and after it
completes the synchronous portion of message processing.

The DSIMMDBS macro is provided for calling DSIMMDB. By using DSIMMDBS,

you do not have to calculate the offset of DSIMMDB in the SVL.

The format for the DSIMMDBS macro is:

LA 13,savearea
LA 1,plist Your parameter list
DSIMMDBS Call DSIMMDB
LTR 15,15 Check for errors
BNZ ERROR

Where:
plist
Is a standard parameter list in the following form:
Word 1
The address of a fullword containing the TVB address for the task.
Word 2
The address of a fullword containing the address of the MDB to be
processed.
Word 3
The address of a fullword containing the address of the source object. The
source object is optional. If you do not want to specify a source object,
Word 3 contains the address of a value of zero.
Word 4
The address of a fullword containing a 16-byte correlator field. This field
needs to be all binary zeros for a single MDB, or all binary zeros for the
first MDB of a set of related MDBs.
This field needs to be task reentrant, and enable DSIMMDB to write a
16-byte correlator value into it. For related MDBs, save this correlator value
and pass it back to DSIMMDB on each subsequently related MDB. When
an MDB is processed with an end-of-text indication, the correlator is
returned to you with a zero value.
savearea
Is a standard 72-byte save area, usually at the start of the code.

Return Codes
The following return codes are for the DSIMMDB macro:
0 The requested function was performed.
24 Storage was unavailable.
564 An error is detected in the correlation parameter. A diagnostic memory
dump of the MDB is written to the NetView log if the address of the MDB
is not zero. A diagnostic memory dump of the source object is written to
the NetView log if the address of the source object is not zero.
568 The first operand is not a valid MDB. A diagnostic memory dump of the
MDB is written to the NetView log if the address of the MDB is not zero.
Additionally, a diagnostic memory dump of the source object is written to
the NetView log if the address of the source object is not zero.

Chapter 9. Called Service Routines 269

DSIMMDB

572 The second operand is not a valid source object. A diagnostic memory
dump of the MDB is written to the NetView log if the address of the MDB
is not zero. Additionally, a diagnostic memory dump of the source object is
written to the NetView log if the address of the source object is not zero.

Note:
1. This service does not free the MDB or source object.
2. Use the MVS control block IEAVM105 as a guide for building your MDB.
3. To chain related MDBs, use the correlator parameter (Word 4) to DSIMMDB in
place of the IEAVG132 map.
4. If IEAVM105 is not available, you can use parts of the DSIAIFRO map to build
your MDB, as follows:
a. Begin your MDB at DSIMGO level.
b. Change the type code for DSIMGO to X'0001' to indicate that this is an
incoming MDB.
c. Include one DSICPO, one DSIGOJ, and as many DSITOJ objects as needed
to contain your text.
5. The first character in your text object is discarded; it cannot be a meaningful
part of your message. The second character is discarded if both of the
following conditions exist:
The character is a plus sign (+)
MDBCAUTH (CPOCAUTH) is set on (set to 1).
6. MDBs created using this service routine are submitted directly to the NetView
program; the operating system is not involved in the processing or routing of
the MDB. Therefore, items that are normally subject to MVS system routing
(such as console name and route code) are ignored; the MDB is delivered only
to the task that calls the service routine.
7. When creating DOM MDBs, be aware that not all forms of DOM can be
transported over OST-NNT sessions. When using those sessions, only create
DOM MDBs that indicate DOM by MSGID.

For detailed information about MDB formats, refer to the description of MDB in
the z/OS library.

270 Programming: Assembler

Appendix A. Assembler Samples
This appendix provides a table of the assembler samples that are shipped as part
of the NetView sample library. These samples are distributed as members of the
CNMSAMP data set.

Each sample described in this section has two names, such as ATMPCMDP
(CNMS4202). The CNM name is the name under which the file or member is
distributed on the sample library tape. The first name is a more meaningful alias
name to which the CNM file is copied during installation.

Follow these steps to enter the member names as commands:

v Assemble and link edit the samples using the alias name.
v Delete the asterisk (*) in column 1 of the appropriate CMDDEF statement in
CNMCMD or its included members so you can issue the alias name as a
command. No entries are needed in CNMCMD for installation exits.
v Recycle the NetView program to enable the CNMCMD changes.

This appendix also contains a description of each sample. The last section provides
coded examples of an installation exit routine, a command processor, a
user-written function, and a user-written optional subtask.

Note:
1. Refer to the prologs of the samples for information about how certain samples
are related and about special cases for installation exit routines and other
samples (such as DSIUSR00).
2. The alias name is the control section (CSECT) name.

Assembler Samples Reference Table

Table 49 shows the assembler language samples that are shipped with the NetView
product. The table contains the function, the alias name, and the name of the
member in NETVIEW.V6R2M1.CNMSAMP.
Table 49. Assembler Language Samples Shipped with NetView
Assembler CNMSAMP
Alias Member Sample Function
AAUTOTB CNMS4291 Sends MSU to automation table
ABLDMSG CNMS4278 Uses DSIMBS to build messages
ACALLCMD CNMS4280 Calls another command
ADATTIM CNMS4274 Uses DSIPSS to display date and time
AGETDS CNMS4294 DSIGETDS sample command processor
AHREGSTR CNMS4296 Register/deregister an application to the LU 6.2
high-performance transport
AHSNDMU CNMS4286 Sends an alert through the LU 6.2 high-performance
transport
ALERTMSG CNMS4284 Creates a customizable message for automation
ALISTMEM CNMS4276 Lists a member of DSIPARM

© Copyright IBM Corp. 1997, 2015 271

Assembler Samples

Table 49. Assembler Language Samples Shipped with NetView (continued)

Assembler CNMSAMP
Alias Member Sample Function
AMLWTO CNMS4273 Uses DSIPSS for title-line output
AMSGMOD CNMS4271 Uses DSIMDS to build a message module
AOPTTSK CNMS4277 User-written optional subtask
APRSMDB CNMS4299 Example usage of process MDB service
APSSFULL CNMS4279 Uses DSIPSS to display a full-screen panel
AREGISTR CNMS4292 LU 6.2 register/deregister application
ARODMCON CNMS4290 Uses CNMQAPI to access RODM
ASENDMU CNMS4293 Sends alert to ALERT_NETOP
ASEQLOG CNMS4275 Logs text to a sequential log
ATMPCMDP CNMS4202 Template for assembler command processor
ATMPUXIT CNMS4282 Template for assembler installation exit
AUSRFUNC CNMS8002 Example of a REXX user-written function
AWRTLOG CNMS4272 Uses DSIWLS to write a message to the NetView log
AXITVN CNMS4270 Defines an XITVN DST exit to initialize an empty VSAM
data set
CNMRECV CNMS4289 Receives data buffers from a receiver's queue
CNMSEND CNMS4288 Sends a data buffer to a receiver
CNMSGENA CNMS4287 Generic alert sender application
CNMSMF3E Sample IEFACTRT SMF exit
CNMSMF3F SMF record type 30 automation
DSICTMOD CNMS0055 Specifies NetView constants such as timeout values and
sense code filtering
DSIEX02A CNMS4283 Uses DSIEX02A to manipulate messages
DSIEX17 CNMS4297 Manipulates message IEF233A and its associated DOM
DSIEX18 CNMS4298 Template for coding a DSIEX18 installation exit
DSIEX19 CNMS4307 Provides command authority checking for the RUNCMD
command
DSIEX20 CNMS4308 Allows filtering of session awareness (SAW) data
DSIEX21 Provides an example of a DSITCPRF encryption
installation exit
DSIRXPRM CNMSJM11 Specifies the NetView REXX environment initialization
parameters. As of NetView V6R2, use
REXX.FUNCPKGLIST statements (for function package
names) and REXX.CMDENV statements (for command
environments) in the CNMSTYLE (CNMSTUSR or
CxxSTGEN) member; for more information, see the
Administration Reference.
DSIUSR00 CNMS4281 User-defined message member
OPERID CNMS4295 Sample automation table function (ATF)

272 Programming: Assembler

 Assembler Samples

Assembler Samples Description

Each sample provides a description of the function and the NetView service
macros that are used.
AAUTOTB (CNMS4291)
This sample sends an MSU to the automation table for evaluation. The
NetView service macros used in this sample are DSICBS, DSIAUTO, and
DSIPSS.
ABLDMSG (CNMS4278)
This sample uses DSIMBS to build user-defined messages. The NetView
service macros used in this sample are DSICBS, DSIDATIM, DSIDEL,
DSILOD, DSIMBS, and DSIPSS.
ACALLCMD (CNMS4280)
This sample calls another command processor. The NetView service macros
used in this sample are DSICBS, DSICES, DSIDATIM, DSIFRE, DSIGET,
DSILCS, and DSIPRS.
ADATTIM (CNMS4274)
This sample uses DSIPSS to display date and time. The NetView service
macros used in this sample are DSICBS, DSIDATIM, and DSIPSS.
AGETDS (CNMS4294)
This sample issues DSIGETDS to retrieve an MSU pointed to by TVBAIIFR.
The NetView service macros used in this sample are DSICBS, DSIDATIM,
DSIGETDS, and DSIPSS.
AHREGSTR (CNMS4296)
This sample registers or deregisters an application as an LU 6.2 high
performance application. The NetView service macros used in this sample
are DSICBS, DSIPSS, DSI6REGS.
AHSNDMU (CNMS4286)
This sample sends a software alert from a registered LU 6.2
high-performance application. The NetView service macros used in this
sample are DSICBS, DSIPSS, DSI6SNDS.
ALERTMSG (CNMS4284)
This sample creates a customizable message for automation from generic
and nongeneric network major vector transport alerts.
The prolog of CNMS4284 contains installation directions and customization
guidelines. The DSTINIT statements of CNMS4284 show how to install the
sample on the XITCI installation exit of the BNJDSERV task. The NetView
macros used in this sample are DSIBAM, DSIBAMKW, DSISRCMV, and
DSICVTHE.
ALISTMEM (CNMS4276)
This sample reads and displays a member from the NetView DSIPARM
data set. It also does command authorization checking for the supplied
parm member name to prevent unauthorized display of DSIOPF. The
NetView service macros used in this sample are DSICBS, DSIDATIM,
DSIDKS, DSIKVS, and DSIPSS.
AMLWTO (CNMS4273)
This sample uses DSIPSS for title-line output. The NetView service macros
used in this sample are DSICBS, DSIDATIM, and DSIPSS.
AMSGMOD (CNMS4271)
This sample uses the message definition services (DSIMDS) to build a

Appendix A. Assembler Samples 273

Assembler Samples

user-defined message module (AMSGMOD). It is used with the ABLDMSG

sample command processor and DSIEX02A. The NetView service macro
used in this sample is DSIMDS.
AOPTTSK (CNMS4277)
This sample is an example of a user-written optional subtask.
This template is available as part of the NetView sample library. It can be
found as member CNMS4277 of the CNMSAMP data set.
APRSMDB (CNMS4299)
This sample shows how to build an MDB with a source object and submit
it to NetView for processing.
APSSFULL (CNMS4279)
This sample uses DSIPSS to display a full-screen panel, wait for terminal
input, and echo the input. The NetView service macros used in this sample
are DSICBS, DSIFRE, DSIGET, DSIPSS, and DSIWAT.
AREGISTR (CNMS4292)
This sample registers or deregisters an application as an MS application or
as an operation management served application. The NetView service
macros used in this sample are DSICBS, DSIPSS, and DSI6REGS.
ARODMCON (CNMS4290)
This sample invokes CNMQAPI, which enables access RODM under the
control of NetView. The coded example shows a RODM CONNECT
function. The NetView service macros used in this sample are DSICBS and
DSINOR.
ASENDMU (CNMS4293)
This sample sends a software alert to ALERT_NETOP from a registered MS
application named USERAPPL. The NetView service macros used in this
sample are DSICBS, DSIPSS, and DSI6SNDS.
ASEQLOG (CNMS4275)
This sample logs text to a sequential log. The NetView service macros used
in this sample are DSICBS, DSIDATIM, DSIMQS, DSIPSS, and DSIWLS.
ATMPCMDP (CNMS4202)
This sample is a template for command processors in the assembler
language. This sample is included in “Template for a Command Processor”
on page 76.
ATMPUXIT (CNMS4282)
This sample is a template for assembler installation exits. See “Template for
an Installation Exit Routine” on page 57
AUSRFUNC (CNMS8002)
This sample is an example of a user-written REXX function. The example
returns the character string “Hello World” to the calling REXX command
list. It shows entry linkage, allocates an SWB, sets up a result, issues
DSIRXEBS to obtain a new evaluation block, returns the result to the caller,
and frees the SWB and all other temporary storage. The DSIRXEBS is
necessary only when the evaluation block that was passed on entry is too
small to contain the result. DSIRXEBS is in the example only to show a
sample usage. Also, the SWB is needed only if a NetView service call is
generated.

274 Programming: Assembler

 Assembler Samples

AWRTLOG (CNMS4272)
This sample uses DSIWLS to write a message to the NetView log. The
NetView service macros used in this sample are DSICBS, DSIDATIM, and
DSIWLS.
AXITVN (CNMS4270)
This sample is an XITVN DST exit. It provides the initial record for an
empty VSAM data set. The NetView service macros used in this sample
are DSICBS and DSIDATIM.
CNMRECV (CNMS4289)
This sample receives data buffers from the receiver buffer's queue. The
NetView service macro used in this sample is DSISYS.
CNMSEND (CNMS4288)
This sample sends a data buffer to a receiver using the NetView
program-to-program interface.
CNMSGENA (CNMS4287)
This sample sends a generic alert to the NetView program using the
NetView program-to-program interface.
CNMSMF3E
This sample IEFACTRT SMF exit sends selected type 30 SMF records (job
step events) to the main NetView address space for automation.
CNMSMF3F
This sample formats selected type 30 SMF records (received from the
CNMSMF3E exit) into a BNH874I multiline message for automation.
DSICTMOD (CNMS0055)
This sample specifies a wide range of constants for the NetView program.
You can specify timeout values for many functions such as hardware
monitor, trace NCP command, view requests, and RUNCMDs. You can
specify retry intervals for functions such as status collector, RTM, and
WTORs. You can specify message queue thresholds, heap sizes, and sense
code filtering. Refer to the sample module for a complete list of constants.
DSIEX02A (CNMS4283)
This sample is used to manipulate messages. The installation exit is
invoked for standard output to the operator's terminal. If DWO403I is the
incoming message, it issues DSIMQS to start the task specified in
DWO403I and swaps the message buffer to indicate that the task has been
started and that the request can be reissued.
NetView service macros used in this sample are DSICBS, DSIDEL, DSIFRE,
DSIGET, DSILCS, DSILOD, DSIMBS, DSIMQS, and DSIPRS.
DSIEX17 (CNMS4297)
This installation exit is invoked upon receipt of MVS messages and delete
operator messages (DOMs) and is called before automation or ASSIGN
processing.
CNMS4297 manipulates message IEF233A and its associated DOM.
IEF233A is a held message displayed upon receipt of an MVS MOUNT
request. When the MOUNT request is honored, a DOM is issued to delete
the held message.
The intent of this sample is to provide a logged message that includes the
MOUNT request, the time that it was received, and the time that it was
honored.

Appendix A. Assembler Samples 275

Assembler Samples

CNMS4297 also shows how to invoke DSIFREBS to delete a message so

that it is not propagated for further processing.
The following list shows the NetView service macros used in this sample:
DSICBS
DSIDATIM
DSIFRE
DSIGET
DSILCS
DSIPRS
DSIVARS
DSIWLS
Assembler language called service routine DSIFREBF is also used in the
sample.
DSIEX18 (CNMS4298)
This sample is an installation exit that works with BROWSE NETLOG and
BLOG requests:
v When a user enters a BROWSE NETLOGx request, this exit processes
every record which is read from the network log as the operator
interacts with the log.
v When a user enters a BLOG request, BLOG filtering is first processed
internally for every record that is read from the network log as the
operator interacts with the log. Next, any records that are permitted for
display by BLOG filtering are passed to DSIEX18.
As shipped, this sample provides no additional filtering. It must be
modified before being used.
DSIEX19 (CNMS4307)
This sample is an example of a RUNCMD security checking exit. This
sample checks various commands that are embedded within a RUNCMD
command. The checking is done using the DSICES and DSIKVS macros.
DSIEX20 (CNMS4308)
This sample is an installation exit that allows filtering of session awareness
(SAW) data received from VTAM by the session monitor. The filtering
takes place prior to the filtering associated with a KEEPMEM statement
(KCLASS and MAPSESS definitions).
DSIEX21
This sample is an example of a DSITCPRF encryption installation exit.
Refer to the IBM Tivoli NetView for z/OS Security Reference for more
information.
DSIRXPRM (CNMSJM11)
This sample contains the TSO/E REXX initialization parameters used by
the NetView program for NetView REXX support. The sample includes the
TSO/E REXX parameter block, module name table, subcommand table,
and function package table. It also includes JCL, which must be modified,
to assemble and link edit the NetView REXX parameters into a NetView
load library. The sample can be modified (except as noted in the sample) to
suit the needs of your installation.

Note: As of NetView V6R2, use REXX.FUNCPKGLIST statements (for

function package names) and REXX.CMDENV statements (for command

276 Programming: Assembler

 Assembler Samples

environments) in the CNMSTYLE (CNMSTUSR or CxxSTGEN) member;

for more information, see the Administration Reference.
DSIUSR00 (CNMS4281)
This sample is an example of a user-defined message member. It is used in
conjunction with the ABLDMSG sample command processor.
OPERID (CNMS4295)
This sample is an example of an automation table function (ATF). It can be
called from a NetView automation table, and returns the operator ID of the
NetView task that is automating a message or an MSU. See Appendix C,
“Writing an Automation Table Function,” on page 287 for more
information about ATFs.

Note: For more information about CNMRECV(CNMS4289),

CNMSEND(CNMS4288), and CNMSGENA(CNMS4287), refer to the IBM Tivoli
NetView for z/OS Application Programmer's Guide.

Appendix A. Assembler Samples 277

Assembler Samples

278 Programming: Assembler

Appendix B. MDB Field to AIFR Cross-Reference Table
This appendix provides a cross-reference table for MDB control block fields. The
MDB fields are listed in control block order and cross-referenced to existing
automation internal function request (AIFR) fields.
Table 50. MDB to AIFR Field Cross-Reference Table
MDB Control Block BUFHDR, IFRAUTO,
Field Description or DSIAIFRO field
Note: The following fields support full WTO attributes.
MDBGMID 4-byte message ID field; decimal GOJGMID
MDBGSYID 1-byte system ID; decimal GOJGSYID
MDBGSEQ 3-byte sequence number; decimal GOJGSEQ
MDBGTIMH 8-character time in the format of: hh.mm.ss GOJGTIMH
MDBGTIMT 3-character time in the format of: .th GOJGTIMT
MDBGDSTP 7-character date stamp in the format of: yyyyddd GOJGDSTP
MDBGMFLG(nn) 2-byte flags GOJGMFLG
MDBGMFLG(1) This is a DOM IFRAUDOM
MDBGDOM IFRAUWDO
GOJGDOM
MDBGMFLG(2) Sound processor alarm GOJGALRM
MDBGALRM
MDBGMFLG(3) Hold message until DOM or otherwise deleted GOJGHOLD
MDBGHOLD
MDBGFGPA 4 characters of foreground presentation attributes GOJGFGPA
MDBGFGPA(1) Foreground control field GOJGFCON
MDBGFCON
MDBGFGPA(2) Foreground color field GOJGFCOL
MDBGFCOL
MDBGFGPA(3) Foreground highlighting GOJGFHIL
MDBGFHIL
MDBGFGPA(4) Foreground intensity GOJGFINT
MDBGFINT
MDBGBGPA 4 characters of background presentation attributes GOJGBGPA
MDBGBGPA(1) Background control field GOJGBCON
MDBGBCON
MDBGBGPA(2) Background color field GOJGBCOL
MDBGBCOL
MDBGBGPA(3) Background highlighting GOJGBHIL
MDBGBHIL
MDBGBGPA(4) Background intensity GOJGBINT
MDBGBINT
MDBGOSNM Originating system name IFRAUWSN

GOJGOSNM

© Copyright IBM Corp. 1997, 2015 279

MDB Field to AIFR Cross-Reference Table

Table 50. MDB to AIFR Field Cross-Reference Table (continued)

MDB Control Block BUFHDR, IFRAUTO,
Field Description or DSIAIFRO field
MDBCOJBN Job name IFRAUWJA

CPOCOJBN
MDBCPROD 16-byte SCP product level CPOCPROD
4-character MVS CP object version level
4-character control program name
8-character FMID of originating system
MDBCERC 128 bits routing codes IFRAUWRT

CPOCERC
MDBCDESC 2-byte descriptor codes IFRAUWDS

CPOCDESC
MDBDESCA System failure IFRAUWDS

CPOCDESC
MDBDESCB Immediate action required IFRAUWDS

CPOCDESC
MDBDESCC Eventual action required IFRAUWDS

CPOCDESC
MDBDESCD System status IFRAUWDS

CPOCDESC
MDBDESCE Immediate command response IFRAUWDS

CPOCDESC
MDBDESCF Job status IFRAUWDS

CPOCDESC
MDBDESCG Application program/processor DOM at end of task IFRAUWDS

CPOCDESC
MDBDESCH Out-of-line IFRAUWDS

CPOCDESC
MDBDESCI Operator's request IFRAUWDS

IFRAUMCS(3)

CPOCDESC
MDBDESCJ Track command response IFRAUWDS

CPOCDESC
MDBDESCK Critical eventual action IFRAUWDS

CPOCDESC
MDBDESCL Delivered but not held IFRAUWDS

CPOCDESC

280 Programming: Assembler

 MDB Field to AIFR Cross-Reference Table

Table 50. MDB to AIFR Field Cross-Reference Table (continued)

MDB Control Block BUFHDR, IFRAUTO,
Field Description or DSIAIFRO field
MDBDESCM NetView automation table had opportunity to process this message IFRAUWDS
before the WTO was issued
CPOCDESC
MDBDESCN Reserved None

MDBDESCO

MDBDESCP
MDBCMLVL Message level flags CPOCMLVL
MDBCMLVL(1) WTOR IFRAUWWR
MDBMLR
CPOMLR
MDBCMLVL(2) Immediate action IFRAUWDS(2)
MDBMLIA
CPOMLIA
MDBCMLVL(3) Critical eventual action IFRAUWDS(11)
MDBMLCE
CPOMLCE
MDBCMLVL(4) Eventual action IFRAUWDS(3)
MDBMLE
CPOMLE
MDBCMLVL(5) Informational CPOMLI
MDBMLI
MDBCMLVL(6) Broadcast IFRAUWBD
MDBMLBC
IFRAUMCS(6)

CPOMLBC
MDBCMLVL(7) Reserved None
MDBCMLVL(8)
MDBCMLVL(9)
MDBCMLVL(10)
MDBCMLVL(11)
MDBCMLVL(12)
MDBCMLVL(13)
MDBCMLVL(14)
MDBCMLVL(15)
MDBCMLVL(16)
MDBCATTR 2-byte message attributes CPOCATTR
MDBCATTR(1) Reserved None
MDBCATTR(2) Message is command response IFRAUMCS(3)
MDBCMCSC
CPOCMCSC
MDBCATTR(3) Message issued by authorized program CPOCAUTH
MDBCAUTH
IFRAUPLS
MDBCATTR(4) Message is to be retained by AMRF CPOCRETN
MDBCRETN

Appendix B. MDB Field to AIFR Cross-Reference Table 281

MDB Field to AIFR Cross-Reference Table

Table 50. MDB to AIFR Field Cross-Reference Table (continued)

MDB Control Block BUFHDR, IFRAUTO,
Field Description or DSIAIFRO field
MDBCATTR(5) Reserved None
MDBCATTR(6)
MDBCATTR(7)
MDBCATTR(8)
MDBCATTR(9)
MDBCATTR(10)
MDBCATTR(11)
MDBCATTR(12)
MDBCATTR(13)
MDBCATTR(14)
MDBCATTR(15)
MDBCATTR(16)
MDBCPRTY 2-byte message priority; decimal CPOCPRTY
MDBCRETN AMRF retained message CPOCRETN

IFRAURET
MDBCRRET Retain in AMRF CPOCRRET

IFRAURRT
MDBCRNRT Do no retain in AMRF CPOCRNRT

IFRAUNRT
MDBCASID ASID of issuer; decimal IFRAUASI

IFRAUWAS

CPOCASID
MDBCTCB TCB address of issuer IFRAUTCB

4-byte hexadecimal IFRAUWJT

CPOCTCB
MDBCTOKN 4-byte DOM token associated with message; decimal CPOCTOKN
MDBCSYID 1-byte system ID (for DOM); decimal CPOCSYID
MDBDOMFL 1-byte DOM flags CPODOMFL
MDBDOMFL(1) DOM by message ID MSGDOMAT
MDBDMSGI
IFRAUWDT

IFRAUWDA

CPODMSGI
MDBDOMFL(2) DOM by system ID CPODSYSI
MDBDSYSI
MDBDOMFL(3) DOM by ASID IFRAUWDT
MDBDASID
IFRAUWDA

CPODASID

282 Programming: Assembler

 MDB Field to AIFR Cross-Reference Table

Table 50. MDB to AIFR Field Cross-Reference Table (continued)

MDB Control Block BUFHDR, IFRAUTO,
Field Description or DSIAIFRO field
MDBDOMFL(4) DOM by job step TCB IFRAUWDT
MDBDJTCB
IFRAUWDA

CPODJTCB
MDBDOMFL(5) DOM by token IFRAUWDT
MDBDTOKN
IFRAUWDA
MDBDTOKN
MDBCMISC 1-byte miscellaneous routing information CPOCMISC
MDBCMISC(1) Display UD messages CPOCUD
MDBCUD
MDBCMISC(2) Display only UD messages CPOCFUDO
MDBCFUDO
MDBCMISC(3) Queue by ID only CPOCFIDO
MDBCFIDO
MDBCOJID 8-character originating job ID IFRAUWJU

CPOCOJID
MDBCKEY 8-byte key associated with message CPOCKEY

8 bytes of hexadecimal or character value

MDBCAUTO 8-byte MPF automation token CPOCAUTO

Character
MDBCCART 8-byte command and response token CPOCCART

8 bytes of hexadecimal or character value

MDBCCNID MVS target console (4 bytes); decimal CPOCCNID

Use CONVCON to find 8-character console name, save in IFRAUCON

IFRAUCON
MDBCMSGT 16-bit message type CPOCMSGT
MDBCMSGT(1) Display job names IFRAUWF1(9)
MDBMSGTA
CPOMSGTA
MDBCMSGT(2) Display status IFRAUWF1(10)
MDBMSGTB
CPOMSGTB
MDBCMSGT(3) Monitor active CPOMSGTC
MDBMSGTC
MDBCMSGT(4) Indicates existence of QID field in WPL (AOS/1) CPOMSGTD
MDBMSGTD
MDBCMSGT(5) Reserved None
MDBCMSGT(6) Monitor SESS IFRAUWF1(14)
MDBMSGTF
CPOMSGTF

Appendix B. MDB Field to AIFR Cross-Reference Table 283

MDB Field to AIFR Cross-Reference Table

Table 50. MDB to AIFR Field Cross-Reference Table (continued)

MDB Control Block BUFHDR, IFRAUTO,
Field Description or DSIAIFRO field
MDBCMSGT(7) Reserved None
MDBCMSGT(8)
MDBCMSGT(9)
MDBCMSGT(10)
MDBCMSGT(11)
MDBCMSGT(12)
MDBCMSGT(13)
MDBCMSGT(14)
MDBCMSGT(15)
MDBCMSGT(16)
MDBCRPYL 2-byte reply ID length; decimal CPOCRPYL
MDBCRPYI 8-character reply ID CPOCRPYI
MDBCTOFF Offset in the message text field of the beginning of the message CPOCTOFF

(Internal field, no external variable.)

MDBCRPYB 4-byte binary reply ID CPOCRPYB
MDBCLCNT 2-byte count of number of lines in message; decimal CPOCLCNT
Note: CPOCLCNT and MDBCLCNT are not supported by the
NetView program. The count of buffers on the IFRAUTBA chain is
used instead. GETMSIZE provides this function.
MDBCOJBN 8-character originating job name CPOCOJBN
MDBTLEN 2-byte text object length HDRTLEN
MDBTTYPE 2-byte text object type flags HDRLNTYP in each
data buffer

HDRTTYPE
MDBTTYPE(1) Control text HDRLNCTL
MDBTCONT HDRTCONT
MDBTTYPE(2) Label text HDRLNLBL
MDBTLABT HDRTLABT
MDBTTYPE(3) Data text HDRLNDAT
MDBTDATT HDRTDATT
MDBTTYPE(4) End text HDRLNEND
MDBTENDT HDRTENDT
MDBTTYPE(5) Prompt text HDRTPROT
MDBTPROT
MDBTTYPE(6) Reserved None
MDBTTYPE(7)
MDBTTYPE(8)
MDBTTYPE(9)
MDBTTYPE(10)
MDBTTYPE(11)
MDBTTYPE(12)
MDBTTYPE(13)
MDBTTYPE(14)
MDBTTYPE(15)
MDBTTYPE(16) Text object presentation field overrides general object presentation HDRTFPAF
MDBTFPAF attribute field
MDBTMTPA 4-byte presentation attributes HDRTMTPA

284 Programming: Assembler

 MDB Field to AIFR Cross-Reference Table

Table 50. MDB to AIFR Field Cross-Reference Table (continued)

MDB Control Block BUFHDR, IFRAUTO,
Field Description or DSIAIFRO field
MDBTMTPA(1) Presentation control HDRTPCON
MDBTPCON
MDBTMTPA(2) Presentation color HDRTPCOL
MDBTPCOL
MDBTMTPA(3) Presentation highlighting HDRTPHIL
MDBTPHIL
MDBTMTPA(4) Presentation intensity HDRTPINT
MDBTPINT
MDBTMSGT Variable length message text Message text is in
buffers chained from
IFRAUTBA and
IFRAUTBL
Note: The following fields and flags from WQE are not mapped by MDB, are set to zero (0), and generally apply to
how the write-to-operator switch virtual circuit (WTO SVC) was issued and not to what the message is about.
Suppressed message; bit is always set to zero (0) IFRAUWSP
1
Routing and Descriptor codes exist; inferred from other data IFRAUMCS(1)
Queue conditionally to REG0 console; bit is always set to zero (0) IFRAUMCS(2)
1
Message type flag field exists; can be inferred from other data IFRAUMCS(4)
Message is reply to WTOR; bit is always set to zero (0) IFRAUMCS(5)
Queue to hardcopy only; bit is always set to zero (0) IFRAUMCS(7)
Queue unconditionally to console in REG0; bit is always set to zero IFRAUMCS(8)
(0)
No time stamp; bit is always set to zero (0) IFRAUMCS(9)
Do not log minor WQEs; bit is always set to zero (0) IFRAUMCS(11)
Extended WPL exists; bit is always set to zero (0) IFRAUMCS(12)
Bypass queue to hardcopy; bit is always set to zero (0) IFRAUMCS(14)
WQEBLK keyword specified; bit is always set to zero (0) IFRAUMCS(15)
Note:
1. Fields indicated as inferred mean that fields from earlier releases of the NetView program must be set by testing
the values of other fields. For example, if at least one route code is nonzero, set the route-codes included flag to
ON.

Appendix B. MDB Field to AIFR Cross-Reference Table 285

MDB Field to AIFR Cross-Reference Table

286 Programming: Assembler

Appendix C. Writing an Automation Table Function
This section describes how to design, code and install an assembler language
automation table function (ATF) for the NetView program. You can write an ATF
to evaluate a complex condition and return a value to automation table processing.
An ATF is useful for gaining access to message, management services unit (MSU),
or MSU hierarchy information that cannot be accessed directly from the
automation table.

Overview of Automation Table Function

An ATF conditional performs a module call from the automation table. An ATF
module has the option of returning data to be compared against a value in the
automation table statement to make synchronous automation decisions. Data
returned by an ATF module can also be passed by the automation table to a
command or a command list. The ATF conditional can be contained in IF-THEN
automation statements.

The syntax of an ATF conditional is:

►► ATF ( ' modname ' ) = value ►◄

BIT parameterlist

Where:
BIT
Specifies that the automation table is bit data.
modname
Specifies a 1- to 8-character load module name.
parameterlist
Specifies the parameter list to be passed to modname.
value
Specifies the value that the automation table uses to compare with the value
returned by modname, if any.

The ATF module gets control only if the automation table scans to that statement.
Because performance can be affected negatively, IF-THEN statements that contain
ATF module calls cannot be executed with each scan of the automation table. Place
these IF-THEN statements within BEGIN-END sections to prevent unnecessary
calls.

ATF resembles a function as defined in REXX and, from the automation table
language perspective, ATF is a function that calls functions.

Note: Refer to the IBM Tivoli NetView for z/OS Automation Guide for more
information about the IF-THEN statement and ATF syntax.

© Copyright IBM Corp. 1997, 2015 287

Writing an Automation Table Function

Designing and Coding an ATF Module

ATF modules must adhere to the guidelines for user-written programming
described in “General Coding Guidelines” on page 4. In addition, ATF modules
must conform to the special requirements described in this section.

Note: A sample ATF module OPERID (CNMS4295) is provided with the NetView
program. You can use it as pattern when coding your own ATFs.

Input to and Output from the ATF

When the ATF module gains control, the registers contain the following
information:
0 Unspecified
1 The address of an 8-byte parameter list that contains:
1. A 4-byte address of a command work block (CWB)
The CWB contains the following values:
v A user save area (CWBSAVEA) that is the ATF 72-byte save area.
v The address of the command buffer (CWBBUF) in which the
NetView program loads the command string. The buffer has a
standard BUFHDR.
v The address of a service work block (CWBSWB) for calling service
facilities.
v The address of the task information block (CWBTIB).
v A work area (CWBADATD) that is the ATF 256-byte temporary
storage for keeping variables while remaining reentrant.
2. The 4-byte address of the AIFR being automated
13 The address of a standard 72-byte save area used to store the caller's
registers.
14 The return address
15 The entry address of the ATF module
2-12 Unspecified

The AIFR being automated can contain either a message or an MSU buffer. See
Figure 18 on page 290 for an example of the parameter list and of control blocks
and their relevant pointers.

For bit string functions, the first byte of the returned value from ATF must contain
the first bit needed for the evaluation. The bit string on the right side of the equal
sign specifies X for any bit positions whose value is irrelevant to the evaluation.

For example, if ATF must determine whether the third and fourth bits of a byte are
B'01', you can code this as:
IF ATF (BIT ’pname ....’) = ’XX01’ THEN ....;

You can also write the pname to shift the bits so that leading Xs are not needed.
This does not affect the NetView program as long as the pname design is
coordinated with the automation entry.

When the NetView program regains control, the registers and their contents are as
follows:

288 Programming: Assembler

 Writing an Automation Table Function

15 A return code:
0 Normal
1-8 ATF-detected error
>8 Unexpected error
0-14 Restored to caller's contents

The ATF module replaces the command string, found in the buffer pointed to by
CWBBUF, with the value to be compared to the right side of the equal sign on the
automation table IF-THEN statement. The maximum size of the returned data is
limited to 256 bytes minus the length of the BUFHDR. The ATF places the actual
length of the returned data in HDRMLENG. If you put zero in HDRMLENG, a
null value is returned.

To extract more data, you can use multiple ATF invocations from one automation
table statement.

Do not return a swapped buffer, because the buffer that the NetView program
provides is the maximum size supported.

ATF return codes 1–8 causes a false ATF comparison. Return codes greater than 8
can also cause a false ATF comparison. Error message CNM588E is issued for
return codes greater than 8. In an operator station task, the error message is sent to
the operator. In a data services task (DST) or optional subtask (OPT), the error
message is sent to the operator that started the DST or OPT, if one exists.
Otherwise, it is sent to the authorized receiver. You see the return code only if it is
greater than 8 (which results in an error message containing the return code).

Note:
1. Do not pass a return code greater than 8 unless you want to indicate a severe
error from the ATF module.
2. Freeing the buffer passed to ATF causes an abend.

Control Blocks
An ATF module has access to the command buffer and these control blocks:
v AIFR
v DSICWB
v DSISWB
v DSITVB
v DSITIB
v DSIMVT
v DSISVL

Appendix C. Writing an Automation Table Function 289

Writing an Automation Table Function

Register 1

Parameter List

CWB @
CWB
AIFR @

CBH

CWBBUF BUFHDR Command String

CWBSAVEA

CWBTIB

CWBSWB
AIFR CWBADATD

BUFHDR

IFRCODE

IFRAUTBA BUFHDR Message or MSU data

IFRAUTBL

BUFHDR Message or MSU data

BUFHDR Message or MSU data

Figure 18. Control Blocks Used by ATF Modules

Installing an ATF module

Link edit the ATF load module into the NetView load library. Code an automation
table IF-THEN statement specifying your ATF module name and other required
information. Refer to the IBM Tivoli NetView for z/OS Automation Guide for
information about coding an IF-THEN statement. Use the AUTOTBL command to
activate your automation table. Refer to the NetView online help for information
about the AUTOTBL command. ATF modules coded in the automation table are
loaded when the automation table is activated by the AUTOTBL command. You do
not need to recycle the NetView program to be able to use an ATF load module
when it is added to the NetView load library.

You can add new ATF modules (using link-editing) and activate them (using the
AUTOTBL command) while the NetView program is running, even if automation
was previously in effect. To change an existing ATF module that is already loaded,
you have four alternatives:

290 Programming: Assembler

 Writing an Automation Table Function

1. Rename the ATF module using link-editing, change the corresponding ATF
name or names in the automation table, and reissue the AUTOTBL command.
2. Stop the NetView program and restart it.
3. Deactivate the ATF module using the AUTOTBL OFF command. Wait for a
CNM593I message to be issued to ensure that all existing ATF modules are
deleted, then reissue the AUTOTBL command to put the modules back into
effect.
4. If it is not practical to shut off automation, issue the AUTOTBL command with
a substitute member. Wait for the current automation process to finish using the
ATF module. Run a command processor to delete one or more modules, and
then reissue the AUTOTBL command with the main member.

When the AUTOTBL command processing abends because of a STOP FORCE or a

RESET IMMED command, all of the ATF modules cannot be deleted, even if a
CNM593I message is received. If one of these situations exists, you can run a
command processor to delete one or more modules before reissuing the AUTOTBL
command to make sure the old modules of the same name that you are replacing
are deleted.

Points to Remember
When you write ATF modules, remember the following points:
v Write them in assembler language.
v Do not define them in CNMCMD or its included members.
v They cannot be called as commands.
v They are different from NetView commands. Do not invoke them outside the
automation table. Do not code NetView commands as modules.
v Define it as being a reentrant load module (by the name to be referenced in
automation statements) stored in a NetView load library defined by the NetView
PROC, which is similar to a command processor.

Appendix C. Writing an Automation Table Function 291

Writing an Automation Table Function

292 Programming: Assembler

Appendix D. Assembler Macros and HLL Service Routine
Interfaces
Table 51 lists each assembler macro or service routine and its corresponding
high-level language (HLL) service routine name. Chapter 8, “Macros,” on page 155
contains detailed information on each assembler macro.

Note: For more information about the HLL service routines, refer to IBM Tivoli
NetView for z/OS Programming: PL/I and C.
Table 51. Assembler and HLL Service Interfaces for the NetView program
Assembler
Macro HLL Service Routine Name Description
DSIAUTO CNMAUTO Invoke automation services
DSIBAM – Build automation message
DSIBAMKW – Build automation message keyword
DSICBS – Control block services
DSICES CNMSCOP Command entry services
DSICVTHE – Convert to hex
DSIC2T CNMC2T Code point translation service reference
DSIDATIM CNMINFC Date and time
DSIDEL – Delete user-defined module
DSIDKS CNMMEM(C|O|R|) Disk services
DSIFIND CNMNAMS Find long-running command storage
DSIFRE CNMPOOL Free storage
DSIFREBF* – Free buffers service
DSIGET CNMPOOL Get storage
DSIGETDS CNMGETD Data queue manipulation service
DSIHREGS CNMHRGS High-performance transport application
registration
DSIHSNDS CNMHSMU Send high-performance message unit
DSIID – Inserts a readable identifier in the code
DSIKVS CNMSCOP Keyword and or value services
DSILCS – Obtain and or release control blocks
DSILOD – Load user-defined module
DSIMBS – Message build services
DSIMDS – Message definition services
DSIMMDB* CNMPMDB Process MDB service
DSIMQS CNMSMSG Message queueing services
DSINOR CNMQAPI Resource Object Data Manager
DSIPAS – Parameter alias services
DSIPOP CNMNAMS Remove long-running command
DSIPOS – ECB post services

© Copyright IBM Corp. 1997, 2015 293

Assembler Macros and HLL Service Routine Interfaces

Table 51. Assembler and HLL Service Interfaces for the NetView program (continued)
Assembler
Macro HLL Service Routine Name Description
DSIPRS CNMSCAN Parsing services
DSIPSS CNMSMSG Presentation services
DSIPUSH CNMNAMS Establish long-running command
DSIQOS – Query operator services
DSIQRS – Query resource services
DSIRDS – Resource definition services
DSIRXCOM – Access REXX variables (VM only)
DSIRXEBS – Get an EVALBLOK
DSISRCMV – Search for subvector/subfield
DSISYS CNMINFC Operating system indicator
DSITECBS – Manage a dynamic ECB list for DSTs
DSIVARS CNMVARS NetView variable services
DSIWAT – ECB wait services
DSIWCS CNMSMSG Write console services
DSIWLS CNMSMSG Write log services
DSIZCSMS CNMCNMI CNM data services
DSIZVSMS CNMKIO VSAM data services
DSI6REGS CNMRGS Registration API
DSI6SNDS CNMSMU Send a message unit
DUIFSMTE – Defines a status mapping table entry. Refer
to IBM Tivoli NetView for z/OS Resource
Object Data Manager and GMFHS
Programmer's Guide for more information.
Note: * = Assembler service routine.

294 Programming: Assembler

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

© Copyright IBM Corp. 1997, 2015 295

 sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

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.

COPYRIGHT LICENSE:

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:

© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights
reserved.

296 Programming: Assembler

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 and Acrobat and all Adobe-based trademarks are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States,
other countries, or both.

Linux is a registered trademark of Linus Torvalds in the United States, other

countries, or both.

Microsoft and Windows are registered 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 297
298 Programming: Assembler
Index
Special characters assembler (continued)
command samples (continued)
&WAIT condition 12, 28, 40 CNMRECV 275
CNMSEND 275
CNMSGENA 275
Numerics CNMSMF3E 275
3270 data stream 66 CNMSMF3F 275
DSICTMOD 275
DSIEX02A 275
A DSIEX17 275
DSIEX18 276
AAUTISAW control block 49 DSIEX19 276
abend (abnormal end) reinstate routine DSIEX20 276
general 75 DSIEX21 276
long-running command processor 68 DSIUSR00 277
ABEND (abnormal end) reinstate routine OPERID 277
DSIPOP macro 211 macros and HLL service routine 293
DSIPUSH macro 223 parameter sample 276
ACB (access method control block) 89 performance 1
accessibility xv ASSIGN command 12, 28
action message 72 ASYPANEL ECB 66
addressing mode (AMODE) 6 authorized receiver 28, 203
AID key 66 automated operation, testing of 2
AIFR automation table function (ATF)
buffer structure 61 control block access 289
AIFR (automation internal function request) designing 288
control block 121 installing 290
cross-reference table to MDB fields 279 overview 287
extension 112 automation task command processor 75
modification 111 AUTOTASK command 3
objects 112
routing list 137
alert automation 21
alert generation 23 B
alternate screen size 66 Basic Sequential Access Method (BSAM)
argument list 99 empty file 23, 50
assembler output 23, 50
benefits 1 BNJPALEX installation exit 23
called service routine 267 BNJPNL1 data set 167
command samples BNJPNL2 data set 167
AAUTOTB 273 books
ABLDMSG 273 see publications xi
ACALLCMD 273 branch table, ECB processor load module (DSITECBR) control
ADATTIM 273 block 145
AGETDS 273 break STIFLE mode 72
AHREGSTR 273 buffer
AHSNDMU 273 AIFR 61
ALERTMSG 273 building a command buffer 15
ALISTMEM 273 free NetView buffer service routine 267
AMLWTO 273 header (BUFHDR) control block
AMSGMOD 273 description 103
AOPTTSK 274 example 111
APSSFULL 274 fields 104
AREGISTR 274 HDRIND field values 106
ARODMCON 272, 274 HDRMTYPE field values 106
ASENDMU 274 message command extension 109
ASEQLOG 274 presentation attributes 109
ATMPCMDP 76, 274 structure 9, 104
ATMPUXIT 274 buffer, for RUNCMD 154
AUSRFUNC 274 build automation message (DSIBAM) macro 156
AWRTLOG 275 build automation message keyword (DSIBAMKW) macro 158
AXITVN 275

© Copyright IBM Corp. 1997, 2015 299

C command (continued)
processor (continued)
called service routine 267 calling 16
calling commands 15 combination 60
CanzLog log 242 data service command processor (DSCP) 60
change bars xvii example control blocks used by 63
CLOSE NORMAL command 85 full-screen command processor (FSCP) 65
CMDDEF statement 1, 59, 84 high-priority 59
CNM immediate 60
data input 23, 51 input 61
data service 245 input before 23, 32
interface output 23, 54 installation 76
router 52 long-running 60
CNMCMD 59 operator task 61
CNMPNL1 data set 167 output 62
CNMRECV sample 275 overview 59
CNMS sample 276 regular 59
CNMS0055 sample 275 RESET 61
CNMS4202 sample 76, 274 return codes 62
CNMS4270 sample 275 template for 76
CNMS4271 sample 23, 273 TVBINXIT 60
CNMS4272 sample 275 user-defined 84
CNMS4273 sample 273 work block (DSICWB)
CNMS4274 sample 273 contents 116
CNMS4275 sample 274 how to obtain and release 9
CNMS4276 sample 273 obtaining, releasing 15
CNMS4277 sample 274 command processors
CNMS4278 sample 273 overview 59
CNMS4279 sample 274 command work block 7
CNMS4280 sample 273 COMPCDE keyword 69, 70, 72, 212
CNMS4281 sample 277 control block
CNMS4282 sample 274 header 115
CNMS4283 sample 23, 275 service (DSICBS) macro 159
CNMS4284 sample 23, 273 control block, DSIXRCMD 154
CNMS4286 sample 273 control blocks
CNMS4287 sample 275 accessed by automation table functions 289
CNMS4288 sample 275 accessed by command processor 63
CNMS4289 sample 275 AIFR (automation internal function request) 121
CNMS4290 sample 274 BUFHDR (buffer header) 103
CNMS4291 sample 273 command processor 7
CNMS4292 sample 274 DSICBH (control block header) 115
CNMS4293 sample 274 DSICWB (command work block) 116
CNMS4294 sample 273 DSIDSB (data service block) 117
CNMS4295 sample 277 DSIDSRB (data service request block) 118
CNMS4296 sample 273 DSIDTR (data transport request) 120
CNMS4297 sample 24, 275 DSIELB (external logging block) 120
CNMS4298 sample 24, 276 DSIIFR (internal function request) 120
CNMS4307 sample 24, 276 DSILOGDS (NetView log) 138
CNMS4308 sample 276 DSIMVT (main vector table) 138
CNMS8002 sample 274 DSIPDB (parse descriptor block) 142
CNMSEND sample 275 DSISCE (system command entry) 143
CNMSGENA sample 275 DSISCT (system command table) 144
CNMSJM11 sample 97, 276 DSISVL (service routine vector list) 144
CNMSMF3E sample 275 DSISWB (service work block) 144
CNMSMF3F sample 275 DSITECBR (branch table of ECB processor load
code points, translating 163 modules) 145
code-to-text (DSIC2T) macro 163 DSITIB (task information block) 145
code, using 1 DSITVB (task vector block) 147
combination command processor 60 DSIUSE (installation exit parameter list) 151
command how to establish addressability 9
buffer sample code 65 how to include 7
calling 15 installation exit routine 7
calling directly 15 optional subtask 81
entry service (DSICES) macro 160 overview 103
interaction 1 user subtasks 7
parsing 15 user-written programming 8
processor work block service 9
address 15

300 Programming: Assembler

control point-management service unit (CP-MSU) 51, 253 DSIDKS (disk service) macro (continued)
conventions description and syntax 166
typeface xvii DSIDSB use 117
converting, hexadecimal DSICVTHE macro 163 example 18, 82
CP-MSU (control point management service unit) 51, 253 DSIDSB (data service block) control block 117
cross-domain DSIDSRB (data service request block) control block
command send 23, 35 description 118
ECB 66 fields 118
input 29 major, minor return code 90, 92
tasks 18, 21 DSIDTR (data transport request) control block 120
DSIELB (external logging block) control block 120
DSIELTSK external logging task 14
D DSIEX01 installation exit 23, 29
DSIEX02 installation exit (obsolete) 23, 30
data queue manipulation service (DSIGETDS) macro 177
DSIEX02A installation exit
data service
DSIPSS macro 220
command processor (DSCP)
message handling, OST/NNT 27
coding instructions 88
message handling, PPT 28
description 60
output, operator installation exit 30
example of design 93
summary 23
example program 93
title-line mode 12
solicited 90
DSIEX03 installation exit 23, 32
structure 94
DSIEX04 installation exit 23, 33
unsolicited 89
DSIEX05 installation exit 23, 34
VSAM service interface 91
DSIEX06 installation exit 23, 28, 35
request block (DSRB)
DSIEX07 installation exit 23, 35
control block 118
DSIEX09 installation exit 23, 36
DSCP 88
DSIEX10 installation exit 23, 37
major, minor return codes 90, 92
DSIEX11 installation exit 23, 28, 37
data service (DSIZCSMS) macro, CNM 245
DSIEX12 installation exit 23, 38
data service block 117
DSIEX13 installation exit 23, 38
data transport request (DSIDTR) control block 120
DSIEX14 installation exit 23, 39
date and time (DSIDATIM) macro 165
DSIEX16 installation exit
defining messages, disk 201
interface with DSIEX02A 41
delete user-defined module (DSIDEL) macro 166
message handling, OST/NNT 27
delimiters 214
message handling, PPT 28
destination application name (DAN) 189, 264
post-NetView automation table exit 40
directory names, notation xvii
summary 23
disk service (DSIDKS) macro 18, 166
title-line mode 12
DSCP redrive 90, 91
DSIEX16 interface data 141
DSI090I message 56
DSIEX16B installation exit 23, 45
DSI6REGS (LU 6.2 registration) macro 251
DSIEX17 installation exit 23, 45
DSI6SNDS (send a message unit) macro 258
DSIEX18 installation exit 47
DSIAIFRO control block 111
DSIEX18 sample 276
DSIAUTO (invoke automation service) macro 155
DSIEX19 installation exit 48
DSIBAM (build automation message) macro 156
DSIEX19 sample 276
DSIBAMKW (build automation message keyword) macro 158
DSIEX20 installation exit 48
DSIC2T (code-to-text) macro 163
DSIEX20 sample 276
DSICBH (control block header) 115
DSIEX21 sample 276
DSICBS (control block service) macro
DSIFIND (find long-running command storage) macro
description and syntax 159
description and syntax 170
example 8
example 20
DSICES (command entry service) macro
long-running command processor 68
calling a command directly 16
DSIFRE (free storage) macro
description and syntax 160
description and syntax 172
the ROLL function 73
example
DSICLD data set 167
to get storage 10
DSICTMOD macro 82
to release queued storage 10
DSICTMOD sample 275
free NetView buffers routine 268
DSICVTHE macro, converting to hexadecimal 163
DSIFREBF, free NetView buffers service routine 267
DSICWB (command work block)
DSIFREBS (free storage) macro 174
fields 116
DSIGET (get storage) macro
input to command processor 61
description and syntax 174
overview 116
example
DSIDATIM (date and time) macro 165
to get storage 10
DSIDEL (delete user-defined module) macro 166
to release queued storage 10
DSIDKS (disk service) macro
free NetView buffers routine 268
buffer head use 111

Index 301
DSIGETDS (data queue manipulation service) macro 177 DSIRXFPG system packages 97
DSIHREGS (high-performance transport application DSIRXLFP local packages 97
registration) macro 179 DSIRXPRM sample 97, 276
DSIHSNDS (sending high-performance message unit) DSIRXUFP user packages 97
macro 183 DSISCE (system command entry) control block 143
DSIID (store SYSMOD level, CSECT) macro 190 DSISCT (system command table) control block 144
DSIIFR (internal function request) control block 120 DSISRCMV (searching, subvector/subfield) macro 233
DSIKVS (keyword/value service) macro 190 DSISVL (service routine vector list) control block 144
DSILCS (obtain/release control blocks) macro DSISWB (service work block) control block 144
description and syntax 192 DSISYS (operating system indicator) macro 235
example 9 DSITECBR (branch table of ECB processor load modules)
DSILOD (load user-defined module) macro 195 control block 145
DSILOGDS (Network Log) control block 138 DSITECBS (manage a dynamic ECB list for DSTs) macro
DSILRCR8 routine 71 with DSITECBR control block 145
DSIMBS (message buffer service) macro DSITECBS (managing dynamic ECB list, DSTs) macro
creating messages 11, 201 description and syntax 235
description and syntax 196 DSITIB (task information block) control block 145
DSIMDS (message definition service) macro DSITVB (task vector block) control block 147
creating messages 11 DSIUSE (installation exit parameter list) control block
description and syntax 198 description 151
DSIMMDB (process message data block) routine 268 fields 151
DSIMMDBS process MDB macro 202 input to installation exit routine 25
DSIMQS (message queueing service) macro DSIUSR00 sample 277
description and syntax 202 DSIVARS (variable service) macro 237
example 12 DSIVTAM data set 167
uses DSIWAT (ECB wait service) macro
displaying information 12, 13, 84 description and syntax 240
DSCP design 93 optional subtask processing 79, 82
invoking a user-defined processor 79 DSIWCS (write console service) macro
ROLL function 73 description and syntax 242
scheduling a command 16 example 11
DSIMSG data set 167, 201 DSIWLS (write log service) macro
DSIMVT (main vector table) control block 138 description and syntax 242
DSINOR (resource object data manager) macro 208 example 11
DSIPARM data set 80, 167 uses
DSIPAS (parameter/alias service) macro 210 logging messages 14
DSIPDB (parse descriptor block) control block 142 DSIXRCMD 154
DSIPOP (remove long-running command) macro DSIZCSMS (CNM data service) macro
description and syntax 211 description and syntax 245
uses example 93, 248
long-running command processor 68 uses
RESUME routine 71 CNM data service 86
DSIPOS (ECB post service) macro 213 DSCP interface 90
DSIPRF data set 167 DSIZDST macro 87
DSIPRS (parsing service) macro DSIZVSMS (VSAM data service) macro
description and syntax 214 description and syntax 249
examples 216 example 93
DSIPSS (presentation service) macro uses
description and syntax 216 CNM data service 89
example 12 VSAM service interface 91
uses DSRBO keyword 90, 91
displaying information 12 DSRBU keyword 89
returning a command to an originating domain 61 DST (data service task)
returning command, originating domain 18 concatenated installation exit routine 23, 26
screen formatting 66, 67 description 4
DSIPUSH (establish long-running command) macro installation exit routine 23, 50
description and syntax 223 unique service 22
example 20 writing a user subtask
uses installation 87
long-running command processor 68 writing user subtasks
RESUME routine 71 initialization 54, 87
screen formatting 67 overview 86
the ROLL function 73 processing 88
DSIQOS (query operator validity and status) macro 228 return codes 88
DSIQRS (query resource service) macro 229 DSTINIT statement 87
DSIRDS (resource definition service) macro 232 DUIFSMTE (customize DisplayStatus table) macro 294
DSIRXEBS (get an EVALBLOK) macro 232

302 Programming: Assembler

E I
ECB (event control block) IEFACTRT exit 275
loop 82 IFRCODAI buffer 27, 31, 41
post service 18, 213 IFRCODCR buffer 17, 94
wait service 18, 240 IFRCODUS message buffer 84
education immediate command processor 60
see Tivoli technical training xv immediate message 219
entry specifications 98 INIT keyword 81, 87
environment variables, notation xvii initialization member 80
environments, installation exit 23 input, command processor 61
Erase/Write Alternate command 66 installation exit buffer for RUNCMD 154
Erase/Write command 66 installation exit environments 23
error recovery 61 installation exit parameter list (DSIUSE) control block 151
establish operator validity and logon status 228, 229 installation exits
evaluation block (EVALBLOK) 98, 99 DST (data service task) 23
event routine 223 global 23
exit 16 interface data 141 list 23
external function parameter list 98 routine
external logging 14 control blocks 29
external logging block (DSIELB) 120 input 25
installing 56
output 26
F overview 23
template for 57
find long-running command storage (DSIFIND) macro 170
writing 25
focal point transfer RU header 52
summary 29
free storage (DSIFRE) macro 172
unused 56
FREEMAIN failure 173
installing command processor 76
full-screen command processor
internal function request (DSIIFR) control block 121
coding instruction 65
intertask communication 83
screen formatting 66
invoke automation service (DSIAUTO) macro 155
FUNCT keyword 87
IRB exits, special requirements for 86
function package directory
IRXEVALB mapping macro 99
entry format 101
ISTMGC00 default table 89
example 102
header 100
writing 97
K
keyword/value service (DSIKVS) macro 190
G
general data stream (GDS) 253
get an EVALBLOK (DSIRXEBS) macro 232 L
get storage (DSIGET) macro 174 LIST command 86
getting and freeing storage load failure 56
freeing 172 load user-defined module (DSILOD) macro 195
getting 174 log input, output 67
named 20 log output installation exit 23, 33
non-queued 10 LOGOFF routine 75, 88
queued 10 logoff, before 23, 39
global installation exit routine 23, 29 logon validation 23, 38
global variable service (DSIVARS) macro 237 long-running command (DSIPUSH) macro 223
long-running command processor
completion codes 70
H description 60
scheduling RESUME routine 69
hardcopy log 242
writing 68
HCT (hardcopy task) 4
LOW priority 206
HDRIND field values 106
LU 6.2 registration (DSI6REGS) macro 251
HDRMTYPE field values 106
HIGH priority 206
high-performance transport application registration
(DSIHREGS) macro 179 M
high-performance, send message unit (DSIHSNDS) MACRF keyword 91
macro 183 macro use 6
high-priority command processor 59 macros
HLL service routine, corresponding macros 293 DSI6REGS (LU 6.2 Registration) 251
DSI6SNDS (send a message unit) 258

Index 303
macros (continued) message (continued)
DSIAUTO (invoke automation service) 155 command extension 109
DSIBAM (build automation message) 156 control object, format 113
DSIBAMKW (build automation message keyword) 158 creating 11
DSIC2T (code-to-text) 163 data block (MDB)
DSICBS (control block service) 159 control block fields 279
DSICES (command entry service) 160 externalized data definitions 111
DSICVTHE, hexadecimal 163 message control object 113
DSIDATIM (date and time) 165 process routine 268
DSIDEL (delete user-defined module) 166 definition service (DSIMDS) macro 198
DSIDKS (disk service) 166 deleting 26
DSIFIND (find long-running command storage) 170 ECB 66
DSIFRE (free storage) 172 example, definition module 202
DSIFREBS (free storage) 174 handling
DSIGET (get storage) 174 OST/NNT 27
DSIGETDS (data queue manipulation service) 177 PPT 28
DSIHREGS (high-performance transport application IFRCODAI buffer 27
registration) 179 inserts 196, 200
DSIHSNDS (sending high-performance message unit) 183 logging 14
DSIID (store sysmod level, csect) 190 processing 10, 27
DSIKVS (keyword/value service) 190 queuing service (DSIMQS) macro 202
DSILCS (obtain/release control blocks) 192 replacing 26
DSILOD (load user-defined module) 195 requesting reply 72
DSIMBS (message build service) 196 STIFLE 72
DSIMDS (message definition service) 198 MLWTO (multiline write-to-operator) message 12
DSIMMDBS (process MDB) 202 MNT (main task) 3
DSIMQS (message queueing service) 202 MOD keyword 80
DSINOR (resource object data manager) 208 multiple-domain support-message unit (MDS-MU) 51
DSIPAS (parameter/alias service) 210 MVS
DSIPOP (remove long-running command) 211 Log Browse exit 47
DSIPOS (ECB post service) 213 message and DOM receive exit 23, 45
DSIPRS (parsing service) 214 RUNCMD exit 48
DSIPSS (presentation service) 216 SAW exit 48
DSIPUSH (establish long-running command) 223 system log 242
DSIQOS (query operator validity and status) 228 MVTAIDFT field defaults 141
DSIQRS (query resource service) 229
DSIRDS (resource definition service) 232
DSIRXEBS (get an EVALBLOK) 232
DSISRCMV (searching, subvector/subfield) 233
N
named storage 20, 223
DSISYS (operating system indicator) 235
NetView
DSITECBS (manage a dynamic ECB list for DSTs) 235
buffer structure 9
DSIVARS (variable service) 237
log (DSILOGDS) control block 138
DSIWAT (ECB wait service) 240
sequential log 242
DSIWCS (write console service) 242
tasks
DSIWLS (write log service) 242
DST (data service task) 4
DSIZCSMS (CNM data service) 245
HCT (hardcopy task) 4
DSIZVSMS (VSAM data service) 249
MNT (main task) 3
DUIFSMTE (display status table entry) 294
NNT (NetView-NetView task) 3
overview of macros 155
OPT (optional task) 4
main vector table (DSIMVT) control block 138
OST (operator station task) 3
manage a dynamic ECB list for DSTs (DSITECBS) macro 235
PPT (primary program operator interface task) 4
management service
TRACE facility 1
DSI6REGS macro 251
network log 242
passing, automation table 21
network service request 245
post-automation table exit 23, 45
NNT (NetView-NetView task) 3
using MS transport 20
NORMAL priority 206
manuals
notation
see publications xi
environment variables xvii
MAXABEND definition statement 139
path names xvii
MDS-MU (multiple-domain support-message unit) 51
typeface xvii
MEM keyword 80
numeric code point translation 21
message
NVCLOSE automation table condition item 139
authorized receiver 28
automation 27, 28
buffer 38
buffer contents 84 O
build service (DSIMBS) macro 196 OAN (origin application name) 189, 264

304 Programming: Assembler

objects
message control 113
R
source 114 redrive, DSCP 90, 91
obtain/release control blocks (DSILCS) macro 192 reentrant code 6
online publications register use 6
accessing xiv regular command 29, 32
operating system indicator (DSISYS) macro 235 regular command processor 59
operator remove long-running command (DSIPOP) macro 211
communications 84 request unit header, focal point transfer 52
input 23, 29 RESET command 71
output 23, 30 residency mode (RMODE) 6
OPERID sample 277 resource definition service (DSIRDS) macro 232
OPT resource object data manager (DSINOR) macro 208
definition 4 resource status manager installation exit
message handling 27 summary 23
optional subtask Restructured Extended Executor (REXX) language
attaching 81 writing user function 97
terminating 85 resumable command 223
template for 274 RESUME routine
writing completion codes 70
additional considerations 86 DSIPOP macro 211
initializing 81 DSIPUSH macro 223
installing 80 general 69
overview 79 issuing a message 71
processing 82 return code 70
origin application name (OAN) 189, 264 revision codes xvii
OST (operator station task) 3 ROLL
OST/NNT message receiver 23, 38 command 60
output from command processor 62 full-screen function 73
function 73
group 69, 73
ROUTE command 18
P routing and targeting instruction (R&TI)
parameter substitution 19 APPL field, DSI6REGS macro 253
parameter/alias service (DSIPAS) macro 210 return code, DSI6SNDS macro 264, 265
parse descriptor block (DSIPDB) control block 142 used in DSI6REGS macro 258
parsing 19 with DSI6SNDS macro 258
parsing service (DSIPRS) macro 214 RUNCMD, installation exit buffer control block 154
path names, notation xvii
PDDNM keyword 91
POI (program operator interface) 28
post-message automation table exit 23
S
PPASS keyword 91 samples
PPT (primary program operator interface task) 4 AAUTOTB (CNMS4291) 273
presentation attributes 45 ABLDMSG (CNMS4278) 273
presentation service (DSIPSS) macro 216 ACALLCMD (CNMS4280) 273
presenting information ADATTIM (CNMS4274) 273
full-screen mode 12 AGETDS (CNMS4294) 273
standard mode 12 AHREGSTR (CNMS4296) 273
title-line mode 12 AHSNDMU (CNMS4286) 273
PRI keyword 81, 87 ALERTMSG (CNMS4284) 273
private message queue 83 ALISTMEM (CNMS4276) 273
privileged functions 1 AMLWTO (CNMS4273) 273
privileged system service 4 AMSGMOD (CNMS4271) 273
problem program state 4 AOPTTSK (CNMS4277) 274
process message data block (DSIMMDB) routine 268 APSSFULL (CNMS4279) 274
public message queue 83 AREGISTR (CNMS4292) 274
publications ARODMCON (CNMS4290) 274
accessing online xiv ASENDMU (CNMS4293) 274
NetView for z/OS xi ASEQLOG (CNMS4275) 274
ordering xiv ATMPCMDP (CNMS4202) 76, 274
ATMPUXIT (CNMS4282) 274
AUSRFUNC (CNMS8002) 274
AWRTLOG (CNMS4272) 275
Q AXITVN (CNMS4270) 275
query support 66 CNMRECV (CNMS4289) 275
queued storage 10, 174 CNMSEND (CNMS4288) 275
CNMSGENA (CNMS4287) 275

Index 305
samples (continued) TASK statement 80
CNMSMF3E 275 task vector block (DSITVB) control block
CNMSMF3F 275 description 147
DSICTMOD (CNMS0055) 275 fields 147
DSIEX18 (CNMS4298) 276 use
DSIEX19 (CNMS4307) 276 attaching the OPT subtask 81
DSIEX21 276 intertask communication 147
DSIRXPRM (CNMSJM11) 276 template
DSIUSR00 (CNMS4281) 277 command procedure processor 76
OPERID (CNMS4295) 277 optional task 274
overview 271 terminal input, simulating 16
sequential logging 14 Tivoli
table of assembler 271 training, technical xv
SAW exit 48 user groups xv
scope of command 19 Tivoli Software Information Center xiv
screen identifier 74 TPEND exit, VTAM 86
screen mode TRACE facility 1
full-screen 12 training, Tivoli technical xv
standard 12 translating code points 163
title-line 12 TRAP condition 28
SDDNM keyword 91 TVBINXIT bit
searching, subvector or subfield (DSISRCMV) macro 233 coding restrictions 5
security processing 5
command authorization checking 19 TVBMEMNM field 82
DSICES macro 160 typeface conventions xvii
DSIKVS macro 190
send a message unit (DSI6SNDS) macro 294
sending high-performance message unit (DSIHSNDS)
macro 183
U
unattended operator task 61
sending message unit (DSI6SNDS) macro 258
unbalanced quote 215
sequential logging 14
UNSOL keyword 89
service xv
unsolicited CNM data interface 89
service management connect xv
user fields 103
service routine vector list (DSISVL) control block 144
user groups
service routine, called 267
NetView, on Yahoo xvi
service work block (DSISWB) control block
Tivoli xv
description 144
user memory protection key 4
fields 144
user subtasks, types
how to obtain and release 15
DST (data service task) 79
obtaining, releasing 9
OPT (optional task) 79
SMC xv
user-defined command processor 84
SMF type 39 records 275
user-defined service 96
solicited CNM data interface 90
user-written
source object
function 97
format 114
programming
use 115
coding guidelines 4
SPASS keyword 91
testing 1
STIFLE message 72
subtask 79
STIMER macro 6
USERASIS return code 26, 30, 88
storage service 10
USERDROP return code
store sysmod level in csect (DSIID) 190
deleting message and MSU 26
subtask organization 79
initializing a DST 88
supervisor state 4
installation exit 23
support xv
installation exit output 26
symbolic substitution 140
operator input 30
system command entry (DSISCE) control block 143
USEREVNT return code 53
system command table (DSISCT) control block 144
USEREXLG return code 53
system console
USERHCL return code 34
input from 23, 37
USERHCLR return code 34
message display 14, 36
USERLOG return code 34
output to 23, 24, 36
USERLOGR return code 34
USERMSG buffer 25
USERSWAP return code 26, 30, 88
T
task command considerations 61
task information block (DSITIB) control block 145
task priority, relative 81, 87

306 Programming: Assembler

V
VALCLASS checking 191
variable name 6
variable service (DSIVARS) macro 237
variables, notation for xvii
VIEW command 1
Virtual Storage Access Method (VSAM)
data service (DSIZVSMS) macro 249
empty file 55
I/O (input/output) service 249
input 55
key 250
output 55
request 93
service interface 23, 91
virtual storage, loading and deleting module 18
Virtual Telecommunications Access Method (VTAM)
command invocation, before 23, 34
solicited message 23, 35
unsolicited message 23, 37

W
waiting completion, events 240
work block service 9
write console service (DSIWCS) macro 242
write log service (DSIWLS) macro 242

X
XITBN installation exit 23, 50
XITBO installation exit 23, 50
XITCI installation exit 23, 51
XITCO installation exit 23, 54
XITDI
installation exit 23, 54
keyword 87
XITVI
installation exit 55
keyword 91
XITVN
example 55
installation exit 55
keyword 91
XITVO
installation exit 55
keyword 91
XITXL
installation exit 56

Y
Yahoo user group, NetView xvi

Index 307
308 Programming: Assembler
IBM®

Printed in USA

SC27-2858-03