Rexx PDF

Tivoli IBM Tivoli NetView for z/OS

Version 5 Release 2
Programming: REXX and the NetView Command List Language
SC31-8862-01
Tivoli IBM Tivoli NetView for z/OS
®

Version 5 Release 2
Programming: REXX and the NetView Command List Language
SC31-8862-01
Note
Before using this information and the product it supports, read the information in “Notices” on page 183.
Second Edition (October 2005)

This edition applies to version 5, release 2 of IBM Tivoli NetView for z/OS (product number 5697-ENV) and to all
subsequent releases and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 1997, 2005. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Who should read this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
IBM Tivoli NetView for z/OS library . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Prerequisite publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Accessing terminology online . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Using LookAt to look up message explanations. . . . . . . . . . . . . . . . . . . . . . . x
Accessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
Ordering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Tivoli technical training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Support information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Participating in newsgroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Downloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Operating system-dependent variables and paths . . . . . . . . . . . . . . . . . . . . . xiii
Syntax Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Chapter 1. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

The Benefits of Using Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Examples of Common Startup Command Lists . . . . . . . . . . . . . . . . . . . . . . . 2
Examples of Activating a Network Control Program . . . . . . . . . . . . . . . . . . . . . 2
Creating Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Controlling Access to Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Loading Command Lists into Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Running Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Running Command Lists When NetView Is Started . . . . . . . . . . . . . . . . . . . . . 6
Running Command Lists When Logging On . . . . . . . . . . . . . . . . . . . . . . . . 6
Running Command Lists after Receiving a Message or MSU . . . . . . . . . . . . . . . . . . 6
Running Command Lists from a Terminal . . . . . . . . . . . . . . . . . . . . . . . . 7
Running Command Lists at a Specified Time or Time Interval . . . . . . . . . . . . . . . . . . 7
Running Command Lists from Another Command List . . . . . . . . . . . . . . . . . . . . 7
Running Command Lists from a User-Written Command Processor . . . . . . . . . . . . . . . . 9
Using Network Commands in Command Lists . . . . . . . . . . . . . . . . . . . . . . . 10
Using System Commands in Command Lists . . . . . . . . . . . . . . . . . . . . . . . 10
Using Long-Running Commands in Command Lists. . . . . . . . . . . . . . . . . . . . . 10
Using NetView Pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Using the VIEW Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Using Full-Screen Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Primary POI Task Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
AUTOTASK OST Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Controlling Command List Output . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
| Working with Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Chapter 2. REXX Language Overview . . . . . . . . . . . . . . . . . . . . . . 15

Introduction to the REXX Language . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Compiling and Running REXX Command Lists . . . . . . . . . . . . . . . . . . . . . . . 16
| Using Data REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
| Processing Data REXX Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
| Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
| Data REXX Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
| /*%DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
| /*%LOGIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
© Copyright IBM Corp. 1997, 2005 iii

Coding Conventions for REXX Command Lists and Data REXX Files . . . . . . . . . . . . . . . . 21
Record Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Using Quotation Marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Suppressing Display of Non-REXX Commands . . . . . . . . . . . . . . . . . . . . . . 23
NetView Restrictions on REXX Instructions . . . . . . . . . . . . . . . . . . . . . . . . . 24
Pausing for Operator Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Using the SAY Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Using the CALL Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
NetView Restrictions on REXX Functions . . . . . . . . . . . . . . . . . . . . . . . . . 25
Writing REXX Function Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Changing the Environment Addressed by REXX Command Lists . . . . . . . . . . . . . . . . . 26
Data REXX Host Command Environment . . . . . . . . . . . . . . . . . . . . . . . . . 27
Using the EXECIO Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Using MVS and VTAM Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Using the NetView ALLOCATE and FREE Commands . . . . . . . . . . . . . . . . . . . . . 28
Using REXX Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Nesting REXX Command Lists from Assembler, C, or PL/I . . . . . . . . . . . . . . . . . . . 29
Parsing in REXX Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Tracing REXX Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Return Codes in REXX Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Recovering from Errors in REXX Command Lists . . . . . . . . . . . . . . . . . . . . . . . 31
Chapter 3. REXX Instructions for Command Lists Run in a NetView Environment . . . 33

Using TRAP in Nested REXX Command Lists . . . . . . . . . . . . . . . . . . . . . . . . 34
Using WAIT in Nested Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Using MSGREAD in Nested Command Lists . . . . . . . . . . . . . . . . . . . . . . . . 35
Functions Set by MSGREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 4. REXX Instructions for NetView REXX Command Lists and Data REXX Files 37
Translation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Command List Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Cross-Domain Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Data Set Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Global Variable Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Message Processing Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . 48
Message Processing Information for All Operating Systems . . . . . . . . . . . . . . . . . . 49
MVS-Specific Message Processing Information . . . . . . . . . . . . . . . . . . . . . . . 55
ROUTCDE Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
REXX Management Services Unit Information Functions . . . . . . . . . . . . . . . . . . . . 62
Hardware Monitor (HMxxxxxx) Examples . . . . . . . . . . . . . . . . . . . . . . . . 71
MSUSEG Syntax and Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
| Probable Cause Syntax and Examples . . . . . . . . . . . . . . . . . . . . . . . . . 76
Operator Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Session Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
REXX Environment Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . 82
Terminal Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Time and Date Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Nulls and Blanks Stripping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Chapter 5. Automation Resource Management . . . . . . . . . . . . . . . . . . 85

Defining NetView Automation Table Command Lists . . . . . . . . . . . . . . . . . . . . . 85
Routing Messages from Automation-Table-Driven Command Lists . . . . . . . . . . . . . . . . . 85
Implementing NetView Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Suppressing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Determining the Environment for a Command List . . . . . . . . . . . . . . . . . . . . . 86
Testing Automation Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Recovering from Looping Command Lists . . . . . . . . . . . . . . . . . . . . . . . . 88
Considering Operator Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Common Automation Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
iv Programming: REXX and the NetView Command List Language

Appendix A. Writing Simple Command Lists in the NetView Command List Language 91
What the NetView Command List Language Includes . . . . . . . . . . . 91 . . . . . . . . . .
Coding Conventions for NetView Command List Language Statements . . . . . 91 . . . . . . . . . .
Conventions for General Coding . . . . . . . . . . . . . . . . . 92 . . . . . . . . . .
Conventions for Continuing a Statement. . . . . . . . . . . . . . . 92 . . . . . . . . . .
Conventions for Double-Byte Character Set Text . . . . . . . . . . . . 93 . . . . . . . . . .
Conventions for Suppression Characters . . . . . . . . . . . . . . . 93 . . . . . . . . . .
Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 . . . . . . . . . .
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 95 . . . . . . . . . .
Variable Substitution Order . . . . . . . . . . . . . . . . . . . 95 . . . . . . . . . .
Parameter Variables . . . . . . . . . . . . . . . . . . . . . 96 . . . . . . . . . .
Passing Parameter Variable Information to a Command List . . . . . . . . 97 . . . . . . . . . .
Using Parameter Variables in a Command List . . . . . . . . . . . . 97 . . . . . . . . . .
Passing Parameter Variables to a Nested Command List . . . . . . . . . 98 . . . . . . . . . .
Using Quoted Strings or Special Characters in Parameter Variables . . . . . . 99 . . . . . . . . . .
Null Parameter Values . . . . . . . . . . . . . . . . . . . . . 99 . . . . . . . . . .
Control Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
User Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Hexadecimal Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Null Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Assignment Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
&CONTROL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Writing to the Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Using NetView Commands with &PAUSE . . . . . . . . . . . . . . . . . . . . . . . . 109
An Example Using &PAUSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
NetView Built-in Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
&BITAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
&BITOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
&BITXOR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
&CONCAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
&HIER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
&LENGTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
&MSUSEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
&NCCFID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
&NCCFSTAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
&SUBSTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Appendix B. NetView Command List Language Branching . . . . . . . . . . . . . 123

&IF Control Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
&GOTO Control Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
&EXIT Control Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
&WAIT Control Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Coding an &WAIT Control Statement . . . . . . . . . . . . . . . . . . . . . . . . . 128
Ending an &WAIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Using NetView Commands with &WAIT . . . . . . . . . . . . . . . . . . . . . . . . 132
Control and Parameter Variables Used with &WAIT . . . . . . . . . . . . . . . . . . . . 133
Using &WAIT in Nested Command Lists . . . . . . . . . . . . . . . . . . . . . . . . 134
Customizing the &WAIT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Ending &WAIT If CONTWAIT Is in Effect . . . . . . . . . . . . . . . . . . . . . . . . 137
Suggestions for Coding &WAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Sample Using &WAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Appendix C. NetView Command List Language Global Variables . . . . . . . . . . 141

Using &TGLOBAL and &CGLOBAL . . . . . . . . . . . . . . . . . . . . . . . . . . 142
&TGLOBAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
&CGLOBAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Updating Task Global Variables Using &TGLOBAL . . . . . . . . . . . . . . . . . . . . . 144
Extent of Variables When Using &TGLOBAL and &CGLOBAL . . . . . . . . . . . . . . . . . . 145
Contents v
GLOBALV Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Appendix D. Common Operations Services Commands . . . . . . . . . . . . . . 149

Common Operations Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Common Operations Services Return Codes . . . . . . . . . . . . . . . . . . . . . . . . 150
LINKDATA and LINKTEST Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
LINKDATA and LINKTEST Variables . . . . . . . . . . . . . . . . . . . . . . . . . 150
LINKTEST Additional Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
LINKPD Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
RUNCMD Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Using RUNCMD in a Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Appendix E. Comparison of REXX and NetView Command List Language . . . . . . 155

Comparison of REXX Instructions and NetView Command List Language Control Statements . . . . . . . 155
Comparison of REXX Functions and NetView Command List Language Control Variables and Functions . . . 156
Commands Used in Command Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Appendix F. Command List Examples Index . . . . . . . . . . . . . . . . . . . 161

REXX Command List Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
NetView Command List Language Examples . . . . . . . . . . . . . . . . . . . . . . . . 161
Appendix G. Examples of REXX Command Lists for NetView . . . . . . . . . . . . 163

ACTAPPLS Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
ACTLU Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
CHKOPNUM Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
CHKRSTAT Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
DSPRSTAT Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
GETCG Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
GREETING Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
LISTVAR Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
PRINT Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
TYPE Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
TYPEIT Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Support information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Searching knowledge bases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Searching the information center . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Searching the Internet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Obtaining fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Receiving weekly support updates . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Contacting IBM Software Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Determining the business impact . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Describing problems and gathering information . . . . . . . . . . . . . . . . . . . . . . 180
Submitting problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
vi Programming: REXX and the NetView Command List Language

About this guide
The IBM® Tivoli® NetView® for z/OS® product provides a single point of control
from which you can manage complex computer networks and systems that are
running software from multiple independent software vendors. This document,
IBM Tivoli NetView for z/OS Programming: REXX and the NetView Command List
Language, describes how to write command lists for the NetView product using
either the Restructured Extended Executor language (REXX) or the NetView
command list language.
Note: This document does not provide descriptions of NetView operator

commands. If a command is not familiar, refer to the NetView online help.
Who should read this guide

This guide is for system programmers and network operators who use command
lists or write command lists. Readers should be familiar with how the NetView
program is used in their network and what the operator tasks are.
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

You can access the online library for IBM Tivoli NetView for z/OS version 5.2 at
http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?topic=/
com.ibm.netviewforzos.doc/welcome.htm.
The following documents are available in the Tivoli NetView for z/OS library:
v Administration Reference, SC31-8854, describes the NetView program definition
statements required for system administration.
v Application Programmer’s Guide, SC31-8855, describes the NetView
program-to-program interface (PPI) and how to use the NetView application
programming interfaces (APIs).
v Automated Operations Network Customization Guide, SC31-8871, describes how to
tailor and extend the automated operations capabilities of the NetView
Automated Operations Network (AON) component, which provides
event-driven network automation.
v Automated Operations Network User’s Guide, GC31-8851, describes how to use the
Automated Operations Network component to improve system and network
efficiency.
v Automation Guide, SC31-8853, describes how to use automated operations to
improve system and network efficiency and operator productivity.
v Command Reference Volume 1, SC31-8857, and Command Reference Volume 2,
SC31-8858, describe the NetView commands, which can be used for network and
system operation and in command lists and command procedures.
v Customization Guide, SC31-8859, describes how to customize the NetView product
and points to sources of related information.
© Copyright IBM Corp. 1997, 2005 vii

v Data Model Reference, SC31-8864, provides information about the Graphic
Monitor Facility Host Subsystem (GMFHS), SNA topology manager, and
MultiSystem Manager data models.
v Troubleshooting Guide, LY43-0093, provides information about documenting,
diagnosing, and solving problems that might occur in using the NetView
product.
v Installation: Configuring Additional Components, SC31-8874, describes how to
configure NetView functions beyond the base functions.
v Installation: Configuring Graphical Components, SC31-8875, describes how to install
the NetView graphics components.
v Installation: Getting Started, SC31-8872, describes how to install and configure the
NetView base functions.
v Installation: Migration Guide, SC31-8873, describes the new functions provided by
the current release of the NetView product and the migration of the base
functions from a previous release.
v Messages and Codes, SC31-8866, describes the messages for the NetView product,
the NetView abend codes, the sense codes that appear in NetView messages,
and generic alert code points.
v MultiSystem Manager User’s Guide, GC31-8850, describes how the NetView
MultiSystem Manager component can be used in managing networks.
v NetView Management Console User’s Guide, GC31-8852, provides information
about the NetView management console interface of the NetView product.
v Programming: Assembler, SC31-8860, describes how to write exit routines,
command processors, and subtasks for the NetView product using assembler
language.
v Programming: Pipes, SC31-8863, describes how to use the NetView pipelines to
customize a NetView installation.
v Programming: PL/I and C, SC31-8861, 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, SC31-8862, 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, SC31-8865,
describes the NetView Resource Object Data Manager (RODM), including
defining your non-SNA network to RODM and using RODM for network
automation and for application programming.
v Security Reference, SC31-8870, describes how to implement authorization checking
for the NetView environment.
v SNA Topology Manager Implementation Guide, SC31-8868, 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 Tuning Guide, SC31-8869, provides tuning information to help achieve certain
performance goals for the NetView product and the network environment.
v User’s Guide, GC31-8849, describes how to use the NetView product to manage
complex, multivendor networks and systems from a single point.
v Web Application User’s Guide, SC32-9381, describes how to use the NetView Web
application to manage complex, multivendor networks and systems from a
single point.
v Licensed Program Specifications, GC31-8848, provides the license information for
the NetView product.
viii Programming: REXX and the NetView Command List Language

An index is provided for searching the Tivoli NetView for z/OS library. If you
have Adobe Acrobat on your system, you can use the Search command to locate
specific text in the library. For more information about using the index to search
the library, see the online help for Acrobat.
Prerequisite publications
To read about the new functions offered in this release, see the IBM Tivoli NetView
for z/OS Installation: Migration Guide.
Related publications
For more information about REXX, refer to the TSO/E REXX library.
For information about the NetView Bridge function, see Tivoli NetView for OS/390
Bridge Implementation, SC31-8238-03 (available only from the V1R4 library).
You can find additional product information on the NetView for z/OS Web site:
http://www.ibm.com/software/tivoli/products/netview-zos/
Accessing terminology online

The Tivoli Software Glossary includes definitions for many of the technical terms
related to Tivoli software. The Tivoli Software Glossary is available at the following
Tivoli software library Web site:
http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm
The IBM Terminology Web site consolidates the terminology from many IBM
products in one convenient location. You can access the Terminology Web site at
the following Web address:
http://www.ibm.com/ibm/terminology/
For a list of NetView for z/OS terms and definitions, refer to the IBM Terminology
Web site. For brevity and readability, the following terms are used in this
document:
NetView
For the following products:
v Tivoli NetView for z/OS Version 5 Release 2
v Tivoli NetView for z/OS Version 5 Release 1
v Tivoli NetView for OS/390® Version 1 Release 4
v Tivoli NetView for OS/390 Version 1 Release 3
MVS™
For OS/390 or z/OS operating systems
CNMCMD
For CNMCMD and its included members
CNMSTYLE
For CNMSTYLE and its included members
Tivoli Enterprise™ Portal
For CandleNet Portal®
Tivoli Enterprise Portal Server
For CandleNet Portal Server
About this guide ix

Tivoli Enterprise Management Server
For Candle Management Server®
Unless otherwise indicated, references to programs indicate the latest version and
release of the programs. If only a version is indicated, the reference is to all
releases within that version.
When a reference is made about using a personal computer or workstation, any

programmable workstation can be used.
Using LookAt to look up message explanations

LookAt is an online facility that lets you look up explanations for most of the IBM
messages you encounter, as well as for some system abends (an abnormal end of a
task) and codes. Using LookAt to find information is faster than a conventional
search because in most cases LookAt goes directly to the message explanation.
You can use LookAt from the following locations to find IBM message
explanations for z/OS elements and features, z/VM®, VSE/ESA™, and Clusters for
AIX® and Linux®:
v The Internet. You can access IBM message explanations directly from the LookAt
Web site at http://www.ibm.com/eserver/zseries/zos/bkserv/lookat/.
v Your z/OS TSO/E host system. You can install code on your z/OS or z/OS.e
systems to access IBM message explanations, using LookAt from a TSO/E
command line (for example, TSO/E prompt, ISPF, or z/OS UNIX® System
Services running OMVS).
v Your Microsoft® Windows® workstation. You can install code to access IBM
message explanations on the z/OS Collection (SK3T-4269), using LookAt from a
Microsoft Windows DOS command line.
v Your wireless handheld device. You can use the LookAt Mobile Edition with a
handheld device that has wireless access and an Internet browser (for example,
Internet Explorer for Pocket PCs, Blazer, or Eudora for Palm OS, or Opera for
Linux handheld devices). Link to the LookAt Mobile Edition from the LookAt
Web site.
You can obtain code to install LookAt on your host system or Microsoft Windows
workstation from a disk on your z/OS Collection (SK3T-4269), or from the LookAt
Web site (click Download, and select the platform, release, collection, and location
that suit your needs). More information is available in the LOOKAT.ME files
available during the download process.
Accessing publications online

The documentation CD contains the publications that are in the product library.
The format of the publications is PDF, HTML, and BookManager®.
IBM posts publications for this and all other Tivoli products, as they become
available and whenever they are updated, to the Tivoli software information center
Web site. Access the Tivoli software information center by first going to the Tivoli
software library at the following Web address:
http://www.ibm.com/software/tivoli/library/
Scroll down and click the Product manuals link. In the Tivoli Technical Product
Documents Alphabetical Listing window, click the IBM Tivoli NetView for z/OS
link to access the product library at the Tivoli software information center.
x Programming: REXX and the NetView Command List Language

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 the following Web site:
http://www.elink.ibmlink.ibm.com/public/applications/publications/
cgibin/pbi.cgi
You can also order by telephone by calling one of these numbers:

v In the United States: 800-879-2755
v In Canada: 800-426-4968
In other countries, contact your software account representative to order Tivoli

publications.
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.
Tivoli technical training

For Tivoli technical training information, refer to the following IBM Tivoli
Education Web site:
http://www.ibm.com/software/tivoli/education
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:
v Searching knowledge bases: You can search across a large collection of known
problems and workarounds, Technotes, and other information.
v Obtaining fixes: You can locate the latest fixes that are already available for your
product.
v Contacting IBM Software Support: If you still cannot solve your problem, and
you need to work with someone from IBM, you can use a variety of ways to
contact IBM Software Support.
For more information about these three ways of resolving problems, see “Support
information” on page 177.
About this guide xi

Participating in newsgroups
User groups provide software professionals with a forum for communicating ideas,
technical expertise, and experiences related to the product. They are located on the
Internet and are available using standard news reader programs. These groups are
primarily intended for user-to-user communication and are not a replacement for
formal support.
Note: To access a newsgroup, use the instructions appropriate for your browser.
IBM Tivoli NetView for z/OS:
news://news.software.ibm.com/ibm.software.netview
Newsgroups for related products:
IBM Tivoli Business Systems Manager:
news://news.software.ibm.com/ibm.software.tivoli.business-systems-manager
IBM Tivoli Enterprise Console®:
news://news.software.ibm.com/ibm.software.tivoli.enterprise-console
IBM Tivoli NetView for UNIX and IBM Tivoli NetView for Windows:
news://news.software.ibm.com/ibm.software.tivoli.netview-unix-windows
Downloads
Clients and agents, demonstrations of the NetView product, and several free
NetView applications that you can download are available at the NetView for
z/OS Web site:
http://www.ibm.com/software/tivoli/products/netview-zos/
These applications can help with the following tasks:

v Migrating customization parameters from earlier releases to the current
stylesheet
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 cancelling 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
Conventions used in this guide

This guide uses several conventions for special terms and actions, operating
system-dependent commands and paths, and command syntax.
xii Programming: REXX and the NetView Command List Language

Typeface conventions
This guide 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 Words defined in text
v Emphasis of words (words as words)
v New terms in text (except in a definition list)
v Variables and values you must provide
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 guide uses the UNIX convention for specifying
environment variables and for directory notation.
When using the Windows command line, replace $variable with % variable% for
environment variables and replace each forward slash (/) with a backslash (\) in
directory paths. The names of environment variables are not always the same in
the Windows and UNIX environments. For example, %TEMP% in Windows
environments is equivalent to $TMPDIR in UNIX environments.
Note: If you are using the bash shell on a Windows system, you can use the UNIX
conventions.
Syntax Diagrams
Syntax diagrams start with double arrowheads on the left () and continue along
the main syntax line until they end with two arrowheads facing each other ().
When more than one line is needed for a syntax diagram, the continued lines end
with a single arrowhead ().
Position and Appearance of Syntax Elements

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 the
required, optional, and default values for keywords, variables, and operands as
shown in the following table.
About this guide xiii

Table 1. Position of Syntax Elements
Element Position Meaning
On the main syntax line Required
Above the main syntax line Default
Below the main syntax line Optional
Keywords and operands are shown in uppercase letters. Variables are shown in
lowercase letters and are either italicized or, for NetView help and BookManager
online books, shown in a differentiating color. The appearance of syntax elements
indicates the type of element as shown in the following table.
Table 2. Appearance of Syntax Elements
Element Appearance
Keyword CCPLOADF
Variable resname
Operand MEMBER=membername
Default today or INCL
Required Syntax Elements

The command name and the required keywords, variables, and operands are
shown on the main syntax line. Figure 1 shows that the resname variable must be
used for the CCPLOADF command.
CCPLOADF
CCPLOADF resname
Figure 1. Required Syntax Elements
Optional Syntax Elements

Optional keywords, variables, and operands are shown below the main syntax line.
Figure 2 shows that the ID operand can be used for the DISPREG command but is
not required.
DISPREG
DISPREG
ID=resname
Figure 2. Optional Syntax Elements
Default Keywords and Values

Default keywords and values are shown above the main syntax line.
If the default is a keyword, it is shown only above the main line. You can specify
this keyword or allow it to default. Figure 3 on page xv shows the default keyword
STEP above the main line and the rest of the optional keywords below the main
line.
xiv Programming: REXX and the NetView Command List Language

If an operand has a default value, the operand is shown both above and below the
main line. A value below the main 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 line is used. Figure 3
shows the default values for operands MODNAME=* and OPTION=* above and below
the main line.
RID
,STEP ,MODNAME=*
RID TASK=opid
,CONTINUE ,MODNAME= *
,END name
,RUN
,OPTION=*

,OPTION= *
HAPIENTR
HAPIEXIT
Figure 3. Default Keywords and Values
Syntax Fragments
Commands that contain lengthy sections of syntax or a section that is used more
than once in a command are shown as separate fragments following the main
diagram. The fragment name is shown in mixed case. Figure 4 shows a syntax
diagram with the fragments Pu, PurgeAll, and PurgeBefore.
CSCF
CSCF Pu
PurgeAll
PurgeBefore
Pu
PU=resname
,
,OP=( testop )
PurgeAll
PURGE ALL
PurgeBefore
PURGE BEFORE date

time
Figure 4. Syntax Fragments
About this guide xv

Commas and Parentheses
Required commas and parentheses are shown in the syntax diagram.
When an operand can have more than one value, the values are typically enclosed
in parentheses and separated by commas. For example, in Figure 4 on page xv, the
OP operand contains commas to indicate that you can specify multiple values for
the testop variable.
If a command requires positional commas to separate keywords and variables, the

commas are shown before the keyword or variable, as in Figure 3 on page xv.
Commas are also used to indicate the absence of a positional operand. In the
following example of the BOSESS command, the second comma indicates that an
optional operand is not being used:
NCCF BOSESS applid,,sessid
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.
xvi Programming: REXX and the NetView Command List Language

Chapter 1. Getting Started
The Tivoli NetView for z/OS program enables you to manage complex,
multivendor networks and systems from a single point. A command list is a set of
commands and special instructions that are grouped under one name, like a
computer program. For the NetView program, a command list can be written in
either Restructured Extended Executor language (REXX) or the NetView command
list language.
| Note: The use of REXX is recommended, as it has many functions and

| enhancements that are not available in the NetView command list language.
When you type a command list name at a terminal, the commands and
instructions in that command list are interpreted and processed. You can also run
command lists in other ways. For example, you can issue a timer command to run
a command list at a specified time or at time intervals. You can also run more than
one command list at the same time under different tasks. See “Running Command
Lists” on page 5 for more information.
This chapter describes how to:

v Create command lists
v Run command lists
v Use command lists
The Benefits of Using Command Lists

Command lists help you to automate and manage your network and improve an
operator’s efficiency. Command lists obtain information from operators, other tasks,
system resources, or messages. The command list uses this information to perform
processing or to decide the next action. This flexibility enables you to automate
repetitive or complex operations, perform resource recovery, and handle operations
consistently among different operators. For example, system programmers or
operators can write command lists to:
v Automatically issue command lists at a specified time or time interval using
NetView timer commands AT, EVERY, CHRON, and AFTER
v Under certain conditions, reword, delete, or reply to a message before the
operator sees it
v Provide for command lists to be issued automatically when specific messages or
management services units (MSUs) are received during the operation of systems,
networks, and applications
v Wait for the NetView program to receive a message or group of messages and
take action based on the message content
v Speed backup and recovery procedures, for example, automatic recovery of a
failing resource
v Monitor and restart subsystems and programs (for example, VTAM®, CICS®,
and TSO)
v Display information about an operator’s screen
v Simplify entry of operator commands
v Tailor operator commands and procedures for your network
© Copyright IBM Corp. 1997, 2005 1

Basic Topics
v Ensure completeness and correct order when a sequence of commands must be

issued
v Implement specialized operator dialogs that extend the operator’s role or
increase the efficiency and productivity of operators
Before you write a command list, analyze your system, network operating
procedures, and the tasks that operators regularly perform. Decide which of these
jobs you want to perform using command lists. Start by writing simple command
lists and add the more complex functions as you gain experience.
Note: This document does not describe how to use NetView operator commands.
If you need information about a specific command, refer to the NetView
online help or the IBM Tivoli NetView for z/OS Command Reference.
Examples of Common Startup Command Lists

If you want to set up terminal access facility (TAF) sessions with the Information
Management System (IMS™) and the Host Command Facility (HCF), you can use a
command list instead of entering individual commands.
Figure 5, written in REXX, establishes terminal access facility (TAF) sessions with
IMS and HCF.
/* STARTUP1 */
’BGNSESS OPCTL,APPLID=IMS1,SRCLU=TAF11,LOGMODE=OPCTLLOG,SESSID=IMS’
’BGNSESS OPCTL,APPLID=HCF1,SRCLU=TAF11,LOGMODE=OPCTLLOG,SESSID=HCFA’
’BGNSESS OPCTL,APPLID=HCF1,SRCLU=TAF12,LOGMODE=OPCTLLOG,SESSID=HCFB’
EXIT
Figure 5. STARTUP1 Command List
| Instead of having to remember and enter three commands, operators can enter the
| command list name STARTUP1. The command list starts the three sessions and
| operators receive the same messages they would receive if they had entered all
| three commands.
Examples of Activating a Network Control Program

You can write a command list to simplify the activation of a Network Control
Program (NCP). Figure 6 is an example of a REXX command list that activates an
NCP.
/* NCP1 */
’V NET,ACT,ID=NCP1,LOAD=YES,LOADSTA=LINK1’
EXIT
Figure 6. Example of Activating an NCP
Creating Command Lists

You can create command lists before the NetView program is started or while it is
running. Code each command list as a member of a command list partitioned data
set (PDS). After you create the command list, use facilities such as ISPF or
IEBUPDTE to update the command list.
| The PDS member name is the name you enter to run the command unless you
| define another name for the command list on a CMDSYN keyword on the
| CMDDEF statement. For more information about CMDSYN, refer to the IBM Tivoli
| NetView for z/OS Administration Reference.
2 Programming: REXX and the NetView Command List Language

Basic Topics
The command list name must begin with a nonnumeric character and can be from
one to eight characters. Valid characters are: 0–9 A–Z @ $ #.
After a command list is created and saved as a PDS member, it is ready for the
operator to use.
| Note: To avoid naming conflicts, give your user-written command lists names
| other than the command synonym (CMDSYN) names used for
| NetView-provided command lists. Also, your command list names should
| not begin with any of the 3-character prefixes used by the NetView
| program: AAU, BNH, BNJ, CNM, DSI, DUI, EZL, FLC, FKX, and FKV.
The NetView program supports command lists in data sets that are concatenated
across volumes.
1. Create the data set to be used to store the command lists.
2. Code each command list as a separate member of a command list data set. To
define the name of the command list data set to the NetView startup
procedure, code the JCL DD statement for the DSICLD as follows:
//DSICLD DD DSN=datasetname,DISP=SHR
3. Concatenate data sets by coding the DSICLD statement as shown in Figure 7.
//DSICLD DD DSN=datasetname1,DISP=SHR
// DD DSN=datasetname2,DISP=SHR
// DD DSN=datasetname3,DISP=SHR
// DD DSN=datasetnamen,DISP=SHR
Figure 7. Example of Concatenating Data Sets with the DSICLD Statement
4. Ensure that the first command list data set defined under DSICLD has the
largest block size of any concatenated command list data sets, or that the first
DD statement has a DCB=(BLKSIZE=xxxx) statement, where xxxx is equal to
the largest block size of the concatenated data sets.
Notes:
1. When the NetView program is operating on a z/OS system and you plan to
update or create command lists while the NetView program is running, define
your command list data sets without secondary extents. Otherwise, a command
list might be filed in a new extent.
If this occurs, a secondary extent failure can occur causing error recovery and
loss of a single instance of running the command list. If the error recovery
succeeds and a second attempt to call the command list is made, the command
list is then available.
| If the data set becomes full and you need to compress the data set to add more
| command lists, use the REACC command; for more information, see the IBM
| Tivoli NetView for z/OS Command Reference. You can also call a command list in
| any data set by reading the data set using the pipeline QSAM and saving the
| procedure in memory using INSTORE DSICLD.clistname; for more information,
| see IBM Tivoli NetView for z/OS Programming: Pipes.
2. The block size must be an even multiple of the record length and the record
length must be 80. The records must be formatted as fixed or fixed block at 80.
Ensure that the block size is 3920 or less to reduce paging caused by the block size
exceeding the size of a page of memory.
Chapter 1. Getting Started 3

Basic Topics
Controlling Access to Command Lists

You can use command authorization to specify the operators who can issue a
particular command list.
The following command-authorization methods are available:

v NetView command authorization table
v NETCMDS class of a System Authorization Facility product such as RACF®
Use the LIST SECOPTS command to determine which method is in effect.
The method for restricting access to commands is defined in CNMSTYLE and can
be changed dynamically using the NetView REFRESH command.
| The NetView program automatically checks the operator authorization for a

| command list before it is called. However, authorization for keywords and values
| must be checked by command list statements coded for that purpose, as follows:
| v The called command list can check the parameters that are passed and check the
| operator that called it. Then the called command list is coded to exit if it was
| called inappropriately.
| v REXX command lists can use the AUTHCHK() function.
| v You can start a command list from a PL/I or C command processor. Use the
| command processor to authorize a keyword and value, start the command list,
| and pass the operands to the command list. The command list must then be
| coded to verify that it was called properly using the genealogy list available
| from the PIPE ENVDATA command; for more information, see IBM Tivoli
| NetView for z/OS Programming: Pipes.
Generally, commands or command lists that are called from a command list are
also eligible for command authorization. An exception to this rule is when a
command list is called from the automation table, and AUTOSEC=BYPASS is in
effect; refer to the DEFAULTS command in the NetView online help for more
information. Another exception is when a command list is privileged by inclusion
in the DSIAUTB member of DSIPARM and uses the AUTBYPAS function described
in “Command List Information” on page 40.
For more information about how to protect command lists from unauthorized
users, refer to the IBM Tivoli NetView for z/OS Security Reference. For more
information about writing command processors in PL/I or C, refer to the IBM
Tivoli NetView for z/OS Programming: PL/I and C book.
Loading Command Lists into Storage

| The NetView program provides several means to preload data into main storage in
| order to reduce I/O and thereby improve performance. Two methods, MEMSTORE
| and LOADCL, are appropriate for REXX or NetView Command List Language
| procedures.
| MEMSTORE runs as an autotask and monitors usage of various members. It loads

| members into storage based on frequency of use, weighted by age. Usually,
| MEMSTORE will be started by your Style processing, with limits and exceptions
| appropriate to your installation having been set by your system programmer. If
| you make changes to any REXX or NetView Command List Language procedures,
| use the MEMSTOUT REFRESH procname command to ensure that MEMSTORE has
| not cached an older copy. When making many changes, as with testing, you may

Basic Topics
| want to issue MEMSTOUT UNLOAD DSICLD.procname to permanently prevent

| MEMSTORE from loading your procedure. For more information about
| MEMSTORE and MEMSTOUT, see the online help for these commands; additional
| information can also be found in IBM Tivoli NetView for z/OS Installation: Getting
| Started.
| Note: If you call a command list that has not been preloaded, the command list is
| loaded into main storage, run, and then dropped from main storage.
| Therefore, each time the command list is run, it must be retrieved from the
| auxiliary storage device where it resides. If you preload the command list, it
| can be run multiple times without having to be retrieved from auxiliary
| storage each time.
| The action of MEMSTORE affects all standard means of accessing a member of any
| of the NetView standard DD names. For example, if a REXX procedure has been
| loaded into main storage by MEMSTORE, and you use the BROWSE command to
| view the member, then BROWSE will show the data previously loaded, and you
| will see DATASET: 0 where the concatenation level is listed. Similarly, the LISTA
| DSICLD membname command will show an INSTORE level listing for the member.
| When the procedure is invoked, the member will be ″read″ or copied into another
| location, where it is formatted for interpretation. You can avoid this copying and
| formatting step and obtain a small additional performance enhancement by using
| LOADCL. Use LOADCL only for procedures in DD=DSICLD. After LOADCL, the
| BROWSE command will still show the member as it exists on auxiliary storage.
| However, you can use the LIST CLIST command to review the member as it exists
| in main storage.
Three NetView commands enable you to move command lists into and out of
main storage, and to list command lists that are currently in main storage:
LOADCL
| Works with DROPCL and MAPCL to provide information and control
| about procedures that have been loaded.
DROPCL
Drops a command list that was previously loaded into main storage using
the LOADCL command
MAPCL
Lists command lists that currently reside in main storage
For more information about the LOADCL, DROPCL, or MAPCL commands, refer
to the NetView online help.
The NetView program provides a REXX command list, AUTODROP (CNMS8003),

that can help you manage the number of command lists that are loaded into
storage using the LOADCL command. AUTODROP uses the MAPCL and
DROPCL commands to conditionally drop commands from main storage.
Running Command Lists

Design command lists that run with little assistance from operators. Some of the
ways you can run command lists are:
v When the NetView program is started
v When the operator logs on
v After receiving a message or MSU
v From a terminal

Basic Topics
v At a specified time or time interval

v From another command list
v From a user-written command processor
| v From the NetView management console
| v From a Web page
| v From a remote NetView domain
| v From user exits and optional tasks
Running Command Lists When NetView Is Started

| You can specify that command procedures run automatically when the NetView
| program is started by defining them in CNMSTYLE %INCLUDE member
| CNMSTUSR or CxxSTGEN using auxInitCmd statements. Refer to the IBM Tivoli
| NetView for z/OS Administration Reference for more information. These commands
| run under the primary program operator interface task (PPT). See “Primary POI
| Task Restrictions” on page 12 for information about PPT restrictions.
Running Command Lists When Logging On

You can define a command list to run automatically after an operator successfully
logs on. You can define only one command list to run when an operator logs on,
but this command list can activate other command lists. See “Running Command
Lists from Another Command List” on page 7 for rules that apply when calling
another command list.
Code the name of the command list you want to run in the operator’s profile using
the IC operand of the PROFILE statement, or the IC field in the NETVIEW
segment of the SAF product. For example, if you want to run the HELLO
command list each time an operator logs on, and if the operator has a profile of
PROFBEG, the IC operand can be added to the operator’s profile as follows:
PROFBEG PROFILE IC=HELLO
For more information about the PROFILE definition statement, refer to the IBM
Tivoli NetView for z/OS Administration Reference.
You can include many types of commands in your initialization command list. The
following list describes some of the commands you can include:
v To start autotasks, use AUTOTASK commands. Use START commands to start
other tasks, such as DSTs (data services tasks).
v To restore all task global variables that were saved using the GLOBALV SAVET
command, include:
GLOBALV RESTORET *
Note: The RESTORET depends on two things: the task having previously
performed a SAVET, and the DSISVRT DST being active.
v To set operator-specific defaults that override NetView-wide values set using the
DEFAULTS command, use the OVERRIDE command.
Running Command Lists after Receiving a Message or MSU

The NetView program’s automation table can initiate a command list upon receipt
of a message or MSU. These command lists can automatically respond to the
message or MSU, saving an operator from having to respond to them.
Command lists that the NetView program initiates upon receipt of a message or
MSU can contain a series of commands to perform a function as a result of the

Basic Topics
message or MSU. For example, if the message or MSU reported that an NCP failed,
the command list can issue the VTAM command to reactivate the NCP. See
Chapter 5, “Automation Resource Management,” on page 85 for more information.
Running Command Lists from a Terminal

You can enter a command list name from the terminal in the same way you enter
any other command and operands. When you enter the name of the command list,
the command list starts processing. Message responses and other information can
be sent to the operator, depending on how the command list is written.
Running Command Lists at a Specified Time or Time Interval

Operators can use the following NetView commands to run command lists at a
specified time or time interval:
AFTER
Instructs the NetView program to run the command list after a specified
period of time.
AT Instructs the NetView program to run the command list at a particular
time.
CHRON
Instructs the NetView program to run commands in varied and flexible
ways.
EVERY
Instructs the NetView program to run the command list repeatedly at a
certain time interval.
Note: You can also issue the AFTER, AT, CHRON, and EVERY commands from a
command list.
You can set up the AT, EVERY, CHRON, and AFTER commands so the command
list runs even if the operator is not logged on at the time. This is done with the
PPT operand or by issuing the timer command under an autotask. However, some
commands cannot be used in a command list running under the PPT. See “Primary
POI Task Restrictions” on page 12 for more information.
| You can define command lists so that they always interrupt the processing of other
| command lists. You do this using the TYPE=H (high priority) operand of the
| CMDDEF statement, or by prefixing your command with CMD HIGH. For more
| information about how to code CMDDEF statements, see the IBM Tivoli NetView for
| z/OS Administration Reference. For more information about the CMD command, see
| the online help.
To learn more about the AT, EVERY, CHRON, and AFTER commands, refer to the
NetView online help.
Running Command Lists from Another Command List

One command list can activate another command list. When a command list is
running under the control of another command list, it is nested within the calling
command list. To nest a command list within another command list, code the name
of the called command list as a command within the controlling command list.
When the NetView program reaches a statement with the name of a command list,
it starts running the nested command list. When the NetView program reaches the

Basic Topics
end of the nested command list, it returns control to the calling command list and
proceeds to the next statement, as shown in Figure 8.
CMDLISTA CMDLISTB CMDLISTC
statement1a statement1b statement1c

CMDLISTB statement4b statement4c
statement5a CMDLISTC statement5c
statement7a statement7c
statement8a EXIT
statement9a EXIT
EXIT
Figure 8. Nested Command Lists
When planning to create command lists that run other command lists, keep the
following in mind:
v A REXX command list can be called as a REXX command, subroutine, or
function.
v A REXX command list can call a command list written in the NetView command
list language as a command but not as a subroutine or a function.
v A command list written in the NetView command list language can call another
command list written in the NetView command list language or a REXX
command list as a command.
v Command lists written in REXX and command lists written in the NetView
command list language can call each other.
v You can have 250 levels of externally nested command lists.
Only REXX command lists called as commands, external subroutines, or external
functions count as one of the 250 levels of externally nested command lists. You
can call up to 250 REXX command lists as internal subroutines and functions,
but they do not count toward the 250 levels of externally nested command lists.
v You should test each command list before running the command list as part of a
nested chain of command lists.
For information about REXX subroutines and functions, refer to the REXX library.
Passing Information from One Command List to Another

When REXX command lists and command lists written in the NetView command
list language call each other, operands can be passed from the calling command list
to the nested command list. However, when the nested command list is finished,
only a return code is sent to the calling command list.
| In order to pass additional information, you can use pipeline’s SAFE, STEM, or
| VAR stages, or the global variable pool.
| SAFE stage
| NetView messages, or any other data in a pipeline, can be placed into a
| named SAFE stage by either the calling procedure or the called procedure.
| Named SAFE stages endure as long as any member of the nested family is
| still running. Either the calling procedure or the called procedure can add

Basic Topics
| to, modify, or delete data from the SAFE. See IBM Tivoli NetView for
| z/OS Programming: Pipes for more information about the SAFE stage
| KEEP stage
| The pipeline KEEP stage is similar to the SAFE stage, and will enable you
| to define a task-global place to store messages. See IBM Tivoli NetView for
| z/OS Programming: Pipes for more information about the KEEP stage.
| STEM stage and VAR stage
| Using pipeline STEM and VAR stages, a called procedure can read from
| and write to the calling procedure’s variables, if those variable names are
| known. A calling procedure written in REXX can control such access using
| REXX’s built-in PROCEDURE and EXPOSE keywords. For example, the
| WINDOW (CNME1505) procedure calls customer-defined subcommands
| from an internal procedure named exterCmd and limits variable access to a
| list named toShow. See CNME1505 and the example subcommand
| CNMEXEC for additional details on using this procedure.
| Global variables
| Procedures can store and modify data in COMMON or TASK global
| variables. The GLOBALV command provides one way to do this in a
| manner similar to using the pipeline VAR and STEM stages. Using the
| COMMON or TASK global variables allows data to be shared with other
| procedures, whether they are called directly or invoked by any other
| means. Be sure to provide a means of verifying the accuracy of any data so
| shared in case any of the procedures involved encounters a failure.
Error Handling
If a nested command list encounters an unrecoverable error, the command list ends
and passes the error back to the command list from which it was called.
Note: A list of return codes can be found at “Return Codes in REXX Command
Lists” on page 30.
If the calling command list is written in REXX, it might be able to take action to
recover from the error passed to it from the nested command list. For information
about coding REXX command lists that can recover from errors, see “Recovering
from Errors in REXX Command Lists” on page 31.
If the calling command list is written in the NetView command list language, and
an error occurs in the nested command list, the calling command list also ends. If
the calling command list was called by another command list, it continues to pass
the error back to the command list from which it was called.
Running Command Lists from a User-Written Command

Processor
You can write a command processor that calls a command list. Command
processors are programs written in assembler, PL/I, or C. For information about
how to write command processors, refer to IBM Tivoli NetView for
z/OS Programming: Assembler or IBM Tivoli NetView for z/OS Programming: PL/I and
C.

Basic Topics
Using Network Commands in Command Lists

This section describes how you can use network commands in command lists.
Some of the types of network commands you can include are:
v NetView commands
v User-written NetView commands
v VTAM commands
| The commands used within command lists are subject to command authorization,
| unless either SEC=BY was specified on the CMDDEF statement,
| AUTOSEC=BYPASS is in effect, or the command list is privileged by inclusion in
| the DSIAUTB member of DSIPARM and uses the AUTBYPAS function described in
| this manual. For more information, refer to the IBM Tivoli NetView for
| z/OS Administration Reference.
Notes:
1. The NetView RETURN command is not valid in a command list.
| 2. You can use NetView and user-written commands that are defined on the
| CMDDEF statement as regular, high, or both (TYPE=R, TYPE=H, or TYPE=B).
| You can also use command lists that are undefined.
3. You must use the appropriate prefix:
v NLDM for session monitor commands
v NPDA for hardware monitor commands
v STATMON for status monitor commands
Using System Commands in Command Lists

You can use system commands in command lists. For example, use one of the
following NetView MVS commands to enter MVS commands:
v MVS S jobname
v MVS D A,L
Refer to the NetView online help for more information.
Using Long-Running Commands in Command Lists

| Most NetView commands and some customer-written commands will block a
| calling procedure in order to wait for either operator input, data from an optional
| task, or some other asynchronous event. These commands are called long-running
| commands. You can use long-running commands in your command lists. Using
| long-running commands in your command list enables other commands on the
| low-priority queue to begin running. Refer to the NetView online help for more
| information about command priorities.
| Long-running commands use assembler macro DSIPUSH to accomplish the required

| wait while allowing essential NetView functions like message automation to
| continue. Additional information about the DSIPUSH macro can be found in IBM
| Tivoli NetView for z/OS Programming: Assembler. Examples of long-running
| commands are NPDA and VIEW.
The type of long-running command, and whether the command list uses the CMD
command to queue the command, determines whether the long-running command
or the issuing command list receives processing priority. This is described further
in “Queuing Long-Running Commands” on page 11.

Basic Topics
| When coding a long-running command, it is important to plan for two kinds of

| events that may occur during the extended period before your procedure’s next
| instruction:
| Implied Cancellation
| The operator generally has an opportunity to enter commands (although
| some exceptions are to be noted in IBM Tivoli NetView for
| z/OS Customization Guide). If the operator chooses to invoke the same
| long-running command (or VIEW with the same component name), then
| that procedure will be halted. For this reason, REXX procedures that
| invoke long-running commands should always code SIGNAL ON HALT.
| At that HALT label, code an EXIT –5 in addition to any other cleanup
| processing that you need to do. The –5 return code propagates the halt
| condition to the caller of the procedure, if any. You can also exercise some
| degree of control over this halt condition using the UNIQUE command.
| Refer to the IBM Tivoli NetView for z/OS Customization Guide for more
| information about UNIQUE.
| Interruption
| Normally, your procedure will not be interrupted by another command
| queued from message automation, operator action, a timed command, or
| an EXCMD from another commands (although some exceptions should be
| noted in the command help for the DEFAULTS command). When a
| long-running command is invoked, the wait for operator input can be
| protracted, so NetView invokes any other commands that are queued. This
| may affect your procedure if you use global variables or if you query and
| then take action on the status of any external resource.
Queuing Long-Running Commands

You can control the processing of long-running commands by using the NetView
CMD command to queue them. Queuing a long-running command causes it to be
processed independently of your command list. The result of the long-running
command does not influence the result of the command list. When you queue a
long-running command, the return code indicates the result of the queuing
operation only. You cannot get a return code from the queued command.
To delay the processing of NLDM until your command list is stacked, canceled,
interrupted, or completed, use CMD LOW NLDM.
Using NetView Pipelines

NetView pipelines provide another level of function and flexibility to command
lists. Among many pipeline capabilities is the automation of full-screen
applications. For more information, refer to IBM Tivoli NetView for
z/OS Programming: Pipes or the NetView online help.
Using the VIEW Command

You can use the VIEW command in command lists to display panels. The VIEW
command has access to local and global variables set in the command list that
issues the VIEW command and to NetView local variables.
Refer to the IBM Tivoli NetView for z/OS Customization Guide for more information
about local and global variables, and using the VIEW command with commands
and command lists.

Basic Topics
Using Full-Screen Commands

If a command list that is run from a full-screen processor issues a full-screen
command, the NetView program can display the command facility panel before
displaying the output of the full-screen command. The command facility panel is
displayed only if the command list generates any other output that is displayed to
the operator. Display of the command facility panel suspends any AUTOWRAP
setting and prevents the full-screen output from being automatically displayed. To
minimize the possibility of displaying command facility panel output, define and
code the command list so that it does not generate any other output to be
displayed. For example:
| v Code a CMDDEF definition statement with ECHO=N for the command list.
| Refer to the IBM Tivoli NetView for z/OS Administration Reference for information
| about coding a CMDDEF statement.
v Code TRACE ERRORS or TRACE OFF at the beginning of a REXX command
list. Refer to the REXX library for information about the TRACE instruction.
v Do not code SAY instructions in a REXX command list.
v Code &CONTROL ERR at the beginning of a command list written in the
NetView command list language.
v Do not code &WRITE or &BEGWRITE control statements in a command list
written in the NetView command list language.
v Do not issue commands that have line mode output.
Note: If a command list encounters a statement with a timeout greater than 30

seconds while a full-screen command processor is running, the following
message is issued:
DSI594A COMMAND PROCEDURE cmdlistname WARNING - type STATE ENTERED
You can then enter the necessary information if the command list is waiting
for an operator response, or ensure that a WAIT or &WAIT is satisfied
before rolling to other components.
Primary POI Task Restrictions

Command lists can run under the primary POI task (PPT). However, when
possible, command lists should be run under an autotask. See “AUTOTASK OST
Restrictions” on page 13 for more information about running command lists under
an autotask.
You can run command lists under the PPT when the command lists meet any of
the following criteria:
v Routed to the PPT for processing as a result of NetView automation.
v Coded on a CNMSTYLE definition statement to run when the NetView program
is initialized.
v Called with an AT, EVERY, AFTER, or EXCMD command that uses the PPT as
an operand. (PPT on AT, EVERY, and AFTER enables the command to be run
even when the operator who scheduled it is not logged on.)
The following restrictions apply to command lists that run under the PPT:
v In general, you cannot use full-screen commands and immediate commands. Do
not use the following NetView commands:
| – AUTOWRAP
| – BGNSESS
| – INPUT

Basic Topics
| – LOGOFF
| – ROUTE
| – SET
| – SUBMIT
v Do not use the following REXX instructions:
– FLUSHQ
– MSGREAD
– PARSE EXTERNAL
– PARSE PULL if there is nothing in the REXX data stack
– PULL if there is nothing in the REXX data stack
– TRAP
– WAIT
v Do not use the following NetView command list language control statements:
– &PAUSE
– &WAIT
| Note: When command lists running under the PPT generate messages containing
| non-Latin characters (such as double-byte characters) that are routed to the
| system console, the messages go to the authorized receiver. If no authorized
| receiver exists, authorized receiver messages should not be generated
AUTOTASK OST Restrictions

This restriction applies to automation tasks that are started with the AUTOTASK
command:
v Use the ATTACH command if you want to automate full screen commands.
Because autotasks have fewer restrictions than the PPT, use them instead of the
PPT whenever possible.
Controlling Command List Output

You can control the amount of data displayed to the operator during the
processing of a command list. Responses to commands in the command list or
messages the command list sends to the terminal screen can be displayed to the
operator.
To control the amount of data displayed to the operator during the processing of a
REXX command list, use the NetView PIPE CONSOLE command, TRAP
instruction, or the suppression character (see “Suppressing Display of Non-REXX
Commands” on page 23). Refer to the NetView online help and the REXX library
for information about the TRAP instruction.
To control the amount of data displayed to the operator during the processing of a
command list written in the NetView command list language, use the &CONTROL
statement (see “&CONTROL Statement” on page 104), the &WAIT SUPPRESS
control statement (see “Customizing the &WAIT Statement” on page 135) or the
suppression character (see “Conventions for Suppression Characters” on page 93).
| The commands and messages displayed during processing of a command list

| appear in the message area of the NetView command facility panel. Generally,
| output from the command list is preceded by a type code of C. For a complete
| description of the NetView panel layout and the format of messages sent to the
| panel, refer to the IBM Tivoli NetView for z/OS User’s Guide.

Basic Topics
| Working with Messages

| A message is an object that is made up of the following:
| v An optional reply ID
| v One or more lines of text
| v Attributes associated with each line of text
| v Attributes associated with the message as a whole
| There is, at most, one current message at any given time. The current message is set
| by the most recent occurrence of any of these events:
| v Message automation. The message that triggered the automation is the current
| message when the procedure is invoked. See Chapter 5, “Automation Resource
| Management,” on page 85 for more information about NetView automation.
| v A pipeline. When invocation of the procedure is triggered by a message passed
| from a previous stage, then that message becomes the current message.
| v For REXX, a MSGREAD that occurs after a successful TRAP of a message. For
| NetView CLIST language, an &WAIT. See “Control and Parameter Variables
| Used with &WAIT” on page 133 for more information about using control
| variables with &WAIT.
| v When the procedure invokes a NetView pipeline with SAFE * operating as a
| ″not first″ stage.
| v When the results of a LINKPD command are processed. See “LINKPD Results”
| on page 151 for more information about the LINKPD command.
| All of the means of setting a current message that are listed above will return data
| from the current message regardless of how that message was made the current
| message. For a multiline write-to-operator message (MLWTO), only the first line of
| the message is considered by these functions.
| Information about the current message can be retrieved using the REXX functions or
| NetView CLIST variables (refer to “Message Processing Information Functions” on
| page 48), MSU functions (refer to “REXX Management Services Unit Information
| Functions” on page 62), or message information commands (refer to “Commands
| Used in Command Lists” on page 160).
| Notes:
| 1. Usually, the first blank-delimited word from the first line of text is considered
| the message ID. A reply ID, if present, is ignored.
| 2. To test for the existence of a current message, issue this command:
| PIPE SAFE * | COUNT | VAR MSGCOUNT
| If variable MSGCOUNT contains a 0, there is no current message; if

| MSGCOUNT contains a 1, there is a current message.
| 3. REXX functions that return data pertinent to the current message do so
| regardless of how the message was made current. For multiline messages, only
| the first line is considered by these functions, unless documentation for that
| function states otherwise.
| 4. When a MSGREAD, &WAIT, PIPE SAFE *, or LINKPD occurs, the resulting message
| becomes the current message, even if the message is null (such as when
| MSGREAD has RC=4).

Chapter 2. REXX Language Overview
This chapter includes a brief introduction to REXX. Not all of the features and
syntax rules of REXX are described in this document. This document focuses
primarily on the REXX instructions and functions provided by the NetView
program.
| Note: For complete information about REXX, refer to the TSO/E REXX library.
Introduction to the REXX Language

REXX is often used as an interpretive language; the REXX interpreter operates
directly on the program as it runs, line-by-line and word-by-word. An interpreted
language is different from other programming languages, such as COBOL, because
it is not necessary to compile a REXX command list before running it. However,
you can choose to compile a REXX command list before running it to reduce
processing time.
As with all non-NetView REXX execs and macros, each NetView REXX command
list or Data REXX file must begin with a comment. REXX comments are marked
with /* at the beginning and */ at the end, and can be used in your REXX
command list wherever necessary.
A REXX command list or Data REXX file consists of a series of clauses, each
having a separate purpose. In a simple REXX command list, the clauses are
interpreted in the sequence in which they are coded. You can control the sequence
in which clauses are run by using specific commands that alter the processing
order.
A REXX instruction tells the REXX interpreter to do something. A REXX instruction

is identified by its keyword, which must be the first item in the clause.
When an equal sign (=) is the second item in a clause, the clause is identified as an
assignment clause. Assignment clauses enable you to give a value to a variable.
Variables enable you to define different values for the clauses within a command
list.
When the second item in a clause is a colon (:), the clause is interpreted as a label.
Labels identify the target statement for a transfer of control.
The REXX language enables you to call internal or external routines, called
functions. REXX function names must always be followed by parentheses. There
can be up to 10 expressions, separated by commas, between the parentheses. An
expression is something that can be computed. The REXX interpreter performs the
computation named by the function and returns a result. The result is then used in
the expression in place of the function call. To use a function, place the function
name in the command list or Data REXX file at the location where you want the
result to be accessed. There are also several built-in functions included in the REXX
language that perform predefined operations. Refer to the REXX library for a
complete description of the features of the REXX language.

REXX Language Overview
Compiling and Running REXX Command Lists

REXX command lists can be compiled to significantly improve performance.
The IBM REXX/370 compiler product must be installed on the system where the
command lists will be compiled.
Refer to the REXX library for directions on how to compile a REXX command list.
For additional performance information about compiled REXX command lists, refer
to the IBM Tivoli NetView for z/OS Tuning Guide.
Notes:
1. You do not need to install or start the compiler on the system where the
NetView program resides.
2. The compiled executable file might be larger (take up more space) than the
original uncompiled command list.
3. The NetView program supports the CEXEC (compiled EXEC) and OBJECT
(object deck) output formats of the REXX/370 compiler.
4. When creating a load module from an object deck, note the following items:
v The object deck must be created and saved from a REXX compiler.
v Two DDNAMEs in the REXXL cataloged procedure are particularly
important:
– The SYSIN DD statement must refer to the object deck (input).
– The SYSLMOD DD statement must refer to the load library specified with
the load module (output).
– The object deck must be link-edited with the EFPL stub to create a load
module, and the load module name cannot conflict with any NetView,
REXX, or other load module name.
| – The REXXL cataloged procedure is used to create a load module; the
| procedure can be found in REXX.V5R2M0.EAGPRC.
– The load module can only be called through or by a REXX CALL
instruction, or as a REXX function.
5. To run CEXEC format compiled REXX command lists, place the output file into
a member of one of the DSICLD data sets.
6. Install the compiler run-time library in an authorized library on the system that
runs the compiled REXX command lists.
| Using Data REXX

| Data REXX files are special REXX programs that send data (rather than commands)
| to an environment external to the Data REXX program.
| For any NetView application that supports %INCLUDE processing, you can
| substitute a Data REXX program file for the member that the application ordinarily
| reads. The data generated by your program becomes the data delivered to the
| application.
| The REXX language supports an external ADDRESS environment. Generally, this is

| for commands to be invoked. In the case of Data REXX, the only ADDRESS
| environment supported is NETVDATA. The character strings submitted to the
| NETVDATA environment will become data instead of commands. This data is
| delivered to the application after the Data REXX program file is read and
| processed. No trace of the REXX language elements in the Data REXX program is
| seen by the application.
| Note: In this discussion, the term generated data is used to mean data that contains
| REXX variables or function calls that must be evaluated before the data is
| ready to be sent to the receiving application. One example of a receiving
| application is a phase of style sheet processing during NetView
| initialization.
| By definition, Data REXX files are any NetView data files that begin with the Data
| REXX file directives /*%DATA or /*%LOGIC in the first column of the first record.
| The Data REXX file directives determine the format of the Data REXX code that
| follows the directive. These directives provide a convenient way of switching
| between the logic and data formats. The following paragraphs further describe
| these directives.
| When the /*%LOGIC Data REXX directive is in effect, data is embedded or

| generated in a Data REXX program the same way commands are in a traditional
| REXX program. This is also referred to as logic mode.
| When the /*%DATA directive is in effect, embedded or literal data is programmed

| exactly as the application program expects to see it. REXX programming, including
| generated data clauses for the NETVDATA address environment, is written with
| %> in columns 1 and 2 of each record. This is also referred to as data mode.
| Sample BNJMBDST is an example of a logic file. Sample CNMCMSYS is an

| example of a data file. Sample CNMSTASK uses both data and logic formats.
| Data mode is a convenient way to write large sections of the Data REXX program
| that contain literal data that can be written exactly as the receiving application will
| receive the data. Data that you program dynamically generated in whole or in part
| must be preceded with %> in columns 1 and 2 of the Data REXX program file. For
| example, to create a data record with the domain name of the NetView program
| on which your application is currently running, you might code the following
| starting in column 1:
| %> ’My domain name is’ domain()’.’
| If the domain name of the NetView program on which your application is

| currently running is CNM01, then the following data record is read:
| My domain name is CNM01.
| If a Data REXX generated data record is written to be continued on the next

| record, include %> at the beginning of column 1 of the next record. For example,
| to write a continuation for the previous example that contains the version and
| release of the NetView program on which your application is currently running,
| code the following starting in column 1:
| %> ’My domain name is’ domain() ’and my NetView version is’,
| %> substr(netview(),3,1) ’and release is,
| %> substr(netview(),4,1)’.’
| If the domain name of the NetView program on which your application is

| currently running is CNM01, and the NetView program version is 5 and the
| release is 2, then the following data record is read:
| My domain name is CNM01 and my NetView version is 5 and release is 2.
| Processing Data REXX Files

| When a NetView application reads a Data REXX program file, processing occurs in
| three steps:
Chapter 2. REXX Language Overview 17

| 1. A REXX program is loaded. A NetView application must use the NetView

| DSIDKS services to access Data REXX files and have them processed as Data
| REXX files. When DSIDKS services finds the file member, it reads the first
| record of the file and determines if the file begins with one of the two Data
| REXX directives. If it does, then the Data REXX file is loaded into storage in its
| entirety. As it is loaded, the file is reformatted into a form that the REXX
| interpreter can run. If in data mode, the records are loaded so that the %>
| symbols are not seen by the REXX interpreter. Records without leading %>
| symbols are loaded in such a way that they are presented to the NETVDATA
| address environment without being evaluated by the REXX interpreter.
| Records that are read in logic mode are read into storage unchanged. The Data
| REXX directives are not removed because they appear to REXX as REXX
| comments and are ignored, but not removed. Note that %INCLUDE statements
| are not processed at this time.
| 2. The REXX program runs to completion. After loading the REXX program, the
| program is passed to the REXX interpreter to run. While running, any REXX
| clauses that appear to REXX as external commands are sent to the NETVDATA
| address environment. These commands are actually the data records that are
| collected by NetView and passed to the NetView application. Note that
| %INCLUDE statements can be generated by the Data REXX program during
| this step.
| 3. The resulting data is read by the application. After all the data records have
| been collected by NetView, they are passed to the NetView application. It is
| transparent to the NetView application whether the file being read is a Data
| REXX program. Note that during this step that any %INCLUDE statements are
| processed as they are encountered by DSIDKS services. Included files are also
| checked to determine if they are Data REXX files (as determined by the first
| line) and are processed, independently, in the same three-step manner if they
| are.
| During the first step, each line of the source file is processed individually.
| However, in the second step, REXX interprets the entire Data REXX program
| according to the rules of the REXX language. Thus, REXX elements on one line can
| affect how the following lines are interpreted. For example, consider the following
| Data REXX file:
| 1 /*%DATA Put any comments you want here. */
| 2 %> x = cglobal(’y’); /* getting a value for x
| 3 PASSWORD = XYZ
| 4 %> any comment */
| 5 %> IF tower(’AON’) THEN
| 6 AUTOCMD.mytable.ORDER = C
| Note the absence of %> coding in lines 3 and 6.
| If the tower(’AON’) function is evaluated as true, then the following record is

| generated by the example:
| AUTOCMD.mytable.ORDER = C
| During the first step, line 3 is loaded. However, line 3 is never seen during step 3
| because the REXX comment start delimiter, /*, in line 2 matches the REXX
| comment end delimiter, */, in line 4.
| Line 6 is conditional on the previous IF-THEN evaluation, although it is not

| prefixed with the %> data REXX designator. Line 6 is not evaluated by the Data
| REXX interpreter, despite its similarity to REXX code. This line is sent exactly as
| written to the NETVDATA address environment (if the tower(’AON’) function is

| evaluated as true). The same is true if line 6 was an %INCLUDE instruction. In

| such a case, the %INCLUDE statement is processed by the NetView program after
| the Data REXX program completes.
| Additional Information
| The following information applies to both data and logic files:
| v Data REXX is supported only in the following:
| – CNMCMD
| – CNMSTYLE
| – DSICNM
| – DSIOPF
| – automation tables
| – code point tables
| – command authorization tables
| – command facility panel-format definition members, such as CNMSCNFT
| – hardware monitor (NPDA) members (but not BNJHEADR)
| – members read using NetView disk services with the INCL option
| – operator profile (DSIPRF) members
| – session monitor (NLDM) members
| – span tables
| – the HELPMAP
| v Data REXX is not supported in VSAM files.
| v REXX clauses that are processed as commands in a normal REXX environment
| are instead passed to the NETVDATA environment. As a result, these clauses are
| seen as data by the application reading the member.
| v Data REXX files should be small because they are read entirely into storage.
| Note that %INCLUDE files that are referenced in a Data REXX file are also read
| into storage if they are Data REXX files; files that are not Data REXX files are not
| read entirely into storage. Therefore, to save storage, do not use Data REXX files
| in %INCLUDE files.
| v Output strings that result from SAY and TRACE instructions are written to the
| network log.
| v The REXX keyword instruction ADDRESS can be used; however, the only
| address that is supported is NETVDATA.
| v The following REXX functions cannot be used in Data REXX files:
| – GETMSG
| – LISTDSI
| – MSG
| – MVSVAR
| – OUTTRAP
| – PROMPT
| – SETLANG
| – STORAGE
| – SYSDSN
| – SYSVAR
| v The following REXX keyword instructions cannot be used in Data REXX files:
| – TRACE ? (interactive trace)
| – PARSE EXTERNAL
| v The PULL and PARSE PULL instructions can be used only to access data from
| the REXX data stack. Do not use PULL and PARSE PULL to pause for operator
| input. Data REXX has no operator input facility.
| v REXX functions invoked from Data REXX using synonym names are not
| supported during NetView initialization CNMSTYLE processing.

| Data REXX Directives

| The Data REXX file directives determine the format of Data REXX code. These
| directives provide a convenient way of switching between the logic and data
| formats.
| /*%DATA
| The NetView REXX /*%DATA directive specifies data mode for the Data REXX
| code that follows it. The file remains in data mode until either the /*%LOGIC
| directive is encountered or the end of file (EOF) is reached.
| The syntax for the NetView REXX /*%DATA directive is:
| /*%DATA
| /*%DATA comments*/
|
| where:
| /*%DATA
| The /*%DATA directive must begin with the / in column one. A space is
| required after DATA and the word DATA must be in all capital letters. The file
| must begin with either a DATA or LOGIC directive in the first line.
| comments
| Specifies any comments that you want to include. Comments can span
| multiple lines.
| */ Specifies the end of the DATA directive.
| Usage Notes:
| v In data mode, all REXX instructions must be preceded by %> in column one.
| Lines that do not begin with %> are treated as data.
| Example: The following is an example of how to code Data REXX in data mode:
| /*%DATA --- demonstrate data mode */
| Data line (this line has two leading blanks)
| %>IF CGLOBAL(’ABC’) = 1 THEN
| %INCLUDE ABCFILE
| %>ELSE
| %> DO
| %> ’%INCLUDE’ CGLOBAL(XYZfilenameVar)
| Another data line
| %> END
| Final data line
| Related Statements: /*%LOGIC
| /*%LOGIC
| The NetView REXX /*%LOGIC directive specifies logic mode for the Data REXX
| code that follows it. The file remains in logic mode until either the /*%DATA
| directive is encountered or the end of file (EOF) is reached.
| The syntax for the NetView REXX /*%LOGIC directive is:
| /*%LOGIC

| /*%LOGIC comments*/
|
| where:
| /*%LOGIC
| The /*%LOGIC directive must begin with the / in column 1. A space is
| required after LOGIC and the word LOGIC must be in all capital letters. The
| file must begin with either a DATA or LOGIC directive in the first line.
| comments
| Specifies any comments that you want to include. Comments can span
| multiple lines.
| */ Specifies the end of the LOGIC directive.
| Usage Notes:
| v REXX clauses are processed as commands in a normal REXX environment are
| instead passed to the NETVDATA environment. As a result, these clauses are
| seen as data by the application reading the member.
| v In logic mode, REXX instructions must not be preceded by %>.
| Example: The following is an example of how to code Data REXX in logic mode:
| /*%LOGIC --- demonstrate logic mode */
| ’ Data line (this line has two leading blanks)’
| IF CGLOBAL(’ABC’) = 1 THEN
| ’ %INCLUDE ABCFILE’
| ELSE
| DO
| ’%INCLUDE’ CGLOBAL(XYZfilenameVar)
| ’Another data line’
| END
| ’Final data line’
| Related Statements: /*%DATA
Coding Conventions for REXX Command Lists and Data REXX Files
This section describes the syntax rules that apply when coding REXX command
lists or Data REXX files for the NetView program.
Record Size
| The data portion of records in REXX command lists or Data REXX files for the
| NetView program can be up to 80 characters in length (the records must be a fixed
| length of 80 characters). If the first record of a REXX command list or Data REXX
| file contains numeric characters in columns 73 through 80, the command list or
| Data REXX file is assumed to contain sequence numbers. The NetView program
| will remove the sequence numbers from lines containing executable statements or
| Data REXX control statements. That is, sequence numbers are preserved on lines
| that are known to be data-only (those lines that are contained within a /*%DATA
| section and are not prefixed with %>). The NetView program also truncates
| trailing blanks from all REXX records in REXX command lists and Data REXX files.
| Blank REXX records are not discarded, but are truncated to one blank character.
Using Quotation Marks

To avoid variable substitution on a string in a REXX command list or Data REXX
file in logic mode, enclose the string in either single quotation marks (') or double
quotation marks ("). The quotation marks signify that you do not want REXX to

perform variable substitution on the string. That is, you do not want the REXX
interpreter to interpret the string. When REXX encounters a beginning quotation
mark (single or double) on a command list statement or Data REXX statement, it
stops interpreting until it reaches a matching ending quotation mark.
Do not enclose REXX instructions in quotation marks. REXX recognizes its own
instructions and does not perform variable substitution on REXX instructions. The
following examples show how to use quotation marks to prevent variable
substitution with the REXX SAY instruction:
SAY ’THIS IS A STRING WITH SINGLE QUOTATION MARKS’
SAY "THIS IS A STRING WITH DOUBLE QUOTATION MARKS"
These two instructions display the following at your terminal when using REXX or
writes to the network log when using Data REXX:
THIS IS A STRING WITH SINGLE QUOTATION MARKS
THIS IS A STRING WITH DOUBLE QUOTATION MARKS
To use an apostrophe or double quotation marks within the text of a string

enclosed in quotation marks, you can do the following:
| SAY "IT’S EIGHT O’CLOCK. TIME TO BRING UP CICS."
| SAY ’IT’’S EIGHT O’’CLOCK. TIME TO BRING UP CICS.’
| SAY ’PLEASE ENTER "GO NODENAME" OR "GO STOP"’
| SAY "PLEASE ENTER ""GO NODENAME"" OR ""GO STOP"""
In the following example, either of the first two instructions displays the first line
or writes to the network log when using Data REXX. Either of the last two
instructions display the second line:
IT’S EIGHT O’CLOCK. TIME TO BRING UP CICS.
PLEASE ENTER "GO NODENAME" OR "GO STOP"
Generally, you enclose any NetView commands, or system commands recognized

by the NetView program, in quotation marks. The exception is when you want
variable substitution to take place on an operand of such a command. If you want
variable substitution to take place, leave the operand outside the quotation marks.
| Note: NetView commands cannot be issued from Data REXX files. The only
| address environment supported by Data REXX is ADDRESS NETVDATA.
| When REXX clauses are treated as external commands by REXX, they are
| treated as external data by Data REXX.
For example, if you want to use the NetView INACT command in a command list
to deactivate a node named NODE1, code:
’INACT NODE1’
However, if the command list contains a variable named NODE and you want to
deactivate the node whose name is the current value of the NODE variable, code:
’INACT ’ NODE
The next example uses quotation marks to have REXX perform variable
substitution for only part of a command. The example assumes that the DDNAME
has already been allocated. This example first parses the user’s input into a
variable called DDNAME. The TSO/E EXECIO command is then used to read a
line of that DDNAME. ADDRESS MVS is a REXX instruction, so it is not enclosed
in quotation marks. The quotation marks begin before EXECIO because it is a
TSO/E command. The quotation marks end before DDNAME to enable REXX to
substitute the current value of the DDNAME variable into the EXECIO command.

The rest of the EXECIO command is enclosed in quotation marks so that variable
substitution does not take place on the STEM and LINE operands.
ARG DDNAME
ADDRESS MVS ’EXECIO 1 DISKR ’ DDNAME ’ ( STEM LINE’
Notes:
1. Use caution when writing REXX clauses that have quoted strings that span
multiple records. Because the NetView program truncates trailing blanks from
all REXX command list records before running the command list, REXX clauses
that have quoted strings that span multiple records might not run as expected.
For example, in the following set of REXX clauses that span records, The
NetView program removes the blanks in the middle of the quoted string from
the output.
Enter the following:
say ’ABC
DEF’
The output is:

ABCDEF
All the trailing blanks were removed between the characters C and D.
Blanks that are to be retained are coded on the next line as in the following
example:
say ’ABC
DEF’
The output is:

ABC DEF
2. When it is necessary to continue a quoted string on the next line in a NetView
command list, code the following:
SAY ’THIS IS AN EXAMPLE OF A LONG’,
’QUOTED STRING’
The output is:
THIS IS AN EXAMPLE OF A LONG QUOTED STRING
Notice that the continuation comma displays a blank at your terminal after
displaying the first quoted string. If you do not want the space, you can use
concatenation bars to eliminate it. This is useful when you code long system
commands in your command list. Code the concatenation bars as follows:
SAY ’THIS IS AN EXAMPLE OF A LONG QUO’||,
’TED STRING’
The output is:
THIS IS AN EXAMPLE OF A LONG QUOTED STRING
Suppressing Display of Non-REXX Commands

| Use the REXX TRACE command to control the echoing of REXX instructions. Use
| the SUPPCHAR statement in CNMSTYLE or its included members to suppress
| non-REXX (for example, NetView) commands.
| Notes:
| 1. IGNRLSUP is ignored for commands issued from a REXX command list.
| 2. FOLDUP is ignored for commands issued from a REXX command list.
| Refer to the IBM Tivoli NetView for z/OS Command Reference for more information.

| When issuing a command that returns its status in the return code, you can
| enhance the performance of your command list by suppressing synchronous
| output from the command. To suppress synchronous output, code the suppression
| character twice. If the suppression character is not known, or it might change, or a
| suppression character is not explicitly defined in CNMSTYLE or its included
| members, use the following general form for suppression:
| SUPPCHAR()||SUPPCHAR()||’SET PF24 IMMED RETRIEVE’
| No synchronous output from the command is displayed to the operator.
Use the double suppression character when sufficient status is provided by the
return code and to enhance performance of commands that produce line mode
messages synchronously. Using the double suppression character does not affect
output that is scheduled by a command (for example, D NET,APPLS), nor does it
reliably reduce output from a long-running command (for example, NLDM).
See the SUPPCHAR() function in “Session Information Functions” on page 77 for

more information about suppression characters. You can also do suppression with
the HOLE stage of the PIPE command. Refer to IBM Tivoli NetView for
z/OS Programming: Pipes for information.
NetView Restrictions on REXX Instructions

This section describes the restrictions that apply when coding REXX instructions in
REXX command lists for the NetView program.
Pausing for Operator Input

The REXX instructions (PARSE EXTERNAL, PARSE PULL, PULL, and TRACE ?)
cause a command list to pause for operator input.
| Note: You cannot use this method to communicate with the operator if your
| command list might be used from the NetView management console, from
| the NetView Web application, on an autotask, or for some attended MVS
| console interfaces or might be called remotely by the EXCMD or RMTCMD
| command.
Using the PARSE EXTERNAL or PARSE PULL instructions along with other
instructions, you can code command lists that ask the operator questions and pick
up entered responses. Use the REXX SAY instruction to describe what the operator
should enter. Code the PARSE EXTERNAL or PARSE PULL instruction after the
SAY instruction to temporarily stop the command list (unless, in the case of PARSE
PULL, there is data on the REXX data stack). After the command list has
temporarily stopped, the operator enters the NetView GO command before it
continues. Any data to be passed to the command list is to be entered as an
operand or operands on the GO command. For example, to have the command list
process a YES or NO answer from the operator, code the following SAY and
PARSE EXTERNAL instructions:
SAY ’ENTER "GO YES" OR "GO NO" TO CONTINUE’
PARSE EXTERNAL ANSWER
The operator responds to the command list with either GO YES or GO NO. The
GO command causes the command list to continue processing, and the YES or NO
value is picked up by the PARSE EXTERNAL instruction by placing the value in
the variable ANSWER.

For restrictions on using PARSE EXTERNAL, PARSE PULL, PULL, and TRACE in
Data REXX files, see “Using Data REXX” on page 16.
Using the SAY Instruction

The REXX SAY instruction enables a character string of any length; however,
| NetView can display only 32 000 characters at a time.
| When you issue a REXX SAY instruction in a REXX command list for the NetView
| program, a header precedes the data displayed on the operator’s screen. The
| header is defined by the screen format member in effect and, by default, is 12
| characters in length.
For Data REXX files, output strings that result from the SAY and TRACE
instructions are written to the network log.
Do not use MSGID() as the first item of output from a SAY instruction because the
text of the SAY instruction is processed as a regular NetView message. This
processing can cause the message to be trapped by a TRAP instruction and can
incorrectly satisfy a WAIT instruction, or cause automation processing to loop.
Using the CALL Instruction

| Use the REXX CALL instruction to pass data (arguments) in a way that can be
| parsed more easily by the called routine. For more information about the CALL
| instruction, refer to the TSO/E REXX library. However, when you use the CALL
| instruction, the called program cannot access variables in the calling program by
| PIPE VAR and STEM stages.
| Be careful when you use the CALL instruction to call a REXX command list from
| another REXX command list. The command list you call is treated like a
| subroutine, and some data is shared between the initial command list and the
| called command list. For example, trapped message queues, values of NetView
| commands (such as GETMLINE), and the values of message processing REXX
| functions (such as MSGID) are shared between the two command lists. To prevent
| this sharing of data, call the routine as a NetView command rather than using the
| CALL instruction. Note that this options is not available in Data REXX.
NetView Restrictions on REXX Functions

This section describes the restrictions that apply when coding REXX functions in
REXX command lists or Data REXX files for the NetView program.
Some REXX functions return different values depending on the operating system
under which the command list containing the functions runs. For example, DATE()
returns the current date in different formats depending on the operating system.
The REXX LINESIZE() function always returns the value 32 728 when used in
REXX command lists or Data REXX files for NetView.
For restrictions on using REXX functions in Data REXX files, see “Using Data
REXX” on page 16.
Use the REXXSTRF keyword on the DEFAULTS or OVERRIDE command to enable

the REXX STORAGE() function.
Note: The REXX STORAGE() function cannot be used in Data REXX files.

Writing REXX Function Packages

You can write your own REXX function packages for the NetView program. The
NetView program supplies two dummy directories to help you write function
packages for use with NetView REXX command lists. One directory is for a user
function package (DSIRXUFP), and the other directory is for a local function
package (DSIRXLFP).
Link-edit the real directory and function code into load module DSIRXUFP for a
user function package or into DSIRXLFP for a local function package. As part of
coding the interface to your function code, use the NetView DSIRXEBS macro to
obtain a new EVALBLOCK.
Refer to the REXX library for instructions on coding a real directory and coding
the interface to your function code.
Refer to IBM Tivoli NetView for z/OS Programming: Assembler for information about
the DSIRXEBS macro and function packages, and about writing function package
directories.
Refer to IBM Tivoli NetView for z/OS Installation: Configuring Additional Components
and the IBM Tivoli NetView for z/OS Tuning Guide for information about improving
the performance of REXX function packages for the NetView program.
Changing the Environment Addressed by REXX Command Lists

REXX command lists for the NetView program use NETVIEW as the default
addressing environment. If you want to change the environment, use the REXX
ADDRESS instruction. For example, if you want your command list to run MVS
subcommands, first change the addressing environment with an ADDRESS MVS
instruction.
In ADDRESS MVS, you can use the following commands:

v DELSTACK
v DROPBUF
v EXECIO
v MAKEBUF
v NEWSTACK
v QBUF
v QELEM
v QSTACK
v SUBCOM
v TE
v TS
Refer to the TSO/E REXX library for more information about these commands and
the REXX ADDRESS instruction.
In the NETVIEW addressing environment, the entire command string is converted

to uppercase characters. If you want to issue a command using lowercase
characters, change the addressing environment to NETVASIS, as follows:
address netvasis 'WTO This is a mixed case message.'

Notes:
1. The only valid addressing environments recognized in a NetView REXX
command list are NETVIEW, NETVASIS, and those supported by TSO/E REXX
in any MVS address space.
2. Programs such as SDSF that do program calls will abend if they are linked or
attached. For example, the NetView status monitor and the subsystem router
are examples of programs that can perform program calls. NetView cannot link
or attach to any such program that can perform program calls.
3. The NetView program does not support a TSO/E environment in the NetView
address space.
4. The NetView program returns an error if you try to run a command that is
routed to an incorrect addressing environment.
5. The ADDRESS command only supports address environment NETVDATA
when issued from Data REXX files.
Data REXX Host Command Environment

NETVDATA is the host command environment for Data REXX. No other
environments are supported. This host command environment does not support
commands.
Using the EXECIO Command

If you use the EXECIO command in a command list, code the command list so that
it issues an EXECIO command with the FINIS option before the command list
completes its processing. If the command list using EXECIO is part of a nested
chain of command lists, code the chain so that one of the command lists issues
EXECIO with the FINIS option before the chain of command lists completes
processing.
Coding the chain this way enables you to use SIGNAL ON HALT to try to recover
if EXECIO with the FINIS option encounters an error closing a file. If the EXECIO
command encounters an error, it sets the RC variable to a nonzero return code.
Refer to the REXX library for information about return codes used by the EXECIO
command.
If you use EXECIO to read or write a member of a partitioned data set (PDS) and
are not sure whether the member exists, use the NetView REXX FNDMBR(...)
function to determine the members existence before issuing the EXECIO command.
See “PRINT Example” on page 172 and “TYPE Example” on page 174 for examples
of how EXECIO can be used in a REXX command list.
Note: The EXECIO command cannot be used in Data REXX files.
Using MVS and VTAM Commands

MVS and VTAM commands are examples of asynchronous commands. To obtain
the output of these commands for processing by your procedure, use either
| NetView pipelines or the techniques described for TRAP and WAIT.
| Notes:
| 1. When REXX clauses are treated as external commands by REXX, they are

| 2. Pipelines are not supported with Data REXX files.
Using the NetView ALLOCATE and FREE Commands

The NetView program provides the ALLOCATE and FREE commands to enable
you to dynamically allocate and deallocate data sets from the NetView program.
These commands closely resemble the TSO/E commands for allocating and
deallocating data sets. However, because these commands are provided by the
NetView program, you do not need to use the ADDRESS MVS instruction when
using these commands in a command list. Simply enclose the commands in
quotation marks as you do for other NetView commands. The TYPE, TYPEIT, and
PRINT examples in Appendix G, “Examples of REXX Command Lists for
NetView,” on page 163 use the NetView ALLOCATE command.
Refer to the NetView online help for the syntax of the ALLOCATE and FREE
commands.
| Note: When REXX clauses are treated as external commands by REXX, they are
Using REXX Command Lists

Each time a REXX command list is run in the NetView program, REXX sets up a
REXX environment for the NetView program. When the command list ends, this
unique environment can be held for reuse by the same task. If two command lists
are running at the same time on one operator task (for example, one command list
is suspended while the other is running), two environments are required. Any
REXX command lists called from another REXX command list use the caller’s
REXX environment.
Before running REXX command lists, consider how many concurrent REXX
command lists are usually active for any given NetView task. NetView retains up
to 10 REXX environments and their associated storage until you log off, unless you
use the DEFAULTS or OVERRIDE command to change the number of REXX
environments retained. Refer to the NetView online help for additional information
about the DEFAULTS and OVERRIDE commands.
The NetView program retains REXX environments to improve REXX environment

initialization performance. If more than one REXX environment is available when a
REXX command list is run, the REXX command list can run using a different
REXX environment. Whether this occurs depends on the order in which other
REXX command lists were started and ended during concurrent processing of the
REXX command lists. Storage associated with each REXX environment can increase
depending on the needs of the REXX command lists. Since each REXX command
list can have different storage needs, REXX environments can grow to meet the
needs of the most demanding REXX command list.
You can reduce the number of REXX environments the NetView program retains,
to minimize the storage each task using REXX requires. However, if you set this
number to zero, the NetView program does not save any REXX environments and
the initialization performance of every REXX command list is affected.
Consider the storage required to initialize a REXX environment before running any
REXX command lists. By default, REXX gets sufficient storage for a REXX

command list with about six levels of nested calls. You can change the acquired
storage amount with the DEFAULTS or OVERRIDE command.
REXX command lists that use large numbers of REXX variables or that nest more
than six levels cause the storage to increase as needed. Each REXX command list
requires approximately 12K of storage to start. If you set the amount of
initialization storage to zero, storage is acquired as needed, but performance is
degraded for the first REXX command list using this REXX environment.
Notes:
1. Two entries in the REXX IRXANCHR table are required for each non-nested
NetView or REXX command list to run. If a REXX command list is called from
another REXX command list, a new environment is not required. The nested
command list uses the environment of the primary command list.
2. A recommended default number of REXX environments slots in IRXANCHR
for the NetView program is twice the maximum number of command lists that
can be scheduled to run concurrently under all active NetView tasks, plus one
for Data REXX for each active NetView task.
Nesting REXX Command Lists from Assembler, C, or PL/I

Each time a REXX command list is nested by an assembler, C, or PL/I command
processor, a unique REXX environment is created for that REXX command list. The
data stacks from any previous REXX command lists in the nested chain are not
passed to the additional unique environment. For example, if a REXX command
list calls a PL/I command processor and the PL/I command processor calls
another REXX command list, an additional unique REXX environment is created
for the second REXX command list.
The number of unique REXX environments that can be created at one time is
limited by MVS. Therefore, your nested chains are also limited in the number of
REXX command lists that can be called by the assembler, C, or PL/I command
processors.
Refer to the REXX library for information about the maximum number of
environments in an address space.
Parsing in REXX Command Lists

In a REXX command list, you can parse character strings using either the REXX
PARSE instruction, the NetView PARSEL2R command, or the PIPE EDIT stage.
PARSEL2R is provided by the NetView program to make an instruction equivalent

to the REXX PARSE instruction available in both the NetView command list
language and REXX. The REXX PARSE instruction performs better than
PARSEL2R, and you should use it where possible.
When you use PARSEL2R in a REXX command list, enclose the command in
quotation marks to avoid variable substitution. For example:
TITLE = ’PROCEDURE/ACTION NOT SUPPORTED: X'’087D’'’
’PARSEL2R TITLE A1 A2 A3 A4 A5 A6 A7 A8’
Refer to the NetView online help for information about the PIPE EDIT and
PARSEL2R commands. Refer to the REXX library for information about the REXX
PARSE instruction.

Note: Data REXX supports only the REXX PARSE instruction.
Tracing REXX Command Lists

During the creation of a REXX command list for the NetView program, you can
see how the REXX interpreter evaluates an expression using the TRACE START
(TS) command. The TS command sets an indicator that is checked by the REXX
interpreter when it starts to interpret a command list or when control is returned
to a command list after a nested command list completes. The syntax of the TS
command is:
TS
TS
After receiving the following message:

CNM431I REXX INTERACTIVE TRACE. ENTER ’GO TRACE OFF’ TO END TRACE,
ENTER ’GO’ TO CONTINUE.
enter GO TRACE OFF to end the trace, or enter GO to continue tracing. Also, after
receiving one of the messages indicating a trace point is reached, you can enter GO
followed by a command or instruction you want to run at a given point in the
command list. For example, to set a variable to a certain value at that point in the
command list, you can enter:
GO X=5
Or, to display the current value of a variable, you can enter:

GO SAY ’VAR1 CURRENTLY IS ’VAR1
If you enter a TS command but decide before the trace begins that you do not
want to run the trace, use the TRACE END (TE) command to cancel the trace. You
can also use the TE command to end a trace that is not interactive.
Note: The TS and TE commands are not supported in Data REXX.
The syntax of the TE command is:
TE
TE
For more information about TS and TE, refer to the NetView online help.
Return Codes in REXX Command Lists

The REXX return code variable, RC, is set after completion of each instruction,
command, or nested command list. You can use the EXIT statement in a nested
command list to end the command list and set RC to a value that is passed back to
the calling command list. RC is not given an initial value when a command list
begins.
Possible RC values and their meanings are as follows:

Values Meaning

0 No error. The command, instruction, or nested command list completed

successfully.
–1 The command, instruction, or nested command list encountered an error.
The –1 return code passes control to the FAILURE label if you code
SIGNAL ON FAILURE.
| –3 The command or nested command list is not authorized for this operator
| or the REXX ADDRESS environment is not valid. The –3 return code
| passes control to the FAILURE label if you code SIGNAL ON FAILURE.
–5 The command list is canceled. The –5 return code passes control to the
HALT label if you code SIGNAL ON HALT.
Others
Other return codes are set by individual commands, instructions, or nested
command lists.
See “Recovering from Errors in REXX Command Lists” for more information about
using the SIGNAL instruction with the NetView program.
Recovering from Errors in REXX Command Lists

When an error occurs in a REXX command list, you can use the SIGNAL
instruction to enable processing to continue at a certain point. If the REXX
command list calls a command processor that is external to REXX, such as TRAP
or WAIT, use the SIGNAL instruction to handle error conditions from that
command processor. A command list can encounter an error for the following
reasons:
v An error exists in the coding of the command list.
v The command list is part of a nested chain, and one of the other command lists
in the chain contains an error that is passed back to the calling command list.
v An operator enters a command that causes an error in the command list.
If an error occurs, the SIGNAL instruction passes control to another part of the
command list. Depending on the error condition, the SIGNAL instruction can pass
control to three different labels in the command list. These labels are as follows:
v SIGNAL ON FAILURE passes control to a label named FAILURE when the error
condition results in a negative return code. The only negative return codes
returned by the NetView program are –1 and –3. However, if your command list
calls user-written commands, control is passed to FAILURE when any negative
return code, except –5, is returned.
If your command list recovers from the error, you can return the appropriate
return code to the calling command list. If your command list does not recover
from the error, pass the failure to the calling command list with EXIT –1.
v SIGNAL ON ERROR passes control to a label named ERROR when any
command or function in your command list returns a positive return code.
Control is also passed to ERROR when you do not code SIGNAL ON FAILURE
and a command or function returns any negative return code except –5.
The return code you pass to any command list that nested your command list
should reflect the severity of the error. A zero (0) return code is recognized by all
NetView commands as an indication of successful completion, while all positive
return codes indicate that an error occurred.
v SIGNAL ON HALT passes control to a label named HALT when the command
list is canceled. A command list is canceled when:

– A RESET NORMAL command is run on the current operator task while your
command list is running.
– A CLOSE IMMED command is run on any task in your NetView program
while your command list is running. The command list continues processing
as long as it does not issue NetView commands.
– During SNA sessions, an operator presses the Attn key while your command
list is running.
– A command issued by your command list is canceled or returns a return code
of –5.
– The operator’s terminal session is lost for any reason, including the operator
entering the LOGOFF command, while the command list is running.
To pass the HALT condition to any command list that nested your command list,
end the command list with EXIT –5.
Notes:
1. If you do not code SIGNAL ON HALT, the NetView program passes the halt
condition to the command list that nested your command list.
2. Whenever you call another REXX command list as a function or subroutine, the
following statement of the command list tests the RESULT variable for the –5
cancel condition.
3. If you code SIGNAL ON FAILURE, the NetView program passes only the halt
condition to the calling command list if you code EXIT –1.
For more information about the SIGNAL instruction, refer to the REXX library.

Chapter 3. REXX Instructions for Command Lists Run in a
NetView Environment
Some instructions used in REXX command lists for the NetView program are
provided as part of the NetView program so that REXX command lists can
perform specific NetView activities. Because these instructions are provided by the
program and are not standard REXX instructions, they can be used only in
command lists that run in a NetView environment. These instructions do not
function in REXX EXECs that are running in non-NetView environments. The
REXX instructions provided by the NetView program can be used only in
command lists, and are not available for entry at operator consoles. To handle error
conditions, code the SIGNAL instruction in any REXX command list that uses one
of these NetView instructions.
This chapter contains a description of each REXX instruction provided by the

NetView program, how the instruction works, and how to code the instruction in a
REXX command list.
See Appendix E, “Comparison of REXX and NetView Command List Language,”

on page 155 for a complete list of the REXX instructions that are equivalent to
NetView command list language control statements. This list includes both
instructions provided by NetView and instructions provided by REXX.
The REXX instructions provided by the NetView program are:

v TRAP
v WAIT
v MSGREAD
v FLUSHQ
v GLOBALV
Note: These instructions are not supported by Data REXX.
Pipelines, called with the PIPE command, provide both extended function and
reduced complexity for the automation of message handling. The PIPE command
is therefore a recommended alternative to the TRAP and WAIT instructions.
For information about NetView pipelines, refer to IBM Tivoli NetView for
z/OS Programming: Pipes.
For more information about REXX syntax rules and information about other REXX
instructions, refer to the REXX library.
TRAP, WAIT, and MSGREAD monitor the operator station task (OST) for specific
messages or wait for a specified period of time.
Use the TRAP command to define the messages for which the command list
should wait. When a TRAP instruction is issued, NetView begins monitoring the
operator task for an occurrence of a specified message. If the message is received,
it is stored in a message queue.
When a WAIT command is issued, the command list stops processing until one or
more of the messages specified on the TRAP instruction are received or until the

NetView REXX Instructions
specified period of time elapses. When a WAIT instruction completes, the value
returned by the EVENT() function will indicate the reason that the WAIT
instruction completed.
If the operator task receives any of the messages specified on a TRAP instruction,
you can use the MSGREAD instruction to read the trapped messages from the
message queue. The command list can then take action based on the content of
each message.
The FLUSHQ instruction is used to remove all trapped messages from the message
queue.
The GLOBALV command defines, gets, puts, saves, restores, and purges tasks and
common global variables in REXX command lists.
Refer to the NetView online help for more information about these REXX
instructions and their syntax.
Using TRAP in Nested REXX Command Lists

You can code a TRAP command in a REXX command list that contains nested
command lists. Nested REXX command lists can also contain a TRAP instruction.
However, trapped messages are available only to the command list that issued the
TRAP instruction.
Note: The TRAP instruction cannot be used in Data REXX files.
REXX command lists called as subroutines or functions are considered to be part of

the calling command list. Therefore, TRAP commands issued from subroutines or
functions operate the same as if they were called in the calling command list.
If you used the REXX CALL instruction to call the nested command list, trapped
messages that have not been removed using MSGREAD remain available because
the trap message queue is shared with the nested command list. However, if you
called the nested command list without using the CALL instruction, the trapped
messages are available only to the command list that issued the TRAP instruction.
Note: If a nested command list ends before trapped messages return and these
same messages were being trapped by the calling command list, the
messages are available to the calling command list and are placed in the
message queue. It is possible, therefore, for the message queue to grow large
enough for the NetView program to run out of storage.
To prevent that from happening, you can do one of the following:

v End the calling command list.
v Issue the instruction TRAP NO MESSAGES.
v Issue the instruction FLUSHQ periodically.
Using WAIT in Nested Command Lists

| Any REXX command list called as a regular command list can issue a WAIT
| instruction.
Notes:
1. The WAIT instruction cannot be used in Data REXX files.

| 2. If the command list starts VIEW, you do not need to use the WAIT instruction
| to wait for messages or to wait for operator input. For more information on
| VIEW, refer to the IBM Tivoli NetView for z/OS Customization Guide.
The following considerations apply when using WAIT with nested command lists:
v Messages that arrive for the waiting command list are queued until the nested
command list finishes processing.
v If you specify the same message number on TRAP instructions in both the
waiting and nested command lists, the message satisfies the WAIT in the nested
command list.
v If you used the REXX CALL instruction to call the nested command list, trapped
messages that have not been removed using MSGREAD remain available
because the trap message queue is shared with the nested command list.
However, if you called the nested command list without using the CALL
instruction, the trapped messages are available only to the command list that
issued the TRAP instruction.
Using MSGREAD in Nested Command Lists

You can code MSGREAD in both a nested REXX command list and the initial
REXX command list. If you use the REXX CALL instruction to call a nested
command list, trapped messages are available to both the initial and nested
command lists. If you call a nested command list without using the CALL
instruction, trapped messages are available only to the command list that issued
the TRAP instruction.
Note: The MSGREAD instruction cannot be used in Data REXX files.
Functions Set by MSGREAD

The MSGREAD instruction affects all REXX functions that refer to the current
message.
For example, if MSGREAD is used to read the following message from domain
DOM01:
DSI008I SPAN1 NOT ACTIVE
The following functions are set:

Variable Value
MSGORIGN() DOM01
MSGID() DSI008I
MSGSTR() SPAN1 NOT ACTIVE
MSGCNT() 3
MSGVAR(1) SPAN1
MSGVAR(2) NOT
MSGVAR(3) ACTIVE
MSGVAR(4)–MSGVAR(31) null
For more information about these and other message processing functions, see
“Message Processing Information Functions” on page 48 and “MVS-Specific
Message Processing Information” on page 55.
Chapter 3. REXX Instructions for Command Lists Run in a NetView Environment 35

Notes:
1. Before a MSGREAD instruction is issued, the values of MSGID(),
MSGORIGN(), and MSGSTR() are null. The value of MSGCNT() is 0. The
MSGVAR(n) functions retain any values they are given when the command list
is run.
2. If you issue a MSGREAD instruction when the message queue is empty, the
values of MSGID(), MSGORIGN(), MSGSTR(), and MSGVAR(n) are set to null.
The value of MSGCNT() is zero.
3. If MSGREAD reads a multiline message, the functions are set according to the
first line of the message. Refer to the GETM commands in the NetView online
help or the IBM Tivoli NetView for z/OS Command Reference for information
concerning working with multiline messages.
4. The MSGVAR(1)–MSGVAR(31) functions can be given values when a command
list is called in the same way as the &1–&31 NetView command list language
parameter variables. If MSGVAR(1)–MSGVAR(31) are given values when the
command list is called, save those values in variables before issuing a
MSGREAD instruction. This lets you use the values that are modified by
MSGREAD.
5. After using MSGREAD, save the values of the message functions in variables
before issuing another MSGREAD instruction.

Chapter 4. REXX Instructions for NetView REXX Command
Lists and Data REXX Files
The NetView program provides a number of REXX functions for use only in
NetView REXX command lists and Data REXX files. These functions are provided
as part of the NetView program so that command lists and Data REXX files written
in REXX can perform specific NetView activities. Because these functions are
provided by the NetView program and are not standard REXX functions, you can
use them only in command lists and Data REXX files that run in a NetView
environment. These functions do not run in any REXX execs that are run in
non-NetView environments.
You can improve the performance of your REXX command list by limiting the use
of REXX functions provided by the NetView program. If the same function,
provided by NetView, is used several times in the command list without a change
in value, use the function once to set a local variable to the function’s returned
value. You can then use the local variable in place of the function. If the value
returned by the function might change during processing of the command list, you
need to use the function each time (instead of the local variable) to access its
current value.
The functions provided by the NetView program return values based on system
information. To use a function, you must place the function name in the REXX
command list at the location where you want the information to be accessed.
When the command list runs, the NetView program returns the current value of
the function’s related system information.
The functions let you obtain information about the operating environment, test
conditions in a command list, and take actions based on the results.
Note: For more information about REXX syntax rules and other REXX functions,
refer to the REXX library.
See Appendix E, “Comparison of REXX and NetView Command List Language,”

on page 155 for a complete list of the REXX functions that are equivalent to
NetView command list language control variables. This list includes both functions
provided by the NetView program and functions provided by REXX itself.
The tables in this chapter show the tasks performed by each NetView REXX
function and equivalent NetView command list language control variable used in
NetView command lists. The tables are listed by NetView functions. REXX
functions and equivalent NetView command list language control variables are in
alphabetical order, with the REXX function shown first.
In the tables, the function and control variable are followed by the description.
Notes:
1. Where both a NetView command list language control variable and a REXX
function exists for a task, descriptions are given generically without the NetView
command list language ampersand prefix or the REXX open/close parentheses
suffix.

REXX Functions
2. Where NetView command list language control variables and REXX versions of
a function differ operationally, descriptions for each are given separately; the
NetView command list language control variable description contains only the
differences between the two versions.
3. REXX functions provided for use by the NetView program can be used only
with the NetView program. These functions are not supported by the REXX
interpreter and cannot be used in REXX execs run in a non-NetView
environment.
4. Not all NetView REXX functions can used in Data REXX files. See the function
description to determine if a function can be used in a Data REXX file.
5. REXX functions listed in Table 8 on page 49, Table 9 on page 55, and Table 10
on page 63 return a value consistent with no message to process when used in
Data REXX files.
Translation Functions
Table 3. Translation Functions
Function or Variable Description
CODE2TXT(table,code) Provides translation for various types of code points to national language text.
You can use the NetView program with a problem management database to open
problem records when NetView alerts are received. The code point translation function
is provided in REXX to translate the numeric code points received in the alert into
readable text.
The syntax of the CODE2TXT function follows:
CODE2TXT
CODE2TXT(table,code)

Translation
Table 3. Translation Functions (continued)

CODE2TXT(table,code) where:
(continued)
code
Indicates the code point to translate. This field should be specified as a 1-4
character value representing the hexadecimal code point. The characters can be
uppercase or lowercase. Leading zeros are ignored but are counted as characters
in the four character limit.
Code points in the SNADATA tables are only two characters. To make them the
same length as code points in other tables, CODE2TXT adjusts your code by
concatenating "00" on the end (for example, "DD" becomes "DD00" and "01"
becomes "0100"). Refer to the BNJ82TBL sample and the IBM Tivoli NetView for
z/OS Customization Guide for more information.
table
Specifies the name of the table to use in the translation. The following are valid
tables:
SNAALERT Systems Network Architecture (SNA) alert description code
point
SNACAUSE SNA probable cause code point
SNADDATA SNA detailed data code point from subfield X'82'
SNADDAT5 SNA detailed data code point from subfield X'85'
SNADDAT6 SNA actual action code point for resolution major vector
SNAFCAUS SNA failure cause code point
SNAICAUS SNA install cause code point
SNAREACT SNA recommended actions code point
SNAUCAUS SNA user cause code point
An example of using CODE2TXT follows:

CODE2TXT(SNAALERT,362B)
The example translates code point 362B in the SNAALERT table to “TRANSMITTER
FAILURE”.
Error Processing: Error conditions encountered by this function are handled as follows:
v Non-valid operand: If a non-valid operand (such as a non-valid table name) is
detected, the NetView program issues message CNM432I (non-valid operand). A
REXX syntax condition flag is raised and the REXX interpreter then generates a
message.
v Non-valid code syntax: If a non-valid syntax is detected, the NetView program
issues message CNM423I (non-valid syntax). A REXX syntax condition flag is raised
and the REXX interpreter generates a message.
v Too many operands: Extraneous operands are ignored.
v Code point not found in table: A null string is returned, but no flag is raised.
Translation
Table 3. Translation Functions (continued)

| SUBSYM(symbolic) Returns a literal or variable character string (any character string that has multiple
| MVS system symbolics or a single MVS system symbolic imbedded in it) with the
| MVS system symbolics replaced within that string.
| Substitution is always performed on the &DOMAIN symbolic, unless substitution was

| disabled when NetView was started. For MVS and user-defined system symbolics,
| substitution is not performed if you are not running on an MVS system; you are
| running on an MVS system prior to MVS Version 5 Release 2; substitution was
| disabled when NetView was started; or you have not defined an MVS system symbolic
| on your MVS system.
| The syntax of the SUBSYM function follows:
| SUBSYM
| SUBSYM(symbolic)
| where:
| symbolic
| Specifies the name of the MVS system symbolic.
| An example using SUBSYM to find out the name of the &DOMAIN follows:
| SUBSYM(’&DOMAIN’)
Command List Information

Table 4. Command List Information
AUTBYPAS For information about this function, refer to the IBM Tivoli NetView for z/OS Security
Reference.

Table 4. Command List Information (continued)

AUTHCHK(keyword=value)
This REXX-only function enables you to make a command security check for keywords
and values from a REXX program. This enables you to check the parameters that are
passed to the command list, or any other items you would like to check as keywords
and values related to this command list.
The syntax of the AUTHCHK function is as follows:
AUTHCHK ( keyword=value )
keyword
where:
keyword
Specifies the keyword to be authority checked. Each keyword can contain a
maximum of 8 characters. A maximum of twenty keywords with optional values
can be passed to the program. Because variable substitution can yield a null
keyword, AUTHCHK can accept a null keyword. For example, AUTHCHK() is a
valid call of the AUTHCHK function. When a null keyword is passed to the
AUTHCHK function, authority is assumed to be granted for that particular
keyword.
value
Specifies a value for the keyword. Each value can contain a maximum of 8
characters. You cannot specify value without keyword=.
Because variable substitution can yield a null value, AUTHCHK can accept a null
value and strip the ‘=’ sign to yield a ‘keyword only’ security check. For example,
after variable substitution, this is a valid call of the AUTHCHK function:
AUTHCHK(keyword1=,keyword2=value2,keyword3,keyword4=value4)
Keywords and keyword=value combinations must be separated by commas.
Usage notes:
1. If the keyword and value are both null, the null string is returned, which
implies that authority is granted.
2. keyword=value can be any of the following:
v The value of a single variable.
v Two variables with ‘=’ in between. The = sign must be enclosed in single
quotation marks.
v Two literal strings with ‘=’ in between. The = sign must be enclosed in
single quotation marks.
v A literal and a variable with ‘=’ in between. The = sign must be enclosed in

AUTHCHK() (continued) If all keyword or keyword=value combinations in the list pass authority checking,
AUTHCHK returns a null string. Otherwise, the first keyword to fail authority
checking is returned and any remaining keywords are not checked. If a value fails
authority checking, the first keyword=value combination to fail is returned and any
remaining keywords are not checked. If a syntax error occurs, the keyword or the
keyword=value combination containing the syntax error is returned and the remaining
keywords are not checked.
For example, if a REXX program was run by entering NVRXCMD START,LU=LU200,

authority checking of the keywords START and LU=LU200 can be done by coding the
following in the NVRXCMD program:
/* NVRXCMD:
SAMPLE REXX PROGRAM
*/
PARSE ARG P1’,’P2’,’.
RESULT=AUTHCHK(P1,P2)
...
IF RESULT¬=’’ THEN
DO
SAY OPID() ’IS NOT AUTHORIZED TO KEYWORD/VALUE’ RESULT
EXIT
END
...
In this example, if either of the parameters passed in the variables P1 and P2 does not
pass authority checking, a non-null value is returned by AUTHCHK. If a keyword
fails, it is included in a message and the REXX program ends. If a value fails, the
keyword and value are included in a message and the REXX program ends. For
example, if OPER1 enters NVRXCMD START,LU=LU200, but is not authorized to use the
START keyword, OPER1 IS NOT AUTHORIZED TO KEYWORD/VALUE START is displayed and
NVRXCMD ends. If OPER1 enters NVRXCMD START,LU=LU202, but is not authorized to
use the value LU202, OPER1 IS NOT AUTHORIZED TO KEYWORD/VALUE LU=LU202 is
displayed and NVRXCMD ends.
For information about keyword security, refer to the RACF library and the IBM Tivoli
NetView for z/OS Administration Reference.


AUTHCHKX(command,
keyword=value) This REXX-only function enables you to make a command security check for a
command and its associated keywords and values from a REXX program. This enables
you to check a command and any keywords, keywords and values or any other items
you would like to check as keywords and values related to the command. The syntax
of the AUTHCHKX function follows:
AUTHCHKX (command, keyword=value )

keyword
where:
command
Specifies the command to be used for the authorization checks. This is a required
parameter. If a null command is passed, a syntax error occurs. Each command can
contain a maximum of 8 characters.
keyword
Specifies the keyword to be authority checked. Each keyword can contain a
maximum of 8 characters. A maximum of nineteen keywords with optional values
can be passed to the program. Because variable substitution can yield a null
keyword, AUTHCHKX accepts a null keyword. For example, AUTHCHKX(command)
is a valid call of the AUTHCHKX function. When a null keyword is passed to the
AUTHCHKX function, authority is assumed to be granted for the command that
was passed in the function call.
value
Specifies a value for the keyword. Each value can contain a maximum of 8
characters. You cannot specify value without keyword=.
Because variable substitution can yield a null value, AUTHCHKX can accept a
null value and strip the ‘=’ sign to yield a ‘keyword only’ security check. For
example, after variable substitution, this is a valid call of the AUTHCHKX
function:
AUTHCHKX(command,keyword1=,keyword2=value2,keyword3,keyword4=value4)
Keywords and keyword=value combinations must be separated by commas.

AUTHCHKX()(continued)
Usage notes:
1. This function does not perform any syntax checks of the command, keywords or
values. It can only determine if a combination of command, keyword and/or value
is protected using any NetView security facility.
2. If the keyword and value are both null, the null string is returned, which implies
that authority is granted.
3. keyword=value can be any of the following:
v The value of a single variable.
v Two variables with ‘=’ in between. The = sign must be enclosed in single
quotation marks.
v Two literal strings with ‘=’ in between. The = sign must be enclosed in single
quotation marks.
v A literal and a variable with ‘=’ in between. The = sign must be enclosed in
4. If all keywords or keyword=value combinations in the list pass authority checking,
AUTHCHKX returns a null string. Otherwise, the first keyword to fail authority
checking is returned and any remaining keywords are not checked. If a value fails
authority checking, the first keyword=value combination to fail is returned and the
remaining keywords are not checked.
For example, if a NetView command list language program NVCLCMD needs to
perform authority checks on two parameters passed to it, it can call REXX program
NVCHKAUT as: NVCHKAUT NVCLCMD, &P1, &P2. NVCHKAUT can be coded
as follows:
/* NVCHKAUT: SAMPLE REXX PROGRAM */
PARSE ARG P1’,’P2’,’P3’,’.
RESULT=AUTHCHKX(P1,P2,P3)
...
IF RESULT ¬= ’’ THEN
DO
SAY OPID() ’ IS NOT AUTHORIZED TO ISSUE ’P1’ WITH ’RESULT
Return_Code = 8
END
...
Return Return_Code
In this example, if either of the parameters passed in P2 and P3 does not pass
authority checking with the command passed in P1, a non-null value is returned
by AUTHCHKX. If a keyword fails, it is included in a message along with the
command that was passed, the REXX program sets a return code of 8 and returns.
If a value fails, the keyword and value are included in a message along with the
command that was passed, the REXX program sets a return code of 8 and returns.
For example, if OPER1 enters NVCLCMD START, LU=LU200, but is not authorized
to use the START keyword, the message ″OPER1 IS NOT AUTHORIZED TO ISSUE
NVCLCMD WITH START″ is displayed, NVCHKAUT returns a return code of 8 to
NVCLCMD and NVCLCMD ends.
For information about keyword security, refer to the RACF library and the IBM
Tivoli NetView for z/OS Security Reference.
CMDNAME() This REXX-only function returns the name by which the program was called. This
name can be the same as the name returned in the third token by the REXX PARSE
SOURCE command. This name is the command as it was entered, which is possibly a
synonym.
For Data REXX, this function returns the member name of the file that is being
processed.


PARMCNT() Returns the number of parameter variables that are entered when a command list is
initiated. For example, if command list RESC is initiated by entering RESC ACT,LU200,
&PARMCNT then PARMCNT becomes 2. If there are no parameter variables, PARMCNT is zero.
&PARMSTR Returns the string of parameter values used when the command list is initiated.
&PARMSTR does not include the command list name. For example, if command list
RESC is initiated by entering RESC ACT,LU200, then &PARMSTR becomes ACT,LU200.
If there are no parameter variables, &PARMSTR is null. The maximum length of the
string returned by &PARMSTR is 255 characters.
&RETCODE Returns the return code set by either the most recent command procedure or the most
recently activated or nested command list.
&RETCODE is initialized to zero. &RETCODE is set by a command procedure or

nested command list. When you write a command list that is called by another
command list, you can set a return code on the &EXIT statement in the nested
command list. You can use &RETCODE to test this return code in the calling
command list. See “&EXIT Control Statement” on page 125.
On the &EXIT statement, you can set the return code to 0, −1, or a positive integer.
The NetView program can set the return code to 0, −1, −2, −3 or −5. You cannot code
−2 or −3 on the &EXIT statement, but you can test for them. All other negative return
codes are reserved.
The possible values and meanings of &RETCODE are as follows:

n A positive integer; you define the meaning. If &CONTROL ERR is in effect,
the command is echoed on the panel.
0 No error.
–1 An error is found. This command list and all nested command lists end.
Message DSI197I is issued for this command list.
–2 A command in the command list is not correct. The message DSI209I is
displayed with the incorrect command. The command is ignored, and the
command list continues.
–3 A command in the command list is not authorized for this operator. The
incorrect command list statement is displayed along with message DSI210I.
The command is ignored, and the command list continues.
–5 A command list is stopped as the result of a RESET or other failure.
Note: &RETCODE is similar to the REXX-provided RC variable.
Cross-Domain Information Functions

Table 5. Cross-Domain Information Functions
NVCNT() Returns the number of NetView domains with which the operator can establish a
cross-domain session.
&NCCFCNT
Cross Domain and Global Variable
Table 5. Cross-Domain Information Functions (continued)

NVID(n) Returns the NetView domain identifier of a domain with which you can establish a
cross-domain session. The domains with which you can establish cross-domain
&NCCFID n sessions are defined by the DOMAINS statement of your operator profile.
| However, if your profile specifies AUTH CTL=GLOBAL, you can establish

| cross-domain sessions with the domains specified by the RRD statement in
| CNMSTYLE or its included members. If neither DOMAINS nor CTL=GLOBAL is
| specified in your operator profile, you receive an error message when using this
| function.
For more information about the DOMAINS and RRD statements, refer to the IBM
The value of n is either a number or a variable with a numeric value. The maximum
value of n is the value of NVCNT.
Notes:
1. If you specify a value that is not valid in n for:
v NVID, a null value is returned
v &NCCFID, an error message is returned
2. To obtain the local domain identifier, use the APPLID function. APPLID returns the
local domain ID appended with a 3-character alphanumeric value assigned by the
NetView program.
NVSTAT(name) Indicates whether you have an active session with a domain. The value of name is the
domain identifier of the domain you are querying. If you have an active session with
&NCCFSTAT name the domain, NVSTAT(name) or &NCCFSTAT return a value of ACT. If you do not have
an active session with the domain, INACT is returned.
Note: If you specify no name or a name that is not valid for:
v NVSTAT, a null is returned.
v &NCCFSTAT, an error message is returned.
Data Set Information Functions

Table 6. Data Set Information Functions
FNDMBR Tries to find the specified member in the files identified by the DD name. The files
(DD_name,member_name) must already be allocated by NetView when FNDMBR is processed. The allocated files
must be a partitioned dataset (PDS). FNDMBR returns two determinant results and a
variety of indeterminate results that you can use to debug your REXX program.
The arguments of the FNDMBR function are defined as follows:

DD_name
Specifies the DD name by which the allocated PDS file is known to the
NetView program.
member_name
Specifies the name of the member of the allocated PDS file to be located.

Table 6. Data Set Information Functions (continued)

FNDMBR The possible results returned by the FNDMBR function are:
(DD_name,member_name) 0 Indicates that the specified member name was found.
(continued) 4 Indicates that the specified member name was not found.
100 Indicates that a system error was encountered while trying to process this
request.
F cccccccc rrrrrrrr
where:
F Indicates that the MVS FIND macro failed.
cccccccc Is the FIND macro return code.
rrrrrrrr Is the FIND macro reason code.
O cccccccc rrrrrrrr
where:
O Indicates that the MVS OPEN macro failed.
cccccccc Is the OPEN macro system ABEND code or zero.
rrrrrrrr Is the OPEN macro return code. If cccccccc is not zero, this is the
same as the return code value in the IEC1nnI message associated
with the OPEN macro system abend code. If cccccccc is zero, this is
the return code from the OPEN macro. For example, a return code of
8 in this case might mean that the DD statement is missing or the file
is not allocated.
The following is an example of the FNDMBR function usage:

IF FNDMBR(’DSICLD’,’MYREXX’) = 0 THEN
This REXX statement is evaluated as true if MYREXX exists in DSICLD or as false if

MYREXX does not exist in DSICLD.
Notes:
1. Refer to the MVS/DFP™ library for the OPEN macro return codes. Refer to the
MVS/ESA™ library for the OPEN macro system abend codes (X’n13’ abend codes)
and IEC1nnI message explanations.
2. If a REXX variable is used to hold the DD name or the member name for the
FNDMBR function, to help insure that the text substituted for the variable does not
exceed 8 characters, strip the leading and trailing blanks from the value before
calling the FNDMBR function.
3. If the NetView ALLOCATE command was used to allocate the dataset, be sure not
to use the FREE option on the ALLOCATE when using the FNDMBR function
together with another command (for example, EXECIO) to access the allocated file.
The FNDMBR function runs an MVS OPEN and CLOSE, which causes the
allocated file to be deallocated if the FREE option was coded on the allocate
command. This restriction does not apply to files allocated using the DD
statements in the NetView startup procedure.
4. The dataset can be allocated down to the member level. However, it is not
recommended because an IEC141I message is issued if the member is not found.
Global Variable Information Functions

Table 7. Global Variable Information Functions
CGLOBAL(name)
REXX
Returns the value of the named common global variable if it exists. If no common
global variable with the specified name exists, a null value is returned. If you do not
specify name, or if you specify more than one name, a syntax error occurs.
End of REXX
NetView Command List Language
The NetView command list language control statement &CGLOBAL is operationally

different than the NetView REXX function described here. See “Using &TGLOBAL and
&CGLOBAL” on page 142.
End of NetView Command List Language
TGLOBAL(name)
REXX
Returns the value of the named task global variable if it exists. If no task global
variable with the specified name exists, a null value is returned. If you do not specify
name or specify more than one name, a syntax error occurs.
End of REXX
The NetView command list language control statement &TGLOBAL is operationally

different than the NetView REXX function described here. See “Using &TGLOBAL and
&CGLOBAL” on page 142.
Message Processing Information Functions

Table 8 on page 49 lists functions and variables that, unless otherwise noted, are
available for use on messages generated by all operating system platforms
supported by the NetView program.
Table 9 on page 55 lists only those functions and variables that are available for use
solely for messages originating from MVS systems.
In all cases, the value of the NetView command list language control variable and
REXX function is null unless otherwise stated if no message processing information
is available.
Some of the functions and variables that are listed in this section contain
discussion of a current message. “Working with Messages” on page 14 contains
additional information about current message.

Message Processing
Message Processing Information for All Operating Systems

Table 8. Message Processing Information
ACTIONDL() Returns the reason for which the NetView program deleted the associated message.
Values are:
&ACTIONDL
(null) The message is not being deleted.
LOCAL The message was deleted by operator overstrike of the CONSOLE
DELETE stage.
NETVIEW The message was deleted using the NetView DOM NVDELID or
CURMSG options, or by the NetView program.
SMSGID The message was deleted by MVS DOM using SMSGID.
TOKEN The message was deleted by MVS DOM using TOKEN.
TCB The message was deleted by MVS DOM for task end.
ASID The message was deleted by MVS DOM for address end space.
INVALID The DSIIFR has a combination of control flag settings that are not
valid.
ACTIONMG() Returns ’1’ if the message is an action message. Returns ’0’ if otherwise.
&ACTIONMG
ATTNID() Returns the VSE attention identifier ID. A plus sign (+) indicates that a reply is
required for this message immediately. A minus sign (−) indicates that a reply is
&ATTNID required for this message.
This function has a value if the message is from a VSE system, but null for non-VSE
messages.
EVENT() The NetView event that satisfied the WAIT is determined by the value of the REXX
EVENT() function. The REXX command list can use the EVENT() function to set a
variable and take appropriate action based on the set value. The possible returned
values from EVENT() are as follows:
M The message for which the command list is waiting has arrived. The message
can be read using the MSGREAD instruction.
T The time period for which the command list was waiting has expired, and
processing is resumed.
G You entered the GO command, and processing is resumed.
E You did not code the WAIT or TRAP instructions correctly. For example, you
entered the operands in the incorrect order or issued a WAIT for messages
instruction without a matching TRAP instruction. The command list resumes
processing.
If you do not issue a WAIT instruction in a command list, the value of the EVENT()
function is replaced with a value of null.
HDRMTYPE() Specifies the 1-character NetView buffer type of the received message or MSU. Buffer
types are described in IBM Tivoli NetView for z/OS Programming: Assembler.
&HDRMTYPE
IFRAUGMT() Returns the Greenwich mean time when the automation internal function request
(AIFR) was created. IFRAUGMT is returned as an 8-byte hexadecimal value in store
&IFRAUGMT clock format.
Message Processing
Table 8. Message Processing Information (continued)

IFRAUIND() Returns two bytes of indicator bits as a series of 16 on (1) and off (0) EBCDIC
characters representing the bits in order. This data is mapped in DSIIFR. The bit
&IFRAUIND positions are:
1 MVS system information attached (WQE data).
5 Message from NetView PPT.
6 Message received cross-domain.
11 Message was PRI routed by ASSIGN command.
12 Message was SEC routed by ASSIGN command.
13 Message was COPY routed by ASSIGN command.
14 Message was routed to authorized receiver.
15 Message was from down-level domain (no AIFR received).
16 Message was unsolicited.
Notes:
1. Other bits can be tested, but have no recommended use. All the bits are defined in
the DSIIFR mapping control blocks. For more information, refer to IBM Tivoli
NetView for z/OS Programming: Assembler.
2. Messages with the unsolicited flag on are eligible for ASSIGN PRI and SEC
routing.
3. This field indicates the AIFR indicator fields IFRAUIND and IFRAUIN2.
4. When using extended consoles, only MVS system messages that are received by the
task with load module name CNMCSSIR are considered unsolicited messages.
5. For more information about solicited and unsolicited messages, refer to the IBM
Tivoli NetView for z/OS Automation Guide.
IFRAUIN3() Returns 1 byte of indicator bits as a series of eight on (1) and off (0) EBCDIC
characters representing the bits in order. This data is mapped in DSIIFR. The bit
&IFRAUIN3 positions and meanings are:
1-2 00 = Default priority
01 = Low priority
10 = High priority
11 = Test the receiver for priority
3 VM PMX
IFRAUI3X() Returns a 32-byte string of ’1’ and 0’ values corresponding to control flags in the
IFRAUI3X word of the DSIIFR. The first 8 bits are the same as IFRAUIN3, allowing all
&IFRAUI3X 32 bits to be accessed at once.
IFRAUSB2() Returns a 2-byte user field in DSIIFR as a string of 2 characters.
&IFRAUSB2 Notes:
1. This function is null if the field is all blanks or binary zeros in any combination.
2. IFRAUSB2 and IFRAUSRB refer to the same user field, but return the value in
different formats.
IFRAUSC2() Returns a 16-byte user field in DSIIFR as a series of 128 on (1) and off (0) EBCDIC
characters representing the bits in order.
&IFRAUSC2 Note: IFRAUSC2 and IFRAUSRC refer to the same user field, but return the value in
different formats.
IFRAUSDR() Returns the 1–8 character name of the originating NetView task.
&IFRAUSDR
IFRAUSRB() Returns a 2-byte user field in DSIIFR as a series of 16 on (1) and off (0) EBCDIC
characters representing the bits in order.
&IFRAUSRB Note: IFRAUSRB and IFRAUSB2 refer to the same user field, but return the value in
different formats.

Message Processing

IFRAUSRC() Returns a 16-byte user field in DSIIFR as a string of 16 characters.
&IFRAUSRC Notes:
1. This function is null if the field is all blanks or binary zeros in any combination.
2. IFRAUSRC and IFRAUSC2 refer to the same user field, but return the value in
different formats.
IFRAUTA1() Returns 6-bytes of indicator bits as a series of 48 on (1) and off (0) EBCDIC characters
representing the bits in order. IFRAUTA1 enables checking of control information. The
&IFRAUTA1 bit positions are:
1, 2, 25 HOLD action.
5, 6, 26 SYSLOG action.
7, 8, 27 NETLOG action.
9, 10, 28 HCYLOG action.
11, 12, 29 DISPLAY action.
13, 14, 30 BEEP action.
20 Message from MVS.
23 VSE format message.
24 Action message.
47 Automation vector extensions exist.
48 Presentation vectors exist in data buffers.
Notes:
1. Other bits can be tested but have no recommended use.
2. Refer to the description of DSIIFR fields IFRAUTA1 through IFRAUTA6 in IBM
Tivoli NetView for z/OS Programming: Assembler.
IFRAUWF1() Returns 4-byte MVS-specific WTO information as a series of 32 on (1) and off (0)
EBCDIC characters representing the bits in order. Specific bit positions with
&IFRAUWF1 recommended uses are:
6 Message is a WTOR.
7 Message is suppressed.
8 Broadcast to all.
9 Display JOBNAMES.
10 Display STATUS.
14 DISPLAY SESSION.
Note: Other bits can be tested but have no recommended use. MLWTO flags in this
area also have no recommended use. MLWTO indicators are moved into the data
buffers.
LINETYPE() Returns the multiline write-to-operator (MLWTO) line type or MSU data buffer type,
as follows:
&LINETYPE C Message control line.
L Message label line.
D Message data line.
DE Last message data line.
E The line is the last message line and contains no data.
H The line is the HIER data buffer type.
M The line is the MSU data buffer type.
blank The message is a single-line message.
null There is no message or MSU data buffer associated with this command list.
Message Processing

MSGID()
REXX
&MSGID
| Returns the message identifier of the current message (see “Working with Messages” on
| page 14 for a definition of current message.) This is the first token, where tokens are
| determined by blanks. A reply ID, if present, is ignored. If a reply ID is sent with the
| message, it is not used as the first token. For a multiline write-to-operator (MLWTO)
| message, MSGID uses the first token of the first line of the message. When an MSU
| buffer is being processed, MSGID is equal to null ('').
Note: For messages received over the VM PROP/PMX interface, MSGID cannot be set
to the actual message identifier because of information added to the front of the
message.
End of REXX
The difference from REXX is that &MSGID is used in NetView automation, with
&WAIT, and with the LINKPD command.
MSGITEM(n)
REXX
&MSGITEM
Returns an item from the current message (“Working with Messages” on page 14
contains additional information about current message.) The first blank-delimited string
after a reply id (if there is one) is considered the message ID, as well as item 0. After
the message ID, parsing for items 1 through MSGCNT() is performed as follows:
v Strings can be delimited by either blanks or commas.
v A string beginning with a single quote preceded by a blank or comma, and ending
with a single quote followed by a blank or comma, is considered a quoted string,
and is treated as a single item, which does not include the surrounding quote.
v Every other delimited string that is not in a quoted string is treated as a single item.
v Delimiters that are not within quoted strings are not part of any item.
MSGITEM can return strings longer than 255.
End of REXX

Message Processing

MSGORIGN()
REXX
&MSGORIGIN
Returns the domain where the last message read by MSGREAD originated.
MSGORIGN() is used for NetView automation, with MSGREAD, and with the
LINKPD command.
Refer to the NetView online help for more information about using functions with
MSGREAD.
End of REXX
Specifies the domain where the message originated. &MSGORIGIN is used in NetView
automation, with &WAIT, and with the LINKPD command.
See Chapter 5, “Automation Resource Management,” on page 85 for more information

about NetView automation.
See “Control and Parameter Variables Used with &WAIT” on page 133 for more
information about using control variables with &WAIT.
See “LINKPD Results” on page 151 for more information about the LINKPD
command.

Note: The NetView command list language and REXX versions of this command are
spelled slightly differently; be sure to use the correct spelling when writing your
command list.
MSGSTR()
REXX
&MSGSTR
| Returns the message text of the current message (see “Working with Messages” on
| page 14 for information about current message). MSGSTR() does not include the
message identifier—the token used by the MSGID() function. For a multiline
write-to-operator (MLWTO) message, MSGSTR() becomes the message text of the first
line of the message.
End of REXX
Is the message text of the message most recently received by NetView. &MSGSTR does
not include the message identifier (the token used by the &MSGID control variable).
&MSGSTR is used with &WAIT and with the LINKPD command.
command.
Message Processing

MSGTSTMP() Returns the message time stamp. The value of this field is the time when the NetView
message buffer was created. The field is a 6-character string in the form of hhmmss,
&MSGTSTMP where:
hh Hours
mm Minutes
ss Seconds
| MSGVAR(n) Note: The use of MSGVAR is supported for compatibility purposes. The use of
| MSGITEM is recommended because the MSGVAR(n) functions do not return data
| relevant to the current message as described in “Working with Messages” on page 14.
| Use the MSGITEM(n) functions to return current message information.
Returns the text of a message. The NetView program changes the values of the
MSGVAR(1) through MSGVAR(31) functions to reflect the text of the message.
Note: MSGVAR(1) through MSGVAR(31) are equivalent to the NetView command list
language variables &1–&31.
Each MSGVAR(n) function is set to a token of the last message read by MSGREAD.
MSGVAR(1) is set to the token following the message identifier—the token used by the
MSGID() function. MSGVAR(2) is set to the next token to the right of MSGVAR(1), and
so on, up to a maximum of 31 variables. MSGVAR(n) is used for NetView automation,
with MSGREAD, and with the LINKPD command.
Refer to the NetView online help for more information about using functions with
MSGREAD.
command.
The MSGVAR(n) functions can be given values when a command list is called in the
same way as are the &1–&31 NetView command list language parameter variables.
MVSRTAIN() In the automation table, a 3-bit field describing MVS retain characteristics of the
message.
&MVSRTAIN Note: The 3 flags correspond to 3 flags defined in the MVS WQE control block when
NetView is using the SSI interface, and corresponds to 3 similar flags in the MDB
when running in Extended Console Mode. The exact meaning and use of the flags is a
property of the operating system.
&MVSRTAIN in NetView command list language is a 3-bit field describing MVS retain
characteristics of the message.
NVDELID() Returns the 24-character NetView deletion identifier for a message. You can remove
the message from the held queue for all tasks in the NetView program using the
&NVDELID NetView DOM NVDELID command. This is the NetView equivalent of the MVS DOM
function, but is used for messages that are not MVS WTOs or WTORs.
REPLYID() Returns the reply identifier for WTORs. This field has a maximum length of 8
characters.
&REPLYID
For messages from VSE systems, the REPLYID is the last three characters of the
6-character message prefix. The three returned characters are the message reply ID
only if the sending system uses those characters to designate a reply ID for a message.
SESSID() Returns the 1–8 character ID of the TAF (terminal access facility) session that sent the
message.
&SESSID
See Chapter 5, “Automation Resource Management,” on page 85 for more information
about NetView automation.
Note: If TAF session is started with a SESSID equal to the domain ID, SESSID is set
| unpredictably and might give unpredictable results. If the current message originated
| from a PPI receiver pipe stage, SESSID shows the SAF ID.

Message Processing
MVS-Specific Message Processing Information

This section contains descriptions of message information functions that are
important for NetView message automation. This information is generated by MVS
systems, but can be seen as cross-domain data in VM and VSE systems as well.
You can also generate user messages with this data as long as the information is
consistent with the MVS definitions. You can find more information about these
functions in the MVS/ESA library.
Some of these message information functions and control variables return valid
meaningful values only if the message currently being processed was originally a
message data block (MDB). Where applicable, this is noted in Table 9.
Table 9. MVS-Specific Message Processing Information
AREAID() Returns a 1-letter (A-Z) identifier for the area on the multiple console support console
panel that displays the message.
&AREAID
AUTOTOKE() Returns the 1–8 character name of the MVS message processing facility (MPF)
automation token.
&AUTOTOKE Note: If you’ve specified AUTO(YES) or AUTO(NO) in the MPF table, the values YES and
NO are not automation tokens.
CART() Returns the 8-byte MVS command and response token (CART). The CART might
contain non-displayable characters.
&CART
Notes:
1. This function has a value only if the message currently being processed was
originally a message data block (MDB).
2. CART is available on systems running MVS 4.1 or a later release.
DESC() Returns the MVS DESCriptor codes as a series of 16 on (1) and off (0) EBCDIC
characters representing the bits in order. Refer to the MVS library for information
&DESC about code values.
JOBNAME() Returns the 1–8 character MVS job name identifier. Because JOBNAME is the name of
the job that originated the message, it might not always be the same as the name of
&JOBNAME the job to which the message is referring. For example, the job names might be
different when MVS issues a message about the NetView job. Also, JOBNAME can
contain the name of an initiator (instead of the actual job name) when a job is started
or stopped. If the message is issued during startup or stopping, extract the job name
from the message text rather than using the JOBNAME function.
Note: The same information is available using MSGCOJBN; refer to the information
about MSGCOJBN on page 57.
JOBNUM() Returns the 8-character MVS job number identifier.
Note: The MVS job identifier might contain embedded blanks.
&JOBNUM
KEY() Returns the 8-character retrieval key associated with the message.
Note: This function has a value only if the message currently being processed was
&KEY originally an MDB.
Message Processing
Table 9. MVS-Specific Message Processing Information (continued)

MCSFLAG() Returns the system message flags in a series of eight on (1) and off (0) EBCDIC
characters representing the bits in order. The bit positions and their meanings are:
&MCSFLAG 1 Send message conditionally to console SYSCONID.
2 Send message unconditionally to console SYSCONID.
3 RESP.
4 REPLY.
5 BRDCST.
6 HRDCPY only.
7 NOTIME.
8 NOCPY.
Notes:
1. This function does not return the same mapping of multiple console support flags
as the automation table compare item.
2. Setting MCSFLAG=’00000000’ is valid. It overrides MCSFLAG set by an incoming
WTO.
MSGASID() Returns the MVS system address space identifier from which the message was issued.
The value of MSGASID is a 1–5 digit decimal number.
&MSGASID Note: This value is null for messages that do not come from an MVS address space.
MSGAUTH() Returns the 2-character value indicating whether the message was issued from an
authorized program.
&MSGAUTH 00 WTO message is not from MVS.
10 WTO is from an unauthorized program.
11 WTO is from an authorized program.
MSGCATTR() Returns the 16-bit MVS message attribute flags as a series of on (1) and off (0) EBCDIC
characters representing the bits in order. Bit positions and their meaning are:
&MSGCATTR 1 Message is suppressed.
2 Message is a command response.
3 Message issued by authorized program.
4 Message is to be retained by Automation Message Retention Facility (AMRF).
Notes:
originally an MDB.
2. Other bits can be tested but have no recommended use.
MSGCMISC() Returns the 8-bit MVS miscellaneous routing flags as a series of on (1) and off (0)
EBCDIC characters representing the bits in order. Bit positions and their meaning are:
&MSGCMISC 1 Display UD (undeliverable) messages.
2 Display only UD messages.
3 Queue by ID only.
4 Indicates whether the message has been marked in the message processing
facility (MPF) table as eligible for NetView automation.
Notes:
originally an MDB.
2. Other bits can be tested, but have no recommended use.

Message Processing

MSGCMLVL() Returns the 16-bit MVS message level flags as a series of on (1) and off (0) EBCDIC
&MSGCMLVL 1 WTOR
2 Immediate action
3 Critical eventual action
4 Eventual action
5 Informational
6 Broadcast
Notes:
originally an MDB.
MSGCMSGT() Returns the 16-bit MVS message type flags as a series of on (1) and off (0) EBCDIC
&MSGCMSGT 1 Display job names
2 Display status
3 Monitor active
6 Monitor SESS
Notes:
originally an MDB.
MSGCNT()
REXX
&MSGCNT
| Returns the number of items in the message string of the current message (see
| “Working with Messages” on page 14 for information about current message).
End of REXX
Returns the number of words in a message string.
MSGCOJBN() Returns the 1–8 character originating job name. (The same information is available
using JOBNAME, described on page 55.)
&MSGCOJBN Note: This function has a value only if the message currently being processed was
originally a message data block (MDB).
MSGCPROD() Returns the 16-character MVS product level. The characters are defined as follows:
v The first 4 characters represent an MVS control point object version level.
&MSGCPROD v The next 4 characters represent the control program name (MVS).
v The last 8 characters represent the function modification identifier (FMID) of the
originating system.
originally an MDB.
Message Processing

MSGCSPLX() Returns the 1–8 character name of the MVS SYSPLEX where the received message
originated. Available when running under MVS/ESA Version 4 Release 3 or above.
&MSGCSPLX Note: This function returns a value only if the message currently being processed was
received from an MVS SYSPLEX, and the message was originally a message data block
(MDB).
MSGCSYID() Returns the 1–3 digit decimal number system identification for DOM.
&MSGCSYID originally an MDB.
MSGDOMFL() Returns the 8-bit MVS DOM flags as a series of on (1) and off (0) EBCDIC characters
representing the bits in order. Bit positions and their meaning are:
&MSGDOMFL 1 DOM by message ID
2 DOM by system ID
3 DOM by ASID
4 DOM by job step TCB
5 DOM by token
originally an MDB.
MSGGBGPA() Returns the 4-byte hexadecimal background presentation attributes. Bytes and their
descriptions are:
&MSGGBGPA 1 Background control field
2 Background color field
3 Background highlighting field
4 Background intensity field.
Use one of the following forms to check for hexadecimal values:
REXX
IF MSGGBGPA() = ’12345678’X THEN ...

End of REXX
&IF &MSGGBGPA = X’12345678’ &THEN ...

originally an MDB.
MSGGDATE() Returns the message date in a 7-character format of yyyyddd, where yyyy is the year
and ddd indicates a calendar day.
&MSGGDATE
Notes:
1. This is not necessarily the current date. It might be the date with which MVS
associates the message as having been issued.
originally an MDB.

Message Processing

MSGGFGPA() Returns the 4-byte hexadecimal foreground presentation attributes. Bytes and their
meaning are:
&MSGGFGPA 1 Foreground control field
2 Foreground color field
3 Foreground highlighting field
4 Foreground intensity field
You can use one of the following forms to check for hexadecimal values:
REXX
IF MSGGFGPA() = ’12345678’X THEN ...
End of REXX
&IF &MSGGFGPA = X’12345678’ &THEN ...

originally an MDB.
MSGGMFLG() Returns the 16-bit MVS general message flags. Bit positions and their meaning are:
1 DOM (delete operator message)
&MSGGMFLG Note: This function has a value only if the message currently being processed was
originally an MDB.
MSGGMID() Returns the 4-character hexadecimal value MVS message identifier field.
&MSGGMID Notes:
originally an MDB.
2. MSGGMID represents the same information as SMSGID, except that SMSGID
returns a decimal value instead of a hexadecimal value.
MSGGSEQ() Returns the 1- to 8-character numerical decimal sequence number. This function
represents the last three bytes of MSGGMID.
&MSGGSEQ Note: This function has a value only if the message currently being processed was
originally an MDB.
MSGGSYID() Returns the 1- to 3-character numerical decimal system identification. This is the first
byte of MSGGMID.
&MSGGSYID Note: This function has a value only if the message currently being processed was
originally an MDB.
MSGGTIME() Returns an 11-character (including periods) time in the form hh.mm.ss.th, where hh is
the hours, mm is the minutes, ss is the seconds, and th is tenths and hundredths of
&MSGGTIME seconds.
originally an MDB.
Message Processing

MSGSRCNM() Returns the 1- to 17-character source object name. This source name is an identifier
from the source object that was provided by either the DSIMMDBS or CNMPMDB
&MSGSRCNM application programming interface (API) call.
For more information about DSIMMDBS, refer to IBM Tivoli NetView for
z/OS Programming: Assembler. For more information about CNMPMDB, refer to IBM
Tivoli NetView for z/OS Programming: PL/I and C.
The source name is selected from the source object by the following rules:
v The first nickname, if any
v The first network identifier concatenated to a network addressable unit (NAU)
name, with a period (.) between, if both exist in sequence
v The first NAU name, if it exists
v The string “N/A” if none of the other names in this list are specified in the source
object
v Null, if there is no source object
For more information about how the source object is defined, refer to the DSIAIFRO
mapping in IBM Tivoli NetView for z/OS Programming: Assembler.
originally an MDB with an associated source object.
MSGTOKEN() Returns a 1–10 digit decimal number that indicates the token associated with the
message.
&MSGTOKEN
Notes:
originally an MDB.
2. You can use a TOKEN value to group WTOs by setting MSGTOKEN prior to
issuing the WTO command. Subsequently, these messages can be deleted using a
single DOM command by specifying the token value in MSGTOKEN.
MSGTYP() Returns the system message type as a series of three on (1) and off (0) EBCDIC
characters representing the bits in order. An on character (1) in one of the positions
&MSGTYP corresponds to the following:
1 SESS — Corresponds to IFRAUWF1(14)
2 JOBNAMES — Corresponds to IFRAUWF1(9)
3 STATUS — Corresponds to IFRAUWF1(10)
PRTY() Returns the priority of the message as set by the originator. This field is a 1–5 digit
decimal number. The NetView program does not use this field when processing the
&PRTY message.
originally an MDB.

Message Processing

ROUTCDE() Returns the MVS routing code or codes assigned to the message. The value of the field
is a series of on (1) and off (0) EBCDIC characters representing the bits in order. The
&ROUTCDE maximum number of ROUTCDEs assigned to a message is 128.
Notes:
1. After the first 16 bits, the number of characters returned in ROUTCDE is the lowest
multiple of 8 that contains one or more on (1) characters. Therefore, you should
compare against a specific substring of ROUTCDE rather than against the entire
string.
For example, if only bit 17 is turned on, a string of 16 zeros, a 1, and 7 more zeros
are returned (000000000000000010000000). One method to test for bit 17 being on is
shown in the REXX example in Figure 9 on page 61.
The functionally equivalent code written in NetView command list language is
shown in Figure 10 on page 61.
2. Another method to check for a specific bit is to use the REXX environment’s POS
(position) function, as shown in Figure 11 on page 62.
3. For details on using the REXX POS function, refer to the REXX library.
SMSGID() Returns a 1–10 character decimal number that identifies a particular instance of a
message. This function can be used by the DOM command to identify action messages
&SMSGID to be removed from the display. Refer to the NetView online help for more
information about DOM.
This field contains the same information as MSGGMID, except that SMSGID is
returned as a decimal number and MSGGMID is returned as a hexadecimal value.
| SYSCONID() Returns the MVS system console name associated with the message. System console
| names are 2–8 characters in length.
&SYSCONID
SYSID() Returns the 1–8 character identifier of the MVS system from which a message arrived.
&SYSID
WTOREPLY Returns an operator reply to a WTOR.
&WTOREPLY REXX
The REXX version is not a function. It is a local variable and therefore does not have
parentheses on the end.
End of REXX
ROUTCDE Examples
/* STANDARD COMPARE */
IF ROUTCDE() = ’000000000000000010000000’
THEN SAY ’ROUTCDE BIT 17 IS SET.’
Figure 9. REXX Example to Test for Bit 17
&IF &ROUTCDE = 000000000000000010000000 &THEN

&WRITE ROUTCDE BIT 17 IS SET
Figure 10. NetView Command List Language Example to Test for Bit 17
MSU Information
/* POS COMPARE (Using the REXX environment function) */

BIT2CHK = 17
IF POS(’1’,ROUTCDE(),BIT2CHK) = BIT2CHK
THEN SAY ’ROUTCDE BIT 17 IS SET’
Figure 11. Using the REXX POS Function to Test for Bit 17
REXX Management Services Unit Information Functions

Table 10 on page 63 lists REXX functions for management services unit (MSU)
processing. MSUs include:
v Control point management services units (CP_MSU)
v Multiple domain support message units (MDS_MU)
v Network management vector transports (NMVT)
v Record maintenance statistics (RECMS)
v Record formatted maintenance statistics (RECFMS)
For more information about MSUs, refer to the IBM Tivoli NetView for
z/OS Automation Guide.
The following terms are used in Table 10 on page 63:

Generic MSU
All MSUs that contain subvector 92. Generic MSUs include:
v Alerts that contain subvector 92
v Resolutions, which always contain subvector 92
Statistics-only RECMS
Some RECMS records contain only statistical data. The RECMS records that
contain only statistical data are those with recording mode (byte 8, 1-offset,
into the RECMS) X'81', X'86', and X'87' (for X'87' that represent temporary
errors, not permanent errors).
Statistics-only RECFMS
Some RECFMS records contain only statistical data. The RECFMS records
that contain only statistical data are those with RECFMS types (byte 8,
1-offset, into the RECFMS) 1, 4, and 5.

MSU Information
Table 10. Management Services Units (MSU) Information Functions

Function Description
HIER (n) Provides user access to the NetView hardware monitor hierarchy data associated with
an MSU. The n specifies the index number (1–5) of a specific name/type pair.
Notes:
1. HIER() (without the n) returns a resource hierarchy slightly different than that
found in BNJ146I messages. The following are name/type pairs:
aaaaaaaa1111bbbbbbbb2222....eeeeeeee5555
The letters represent the resource name and numbers represent the resource type.
The hardware monitor defines from one to five name/type pairs. Each name is
eight characters long and each type is four characters. The names and types are
padded with blanks if necessary.
2. HIER (n) returns the name/type pair aaaaaaaa1111 that corresponds to n. If there is
no name/type pair that corresponds to n, then a null value is returned.
3. HIER(n) returns null under the following conditions:
v If the command list is not run by the automation table
v If the automation table was not driven by an MSU
v If the MSU does not have a hardware monitor resource hierarchy
4. Use the HMSECREC function with HIER to determine the resource name of the
hierarchy level where secondary recording is performed. For more information, see
the description of HMSECREC on page 69.
5. If a complex link exists in a resource hierarchy, there might be resource levels that
do not appear in the information returned by HIER(). You must use a system
schematic to determine the complete hierarchy configuration when a complex link
is present. Use the HMCPLINK function to check whether a complex link exists.
See Table 10 on page 63 for more information about the HMCPLINK function.
6. For information about the NetView built-in function &HIER, see “&HIER” on page
114.
HMASPRID() Returns a 1–9 character alert-sender product ID. This value is identical to the prodid
value described for the SRFILTER (SRF) command. The ID can be one of the following:
v 1–4 character hardware product ID
v 1–9 character software product ID
Trailing blanks are removed.
HMASPRID returns null if:

v An MSU is not a generic record.
v An MSU is not submitted to automation by the hardware monitor.
The maximum length is 9 characters.
HMASPRID applies to all MSUs submitted to automation by the hardware monitor.
See the examples in “HMASPRID” on page 71.
MSU Information
Table 10. Management Services Units (MSU) Information Functions (continued)

HMBLKACT() Returns a 5-character value consisting of a 3-character block ID and a 2-character
action code. This value is identical to the code value described for the SRFILTER (SRF)
command.
HMBLKACT returns null if an MSU is:

v A generic alert (X'0000')
v A resolution (X'0002')
v A PD statistic (X'0025')
v A link configuration data (X'1332')
v A statistics-only RECMS
v A statistics-only RECFMS
v Not submitted to the automation table by the hardware monitor
Otherwise, a value is returned.
Examples of MSUs that HMBLKACT returns a value for include nongeneric alerts
(X'0000'), RECMSs that are not statistics-only, and RECFMSs that are not statistics-only.
HMBLKACT applies to all MSUs submitted to automation by the hardware monitor.
See the examples in “HMBLKACT” on page 72.

HMCPLINK() Returns a 0, 1, or null to indicate whether a complex link exists, where:
1 A complex link exists.
If a complex link exists, there might be resource levels that do not appear in
the resource hierarchy returned by the HIER function. You must use a system
schematic to determine the complete hierarchy configuration when a complex
link is present. See the description of HIER on page 63 for more information.
Hardware monitor panels, such as Most Recent Events, indicate that a
complex link exists by placing an asterisk (*) in the pictorial resource
hierarchy at the top of the panel and displaying message BNJ1538I in the
message line near the bottom of the panel.
0 A complex link does not exist.
Null The MSU was not submitted to automation by the hardware monitor.
The maximum length is 1 character.
HMCPLINK applies to all MSUs submitted to automation by the hardware monitor.
See the examples in “HMCPLINK” on page 72.

MSU Information

HMEPNAU() HMEPNAU returns the NAU name of the entry point node where the MSU originated
for alerts forwarded using the NV-UNIQ/LUC alert forwarding protocol.
HMEPNAU returns the local NAU (domain) name for local MSUs.
For alerts forwarded using the SNA-MDS/LU 6.2 alert forwarding protocol,
HMEPNAU returns the NAU name of the entry point node that contains the MS
application that first forwarded the alert to the ALERT_NETOP application.
HMEPNAU adds an asterisk (*) to the beginning of the NAU name to indicate that the
name returned might not be the entry point node name. For example, if the node
name is NETV01 and HMEPNAU cannot determine if the node is an intermediate
node or the entry point node, it returns *NETV01.
Note: Refer to the IBM Tivoli NetView for z/OS Automation Guide for more information.
HMEPNAU applies only to MSUs submitted to automation by the hardware monitor.

HMEPNAU returns null for all other MSUs.
See the example in “HMEPNAU, HMEPNET, and HMFWDSNA” on page 72.

HMEPNET() HMEPNET returns the NETID name of the entry point where the MSU originated. For
alerts forwarded using the SNA-MDS/LU 6.2 alert forwarding protocol, HMEPNET
returns the NETID name of the entry point node that contains the MS application that
first forwarded the alert to the ALERT_NETOP application. HMEPNET adds an
asterisk (*) to the beginning of the NETID name to indicate that the name returned
might not be the entry point node name.
HMEPNET returns the local NETID name for local MSUs.
If the hardware monitor cannot determine the NETID name of the entry point,
HMEPNET returns an asterisk (*).
HMEPNET returns an asterisk (*), indicating that the NETID name cannot be
determined by the hardware monitor, for all MSUs forwarded by the NV-UNIQ/LUC
alert forwarding protocol.
Note: Refer to the IBM Tivoli NetView for z/OS Automation Guide for more information.
HMEPNET applies only to MSUs submitted to automation by the hardware monitor.

HMEPNET returns null for all other MSUs.
MSU Information

HMEPNETV() Returns a 0, 1, or null to indicate whether the entry point where the MSU originated
was a remote node NetView program. This function applies only to MSUs forwarded
using the SNA-MDS/LU 6.2 alert forwarding protocol.
1 The entry point was a NetView program.
0 The entry point was not a NetView program.
null The MSU was not forwarded using the SNA-MDS/LU 6.2 alert forwarding
protocol.
Notes:
1. Refer to the IBM Tivoli NetView for z/OS Automation Guide for more information
about forwarding mechanisms.
2. The maximum length is 1 character.
3. HMEPNETV applies only to MSUs submitted to automation by the hardware
monitor. HMEPNETV returns null for all other MSUs.
4. See the example in “HMEPNETV” on page 72.
HMEVTYPE() Returns the event type of an MSU. Any trailing blanks in the event type are removed.
The event types include:
AVAL BYPS CUST DLRC HMV HELD IMPD IMR
INST INTV NTFY PAFF PERF PERM PROC REDL
RSLV RSNT SCUR SNA TEMP USER UNKN
For a complete description of all event types, refer to the NetView online help
HMEVTYPE returns null if an MSU is:

v Not submitted to automation by the hardware monitor
HMEVTYPE applies to all MSUs submitted to automation by the hardware monitor.
See the examples in “HMEVTYPE” on page 73.

MSU Information

HMFWDED() Returns a 0, 1, or null to indicate whether an MSU was forwarded from another
NetView node, where:
1 An MSU was forwarded from another NetView program through the
NV-UNIQ/LUC alert forwarding protocol.
0 An MSU was not forwarded from another NetView program, or was
forwarded using the SNA-MDS/LU 6.2 alert forwarding protocol. Examples
of when a 0 is returned include:
v Local MSUs received over the CNM interface
v Local MSUs received from the operating system
v MSUs received over the PPI
v MSUs received using the SNA-MDS/LU 6.2 alert forwarding protocol
Null The MSU was not submitted to automation by the hardware monitor
Notes:
1. RECMS and RECFMS records forwarded from an entry point NetView program to
a focal point NetView program by the LUC forwarding method are not submitted
to automation by the receiving focal point’s hardware monitor. These RECMS and
RECFMS records can be automated only by the sending entry point NetView
program.
2. Refer to the IBM Tivoli NetView for z/OS Automation Guide for more information
3. The maximum length is 1 character.
4. HMFWDED applies to all MSUs submitted to automation by the hardware
monitor.
5. See the examples in “HMFWDED” on page 73.
HMFWDSNA() Returns a 0 or 1 to indicate if an MSU was forwarded from a remote entry point node
using the SNA-MDS/LU 6.2 alert forwarding protocol.
1 An MSU was forwarded from a remote entry point node using SNA-MDS/LU
6.2 alert forwarding protocol.
0 An MSU was not forwarded from a remote entry point node using
SNA-MDS/LU 6.2 alert forwarding protocol.
null An MSU was not submitted to automation by the hardware monitor.
Note: Refer to the IBM Tivoli NetView for z/OS Automation Guide for more information
HMFWDSNA applies only to MSUs submitted to automation by the hardware

monitor. HMFWDSNA returns null for all other MSUs.
MSU Information

HMGENCAU() Returns the 1-character hexadecimal general cause code of an MSU. The general cause
code indicates both the general classification and exception condition that caused the
MSU to be created. For more details about general cause codes, refer to the
information about basic alert (X'91') alert MS subvectors in the SNA library.
HMGENCAU returns null if an MSU is:

v A link event (X'0001')
Otherwise, a general cause code is returned.
Examples of MSUs that HMGENCAU returns a value for include nongeneric alerts
(X'0000'), RECMS records that are not statistics-only, and RECFMS records that are not
statistics-only.
The maximum length is 1 hexadecimal character.
HMGENCAU applies to all MSUs submitted to automation by the hardware monitor.
See the examples in “HMGENCAU” on page 73.

HMONMSU() Returns 0 or 1 to indicate whether an MSU was submitted to automation by the
hardware monitor, where:
1 Indicates that an MSU was submitted to automation by the hardware monitor.
0 Indicates that an MSU was not submitted to automation by the hardware
monitor (for example, it was submitted to automation by the generic receiver
MS application).
HMONMSU applies to all MSUs.
See the examples in “HMONMSU” on page 73.

MSU Information

HMORIGIN() Returns the name of the resource sending the MSU. Any trailing blanks are removed
from the value returned.
The resource name returned by HMORIGIN is the same name displayed on the
hardware monitor Alerts Dynamic, Alerts Static, and Alerts History panels when
ALT_ALERT ORIGIN is specified in BNJMBDST. Refer to the IBM Tivoli NetView for
z/OS Administration Reference for information about the statements used in BNJMBDST.
If a complex link does not exist in a resource hierarchy, the resource name returned
with HMORIGIN matches one of the resource names returned with the HIER function.
If a complex link does exist, the resource name might not be one of the names
returned with HIER. Use the HMCPLINK function to determine whether a complex
link exists. For more information, see the description of HMCPLINK, on page 64, and
the description of HIER, on page 63.
HMORGIN returns null if an MSU is not submitted to automation by the hardware

monitor.
HMORIGIN applies to all MSUs submitted to automation by the hardware monitor.
See the examples in “HMORIGIN” on page 74.

HMSECREC() Returns 0, 1, or null to indicate whether the hardware monitor performs secondary
recording for an MSU, where:
1 Secondary recording is performed for an MSU at the resource level returned
by the HIER function. See the description of HIER, on page 63, for more
information.
0 Secondary recording is not performed for an MSU. HMSECREC always
returns a 0 for PD statistics (X'0025') and frame relays (X'1332') because the
hardware monitor never performs secondary recording for these MSUs.
Null The MSU was not submitted to automation by the hardware monitor.
HMSECREC applies to all MSUs submitted to automation by the hardware monitor.
See the examples in “HMSECREC” on page 74.
MSU Information

HMSPECAU() Returns the 2-character hexadecimal specific component code of an MSU.
The specific component code indicates the generic type of component, subcomponent,
or logical resource that is most closely related to the exception condition that caused
the MSU to be created.For more details about specific component codes, refer to the
information about Basic Alert (X'91') Alert MS subvector in the SNA library. Note that
these codes are valid for RECMS and RECFMS records.
HMSPECAU returns null if an MSU is:

v A link event (X'0001')
Otherwise, a general cause code is returned.
Examples of MSUs that HMSPECAU returns a value for include nongeneric alerts
(X'0000'), RECMS records that are not statistics-only, and RECFMS records that are not
statistics-only.
The maximum length is 2 hexadecimal characters.
HMSPECAU applies to all MSUs submitted to automation by the hardware monitor.
See the examples in “HMSPECAU” on page 74.

MSU Information

HMUSRDAT() Returns 1 to 5 characters of user-specified data from subvector 33 of an MSU. Trailing
blanks are removed from the value returned. This data can be used with hardware
monitor filtering.
The hardware monitor translates any unprintable data in subvector 33 to underscores

(_) and translates lowercase characters to uppercase. The characters returned with
HMUSRDAT reflect any translation done by the hardware monitor and therefore might
not be the same characters in subvector 33. You can use HMUSRDAT to determine
whether the hardware monitor has translated any data in subvector 33 to underscores
or uppercase. Although translated data and subvector 33 data are often identical,
hardware monitor filtering is performed against the translated data, not against the
subvector 33 data.
You can use MSUSEG to retrieve untranslated user-specified data from subvector 33 in
an MSU.
For more information about subvector 33 data, see the UDAT option of the
GENALERT command and the U option of the SRFILTER command.
HMUSRDAT returns a null if an MSU:

v Does not contain subvector 33. Note that subvector 33 is never present in RECMS or
RECFMS records. According to the SNA architecture, only generic major vectors can
contain subvector 33. However, the hardware monitor accepts and processes
subvector 33 information in any of the major vectors submitted to automation.
v Is a frame relay (key X'1332').
v Is not submitted to automation by the hardware monitor.
HMUSRDAT applies to all MSUs submitted to automation by the hardware monitor.
See the examples in “HMUSRDAT” on page 74.

MSUSEG(operands) Provides the parsing capability needed to extract information from a management
services unit (MSU) or other similarly architected pieces of data. Use this function in a
command list that is called by the NetView automation table or an LU6.2 application.
For complete MSUSEG syntax and some examples of usage, see “MSUSEG Syntax and
Examples” on page 74.
For information about the built-in function &MSUSEG, see “&MSUSEG” on page 117.
| NPDABA(operands) Returns the associated hardware monitor probable-cause and error-description text.
| For complete NPDABA syntax and some examples of usage, see “Probable Cause
| Syntax and Examples” on page 76.
Hardware Monitor (HMxxxxxx) Examples

HMASPRID
/* Example A: The following example checks for a generic */
/* hardware monitor MSU. */
IF HMASPRID() ¬= ’’ THEN ....
Figure 12. HMASPRID Example A
MSU Information
/* Example B: The following example checks for a generic */

/* MSU from a 3745 device. */
IF HMASPRID() = ’3745’ THEN ....
Figure 13. HMASPRID Example B
HMBLKACT
/* Example A: The following example checks for a block id */
/* and action code that is not null. */
IF HMBLKACT() ¬= ’’ THEN ....
Figure 14. HMBLKACT Example A
/* Example B: The following example checks for a block id */

/* of ’FFD’ and action code of ’03’. */
IF HMBLKACT() = ’FFD03’ THEN ....
Figure 15. HMBLKACT Example B
/* Example C: The following example checks for a block id */

/* of ’FFD’. It does not check for a specific action code. */
IF SUBSTR(HMBLKACT(),1,3) = ’FFD’ THEN ....
Figure 16. HMBLKACT Example C
HMCPLINK
/* Example A: The following example checks for an MSU */
/* with a complex link. */
IF HMCPLINK() = 1 THEN ....
Figure 17. HMCPLINK Example A
/* Example B: The following example checks for an MSU */

/* that has no complex link. */
IF HMCPLINK() = 0 THEN ....
Figure 18. HMCPLINK Example B
HMEPNAU, HMEPNET, and HMFWDSNA

/*===================================================================*/
/* Example A: Was the MSU was forwarded from node NETA.CNM01 */
/* over LU 6.2? */
/*===================================================================*/
IF (HMFWDSNA() = ’1’) & , /* MSU forwarded over LU 6.2? */
(HMEPNET() = ’NETA’) & , /* From network NETA? */
(HMEPNAU() = ’CNM01’) THEN ... /* And nau CNM01? Then do ... */
Figure 19. HMEPNAU, HMEPNET, and HMFWDSNA Example
HMEPNETV
/*===================================================================*/
/* Example A: Was the MSU was forwarded from a remote node */
/* entry point NetView over LU 6.2? */
/*===================================================================*/
IF HMEPNETV() = ’1’ THEN ...
Figure 20. HMEPNETV Example

MSU Information
HMEVTYPE
/* Example A: The following example checks for hardware */
/* monitor MSUs with an event type of PERM. */
IF HMEVTYPE() = ’PERM’ THEN ....
Figure 21. HMEVTYPE Example A
/* Example B: The following example checks for hardware */

/* monitor MSUs that do not have an event type of null. */
IF HMEVTYPE() ¬= ’’ THEN ....
Figure 22. HMEVTYPE Example B
HMFWDED
/* Example A: The following example checks for hardware */
/* monitor MSUs forwarded from another NetView program */
/* using the NV-UNIQ/LUC.. */
IF HMFWDED() = 1 THEN ....
Figure 23. HMFWDED Example A
/* Example B: The following example checks for hardware */

/* monitor MSUs not forwarded from another NetView program */
/* using the NV-UNIQ/LUC.. */
IF HMFWDED() = 0 THEN ....
Figure 24. HMFWDED Example B
HMGENCAU
/* Example A: The following example checks for a general */
/* cause code that is not null. */
IF HMGENCAU() ¬= ’’ THEN ....
Figure 25. HMGENCAU Example A
/* Example B: The following example checks for a general */

/* cause code of ’01’X. */
IF HMGENCAU() = ’01’X THEN ....
Figure 26. HMGENCAU Example B
HMONMSU
Example A shows one way to check for MSUs that have been submitted by the
hardware monitor.
/* Example A */
IF
. HMONMSU() = 1 THEN ...
.
.
Figure 27. HMONMSU Example A
Example B shows one way to check for MSUs that have not been submitted by the
hardware monitor.
/* Example B */
IF
. HMONMSU() = 0 THEN ...
.
.
Figure 28. HMONMSU Example B
MSU Information
HMORIGIN
/* Example: The following example checks for hardware */
/* monitor MSUs sent from a resource named GENALERT. */
IF HMORIGIN() = ’GENALERT’ THEN ....
Figure 29. HMORIGIN Example
HMSECREC
/* Example: The following example checks for secondary */
/* recording on an MSU and displays the resource hierarchy. */
IF HMSECREC() = 1 THEN
DO
SAY ’Secondary recording is being done for an MSU at’
SAY ’resource level: ’ HIER()
SAY ’The name and type pair displayed last is most likely’
SAY ’involved with the error.’
END
Figure 30. HMSECREC Example
HMSPECAU
/* Example A: The following example checks for a specific */
/* component code that is not null. */
IF HMSPECAU() ¬= ’’ THEN ....
Figure 31. HMSPECAU Example A
/* Example B: The following example checks for a specific */

/* component code of ’0001’X. */
IF HMSPECAU() = ’0001’X THEN ....
Figure 32. HMSPECAU Example B
HMUSRDAT
/* Example: The following example checks for hardware */
/* monitor MSUs with user specified data of MYDAT in */
/* subvector 33. */
IF HMUSRDAT() = ’MYDAT’ THEN ....
Figure 33. HMUSRDAT Example
MSUSEG Syntax and Examples

Syntax
The MSUSEG(operands) syntax is:
MSUSEG
.
(1)
MSUSEG(' id ' )
H (occ) 1
1
,
byte ,length

MSU Information
where:
byte
Is the byte position into the lowest ID specified in id, counting from 1 in
decimal. Position 1 is the first length byte in the header of the lowest ID. The
header is composed of one or two length bytes followed by the 1- or 2-byte ID.
This entry is optional. The default is 1.
H Is inserted if the first ID is to be obtained from the next higher level
multiple-domain support message unit (MDS-MU) as opposed to the
NMVT/control point management services unit (CP-MSU) level. You can code
the H in uppercase or lowercase. You can place H inside or outside of the
quotes when quotes are coded.
id Is the 2- or 4-character representation of the 1- or 2-byte hexadecimal ID of
GDS, major vector (MV), subvector, subfield, or sub-subfield. The hexadecimal
characters (0–9, A–F, a–f) can be mixed case. The first ID is required; additional
IDs are optional.
length
Is the number of bytes in decimal to be returned from the lowest ID specified
in id and starting at the byte position. This entry is optional. The default is
equal to the remainder of the lowest id specified, and starting at the byte
position.
occ
Is the occurrence number, counting from one (1) in decimal. You can use an
asterisk (*) to specify the first occurrence found. This entry is optional at every
level. The default is 1.
The single quotation marks shown in the REXX syntax diagram are required
only when an occ is specified. If you do not explicitly code an occ, the
quotation marks are optional.
. The period establishes a hierarchy of IDs. Thus, the vector ID specified on the
right side of the period is contained within the vector specified on the left side.
Notes:
1. With MSUSEG(operands), as with other REXX function operands, if operands
are specified, they must be delimited by commas. Two successive commas
indicate an omitted operand.
2. If the location is not found, or if the command list containing the
MSUSEG(operands) was not run by an automation table statement due to an
MSU, or if the function was not driven by an MSU, then the value of the
MSUSEG(operands) is null.
3. If you do not specify a byte position, the data returned includes the 1- or 2-byte
length followed by the 1-or 2-byte ID of the lowest ID specified in id.
4. If the byte position is beyond the end of the location, a null value is returned.
5. If the specified length is longer than what remains at the location specified,
whatever remains at the location is returned.
6. Examples of using MSUSEG(operands) are shown in the figures in “MSUSEG
Syntax and Examples” on page 74.
7. For more information about the automation table, refer to the IBM Tivoli
NetView for z/OS Automation Guide. For more information about vector
definitions, refer to the SNA library. For more LU6.2 and MSU information,
refer to the IBM Tivoli NetView for z/OS Application Programmer’s Guide.
8. For information about using the built-in function &MSUSEG in NetView
command list language CLISTs, see “&MSUSEG” on page 117.
MSU Information
Examples
The following are examples of using the MSUSEG() function:
In Figure 34, the third byte of subvector A0 within the Alert major vector (0000)
starts with ’OPEN’. The Alert can be in any of the supported envelopes.
IF MSUSEG(’0000.A0’,3,4) = ’OPEN’ .....
Figure 34. MSUSEG() Example 1
In Figure 35, Alert subvector A0 has ’LINE’ followed by ’DOWN’ anywhere in it.
Literals can be in hex as well as EBCDIC.
INTERPRET ’PARSE VALUE "’MSUSEG(’0000.A0’)’" WITH ’LINE’X +4

’DOWN’’ Y +4 .’
IF X ¬= ’’ & Y ¬= ’’ .....
In Figure 36, Alert subvector A1 has bits '01X01X00XX11XXXX', including

unimportant bits, starting from the first bit of the fourth byte.
IF BITAND(MSUSEG(’0000.A1’,4,2),’DB30’X) = ’4830’X .....
Figure 37 shows an MDS-MU whose first 1212 (CP-MSU) contains a 1323, the first
of which contains any 1326s, the second of which contains 132Bs, the third of
which contains a subvector 01.
IF MSUSEG(’H1212.1323.1326(2).132B(3).01’) ¬= ’’ .....
| Probable Cause Syntax and Examples

| Syntax
| The NPDABA syntax is:
| NPDABA
| NPDABA('bbbaa')
|
| where:
| bbbaa
| The 5-character string that defines the pre-generic alert:
| v bbb is a hardware monitor block ID.
| The block ID is the code used to identify the IBM hardware or software
| associated with the record.
| v aa is an associated hardware monitor action-code.
| The action code is the specific alert ID within a block ID.
| Note: The NPDABA function returns the associated hardware monitor

| probable-cause and error-description text (maximum length of 48
| characters).

MSU Information
| Examples
| Table 11. NPDABA Examples
| Example Probable Cause
| NPDABA(’FFF03’) ’ADAPTER FEEDBK CHK:COMMUN CTRLR PGM/COMMUN CTRLR’
| The NPDA block ID is FFF and

| the associated action code is 03.
| NPDABA(’123456’) ’INCORRECT INPUT’
| The input is 6 characters, which The input is not valid (not a valid hexadecimal number
| is not a valid length. or not 5 characters in length).
| NPDABA(’12345’) ’NOT AVAILABLE’
| The input is 5 characters, but is The hardware monitor does not recognize this
| not a valid block ID and action combination of block ID (123) and action code (45).
| code.
|
|
Operator Information Functions
You can use the following operator information function in REXX command lists
or Data REXX files for the NetView program.
Table 12. Operator Information Functions
OPID() Returns the operator or task ID the same as OPID (’O’). OPID is a 1–8 character
identifier.
&OPID
OPID(’x’) Returns the operator or task ID as a 1–8 character identifier where x is one of the
following:
O Returns the owner’s identity. On a regular OST, it is the same as OPID(), but
on a VOST, it returns the operator ID of the owning OST.
R Returns the operator ID of a remote task controlling the distributed autotask.
If the task is not a distributed autotask, it returns a null.
S Returns the source ID of the operator that originated the command that is
running. Special values, other than the operator ID, might be returned as
follows:
Automation
The command originated in the automation table processing.
(null) The command originated at an optional task or otherwise in
assembler code that specified that the source be ignored.
Note: There is currently no case where the NetView program calls
REXX in this way. Customer-written code or code from other venders
might.
T Returns the target identity, the identity of the task on which the REXX
program is running.
Session Information Functions

You can use the following session information functions in REXX command lists
and Data REXX files for NetView.
Session Information
Table 13. Session Information Functions

APPLID() Returns the application program identifier for the task under which the command list
is running. APPLID is the NetView domain ID appended with a 3-character
&APPLID hexadecimal suffix assigned by the NetView program. For example, if your domain ID
is PARIS, APPLID might be PARIS001. The NetView program attempts to use an
APPLID that is both defined and available. If successful in this attempt, each APPLID
is unique. If no defined APPLID is available, an APPLID of notInit! is used until a
defined APPLID is available. In this case, the notInit! APPLID is not guaranteed to be
unique as multiple tasks might be in this situation.
ASID() Returns the current NetView address space identifier. The value of ASID is a 1–5 digit
decimal number.
&ASID
ATTENDED() Returns a single-character value of either 1 or 0. The values are defined as:
&ATTENDED 1 Indicates that the task is one of the following:

v An OST with a display
v An NNT with a corresponding OST
v An autotask with an associated MVS console assigned using the
AUTOTASK command
v A distributed autotask
0 Indicates that the task is one of the following:
v An autotask without an associated MVS console assigned using the
AUTOTASK command
v Another type of task, such as a DST or an OPT task
Usage Notes:
1. If the associated operator is an AUTOTASK, the presentation data is not eligible for
display unless the AUTOTASK is associated with an active MVS console.
2. ATTENDED can be used with DISTAUTO and AUTOTASK variables to further
determine the characteristics of the task. For example, if ATTENDED is 1,
DISTAUTO is 0, and AUTOTASK is 1, the task is an AUTOTASK with an
associated MVS console.
| AUTCONID() Returns the MVS console identifier associated with this autotask. This association was
| made using the AUTOTASK command with the CONSOLE keyword. The value of
| &AUTCONID AUTCONID is the console name of the MVS console where NetView commands can
| be entered to run under this autotask.
AUTOTASK() Returns a single-character value of either 1 or 0 indicating whether or not the task is
an autotask. Values are:
&AUTOTASK
1 An autotask
0 Not an autotask
CGI() Returns a single-character value of either 1 or 0. Values are:
1 The procedure was called by the NetView Web server.
0 The procedure was not called by the NetView Web server.
| CURCONID() Returns the MVS console identifier obtained by a NetView task. This console was
| obtained with the GETCONID command or by issuing an MVS command. The value
| &CURCONID of CURCONID is the console name of the MVS console that this task uses to enter
| MVS commands.
CURSYS() Returns the 1–8 character current system name.
&CURSYS

Session Information
Table 13. Session Information Functions (continued)

DISC() Returns a single-character value of either 1 or 0 that indicates whether the task is
disconnected. Values are as follows:
&DISC
1 Autotask is disconnected.
0 Autotask is not disconnected.
DISTAUTO() Returns a single-character value of either 1 or 0 that indicates whether a task is a
distributed autotask started with the RMTCMD command. Values are:
&DISTAUTO
1 A distributed autotask
0 Not a distributed autotask
Note: This corresponds to the value of TVBDAUT.
DOMAIN() Returns the 1- to 5-character name of the current NetView domain.
&DOMAIN
DOMAIN(’x’) Returns the 1- to 5-character name of a NetView domain, where x is the following:
R Returns the domain name of a remote task controlling the distributed
autotask. If the task is not a distributed autotask, it returns a null.
| ECVTPSEQ() Is the z/OS product sequence number found in the MVS IHAECVT data area. For
| example, if you are running on z/OS v1.6, ECVTPSEQ returns a value of 01010600.
ENVDATA(’x’) Returns a numeric value or character string, where x is one of the following:
C Returns the screen color count.
D Returns the screen depth (number of rows on the screen).
W Returns the screen width (number of columns on the screen).
G Returns a list of blank delimited entries representing the REXX, PL/I, and C
procedures in the calling sequence or procedure group that was active when
ENVDATA was called.
Each entry consists of two names separated by a slash (/), in the format
command/name. command is the command verb or synonym used to call the
procedure. name is one of the following:
v The module name if the procedure is PL/I or C.
v The member name in DSICLD if the procedure is REXX.
Multiple entries show the calling sequence in reverse order. The command the
operator entered is the last entry listed.
MVSLEVEL() Returns the version of MVS currently running. For example, if you are running
MVS/ESA 4.2.2, MVSLEVEL returns SP4.2.2.
&MVSLEVEL
NETID() Returns the VTAM network identifier. This field has a maximum length of 8
characters. If VTAM has never been active when the NetView program is active, the
&NETID value of NETID is null.
NETVIEW() Returns the version and release of the currently running NetView program. The value
of NETVIEW is a 4-character string in the form of NVvr, where:
&NETVIEW v Indicates the version number of the NetView program
r Indicates the release number of the NetView program
NETVIEW(’x’) Returns a text string, where x is as follows:
T Returns the text string containing the official NetView name.
Session Information

OPSYSTEM() Returns the type of operating system for which the NetView program was compiled.
OPSYSTEM can contain the following character values:
&OPSYSTEM MVS/ESA
MVS/XA™
VM/ESA®
VSE
PANEL() Returns a single-character value of either 1 or 0. Values are:
1 Panel commands can be issued.
0 Panel commands are not allowed.
PARTID() Returns the first two characters of the six-character prefix for VSE messages. The two
returned characters are the message partition ID only if the sending system uses those
&PARTID characters to designate a partition ID for a message.
STCKGMT() Returns the current Greenwich mean time in store-clock format. This field is returned
as an 8-byte hexadecimal value.
&STCKGMT
SUPPCHAR() Returns the suppression character for your installation. (The suppression character
prevents the NetView program from writing the command out to the terminal,
&SUPPCHAR hardcopy log, and network log.)
| SUPPCHAR is a single character that you define in CNMSTYLE %INCLUDE member

| CNMSTUSR or CxxSTGEN. The default suppression character that is defined in
| CNMSTYLE is the question mark (X'6F').
| If you do not define a suppression character in CNMSTYLE or its included members,

| SUPPCHAR defaults to X'3F'.
Note: The SUPPCHAR default character of X'3F' cannot be typed at the operator
console. Therefore, if you do not define a suppression character, the operator is
prevented from using one.
SYSPLEX() Returns the 1–8 character name of the MVS SYSPLEX where the command list is
running. Available for MVS/ESA Version 4 Release 2.2 or above.
&SYSPLEX Note: This function returns a value only if the command list is running on an MVS
SYSPLEX.
TASK() Returns the 3-character string indicating the type of task under which the command
list is running. Possible values are:
&TASK PPT Primary POI task
OST Operator station task
NNT NetView-to-NetView task
For Data REXX, in addition to PPT, OST, and NNT, any the following can be returned:
DST Data services task
HCT Hardcopy task
MNT Main task
OPT Optional task
UNK Unknown task
Note: This value indicates that an error has occurred. Contact IBM Software
Support for more information.
TASK enables the same command list to run under any of these tasks because the
command list can test for the task type and process accordingly. For example, there are
some restrictions for command lists running under the PPT. See “Primary POI Task
Restrictions” on page 12.

Session Information

TOWER(string) Returns either a binary value that indicates whether a tower or subtower is enabled, or
the name of the towers and subtowers that are enabled.
If a string does not end with an asterisk (*), a single-character of either 1 or 0 is

returned. Values are:
1 The tower or subtower is enabled.
0 The tower or subtower is not enabled.
For example, assume that the AON tower and the SNA subtower are enabled, but the
TCP subtower is not, SAY TOWER(AON.SNA) returns 1 and SAY TOWER(’aon.TCP’)
returns 0.
Strings that end with an asterisk (*) return the names of the towers and subtowers that
are enabled. Note that asterisks can be either used alone or used together with a tower
name to determine the subtowers that are enabled. For example, assume that the AON
tower and the SNA and TCP subtowers are enabled, SAY TOWER(’*’) would return AON
SNA TCP and SAY TOWER(’aon.*’) would return SNA TCP.
Notes:
1. Input strings are not case sensitive and mixed case strings can be returned.
2. Tower and subtower combinations must be concatenated with a period (.).
| 3. Towers and subtowers are enabled in CNMSTYLE and its included members. Refer
| to the IBM Tivoli NetView for z/OS Administration Reference for more information.
TYPE() Returns a 3-character string that indicates the level of the NetView program that is
installed. Possible values are:
ENT Enterprise option
SYS NetView System Services
VTAM() Returns the version and release of VTAM as a 4-character string in the form of either
VTvr or Vvrm, where:
&VTAM v Is the version number
r Is the release number
m Is the modification number
Note: The value of VTAM is null if the VTAM program is not active.
VTCOMPID() Returns the 14-character VTAM component identifier. The VTAM component
identifiers are:
&VTCOMPID MVS/ESA 5685-08501-xxx (for VTAM Version 3)
MVS/ESA 5695-11701-xxx (for VTAM Version 4)
MVS/XA 5665-28901-xxx
VSE/ESA 5666-36301-xxx
VM/SP 5664-28001-xxx
VM/9370 5684-05201-xxx
VM/ESA 5684-09501-xxx
where xxx is the release number.
Additional VTAM component identifiers might be added in future updates to VTAM.

Note: The value of VTCOMPID is null if VTAM is not active.
WEEKDAYN() Returns a numeric value in the range of 1 to 7 indicating the day of week (from
Monday through Sunday), as shown below:
&WEEKDAYN 1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday
7 Sunday
REXX Environment and Terminal Information
REXX Environment Information Functions

You can use the following REXX environment functions in REXX command lists
for the NetView program.
Refer to the IBM Tivoli NetView for z/OS Tuning Guide for the rationale on the use
of these functions.
Note: Refer to the DEFAULTS command and the OVERRIDE command in the
NetView online help for more information about the meaning of the
following REXX values. These functions return a null value for operating
systems other than MVS/XA, MVS/ESA, and VSE/ESA.
Table 14. REXX Environment Information Functions
RXDEFENV() Returns the default number of NetView REXX environments set by the REXXENV
parameter of the DEFAULTS command.
&RXDEFENV
RXDEFSTR() Returns the default NetView REXX environment initial storage size set by the
REXXSTOR parameter of the DEFAULTS command. This value can be -1 if REXXSTOR
&RXDEFSTR was set to the default or was never set.
RXNUMENV() Returns the current number of REXX environments initialized for this task. For
RXNUMENV(), this number is always at least 1, representing the REXX environment
&RXNUMENV currently running. For &RXNUMENV, this number can be zero (0).
RXOVRENV() Returns the override number of NetView REXX environments set by the REXXENV
parameter of the OVERRIDE command. If the number of REXX environments has not
&RXOVRENV been overridden or is set to the default value, a null value is returned.
RXOVRSTR() Returns the override NetView REXX environment initial storage size set by the
REXXSTOR parameter of the DEFAULTS command. If the REXX initial storage size has
&RXOVRSTR not been overridden or is set to the default value, a null value is returned.
Terminal Information Functions

You can use the following terminal information functions in command lists for
NetView.
Table 15. Terminal Information Functions
HCOPY() Returns the name of device defined as the hard-copy log printer started by the
operator. If there is no device defined as the hard-copy printer for this operator,
&HCOPY HCOPY is null.
LU() Returns the logical unit name for this operator terminal.
&LU
Time and Date Variables

You can use the following time and date control variables in the NetView
command list language:

Time and Date
Table 16. Date and Time Variables

&DATE Returns the current date in the form of mm/dd/yy, where mm is the month, dd is the
day, and yy is the year.
&TIME Returns the processor time in the format hh:mm, where hh is the hour and mm is the
minutes. The time is based on a 24-hour clock, so 3:00 p.m. is shown as 15:00.
Note: Because &TIME and &DATE are separate variables, you might need extra
coding to determine the correctly matched time and date. For example, if
you get &DATE first, midnight can occur before you get &TIME, so you
have the wrong date for the current time. If you get &TIME first, midnight
can occur before you get &DATE, so you would have the wrong time for the
current date.
The following is an example of some NetView command list language code that
can help you determine if you have the correct date and time:
-RETRY
&TDATE = &DATE
&TTIME = &TIME
&IF &TDATE NE &DATE &THEN &GOTO RETRY
&WRITE &TDATE &TTIME
REXX provides equivalent but more comprehensive time and date functions. For
more information, refer to the REXX library.
Nulls and Blanks Stripping

The stripping (removal) of trailing nulls and blanks is automatically performed by
the NetView program on some of the NetView command list language control
variables and NetView REXX functions that have character values. Notice that
some control variables and REXX functions have different levels of trailing
character removal.
Nulls and Blanks Stripping
Function or Variable Stripping Provided

ACTIONDL(), &ACTIONDL Nulls and blanks
ACTIONMG(), &ACTIONMG Nulls and blanks
APPLID(), &APPLID None
AREAID(), &AREAID None
AUTCONID(), &AUTCONID Nulls and blanks
AUTOTOKE(), &AUTOTOKE Nulls and blanks
CURCONID(), &CURCONID Nulls and blanks
CURSYS(), &CURSYS Nulls and blanks
CMDNAME() Blanks
DCO(), &DCO None
DOMAIN(), &DOMAIN Nulls and blanks
HCOPY(), &HCOPY Blanks
HMASPRID() Blanks
HMEVTYPE() Blanks
HMORIGIN() Blanks
HMUSRDAT() Blanks
IFRAUI3X(), &IFRAUI3X Nulls and blanks
IFRAUSB2(), &IFRAUSB2 Nulls and blanks
IFRAUSDR(), &IFRAUSDR Nulls and blanks
IFRAUSRC(), &IFRAUSRC Nulls and blanks
JOBNAME(), &JOBNAME Blanks
JOBNUM(), &JOBNUM None
LU(), &LU Blanks
MSGCOJBN(), &MSGCOJBN Nulls and blanks
MSGCPROD(), &MSGCPROD Nulls and blanks
MSGCSPLX(), &MSGCSPLX Nulls and blanks
MVSLEVEL(), &MVSLEVEL Nulls and blanks
NVDELID(), &NVDELID None
OPID(), &OPID Blanks
SESSID(), &SESSID Blanks
SYSCONID(), &SYSCONID Nulls and blanks
SYSID(), &SYSID None
SYSPLEX(), &SYSPLEX Nulls and blanks

Chapter 5. Automation Resource Management
This chapter is intended to help you perform NetView automation using command
lists.
Defining NetView Automation Table Command Lists

The automation table identifies which messages or MSUs are automated. It consists
of statements filed in a member of DSIPARM. The statements identify which
messages or MSUs are to be automated based on almost any attribute of the
message or MSU, such as:
v Message number
v Specific MSU field values
v Origin of message or MSU
| As a result, the automation table can change display, logging, routing, or almost
| any other disposition of the message. Commands or command lists can be called
| to analyze the message or MSU either before or in addition to any action taken.
| To define an automation table, code automation statements in a member of

| DSIPARM and then issue the AUTOTBL command using the name of that specific
NetView automation table. You can enter the AUTOTBL command anywhere a
regular command can be issued, and you can activate a table from the style sheet.
Notes:
1. A regular command is a command or command list defined with TYPE=H or
TYPE=R. See IBM Tivoli NetView for z/OS Administration Reference for further
explanation of a regular command.
2. You cannot run the AUTOTBL command under a DST.
For a complete definition of the syntax of the NetView automation statement, refer
to the IBM Tivoli NetView for z/OS Automation Guide. For the syntax of the
AUTOTBL command, refer to the NetView online help.
Routing Messages from Automation-Table-Driven Command Lists

You might have difficulty deciding where to route a message from the NetView
automation table. In order to make this decision, cause a command list to be
driven and use the MSGROUTE command or the ROUTE stage to route the
message to operators or groups of operators.
For more information about the MSGROUTE command, refer to the NetView
online help.
Implementing NetView Automation

This section provides suggestions to help you implement NetView automation. For
more information, refer to the IBM Tivoli NetView for z/OS Automation Guide.
Suppressing Messages
You can suppress some messages so that no operator receives them. To suppress
messages with NetView automation, make an entry in the NetView automation

Advanced Topics
member. Assume, for example, that you do not want the message IST4001
TERMINATION IN PROGRESS FOR APPLID applnm to be displayed. The following
example shows the NetView automation statement:
IF MSGID=’IST400I’ THEN DISPLAY(N);
Determining the Environment for a Command List

In REXX, if you are not sure of the type of task or condition under which a
command list is to run, have the command list check the TASK() function, the
PANEL function, or the AUTOTASK function. You can then use conditional
processing to make the command list flexible enough to run differently under
different tasks.
In NetView command list language, if you are not sure of the type of task or
condition under which a command list is to run, have the command list check the
&TASK control variable or AUTOTASK function in the beginning of the command
list. You can then use conditional processing to make the command list flexible
enough to run differently under different tasks. See Appendix B, “NetView
Command List Language Branching,” on page 123 for more information about
conditional processing.
Testing Automation Command Lists

There are several ways to test automation command lists to ensure that the
command list is called correctly from the NetView automation table and processes
correctly after being called.
| Verifying Proper Operation of Automation Command Lists

| In order to thoroughly test your REXX automation, you may want to verify proper
| automation of your NetView CLIST before you put it in the AUTOTABLE. The
| NetView program provides a means to simulate the current message that will be
| present when your REXX program is driven from the automation table. Sometimes
| it is sufficient to simply use the LITERAL stage to create your simulated message.
| However, LITERAL cannot set message attributes, such as job name or automation
| token, that might be important to your automation. If these message attributes are
| relevant to your testing, you can obtain an exact copy of the message for testing
| purposes by temporarily coding the HOLD(Y) automation action in place of the
| planned action.
| After this temporary automation is invoked, with the subject message held on your
| NCCF screen, you can use the HELDMSG stage to create accurate copies for
| testing. You can test this by issuing the TS command to cause tracing and then
| issue a command such as this:
| PIPE HELDMSG | NETV CMD (DIRECT) yourcmd yourarguments
| If there is more than one held message on the NCCF screen, you may also need to
| add a LOCATE or TAKE stage. After the PIPE HELDMSG command completes,
| yourcmd will be running outside of pipelines, and functions such as JOBNAME()
| and PIPE SAFE * in your procedure will return accurate results from the current
| message provided by the pipeline.
| You can stop this command and then reissued the TS and the pipe command to
| test repeatedly.

Advanced Topics
Verifying NetView Automation Table Entries

You can verify that an automation command list is driven correctly by the NetView
automation table by issuing the message from an operator station or command list.
From a NetView operator console, enter the message ID and message text from the
command line.
From a REXX command list, use the SAY instruction with the message ID and
message text in quotes.
From NetView command list language, use the &WRITE statement with the
message ID and message text in quotes.
If the message you create matches an entry in the NetView automation table, the
table processes any actions specified for that entry. Through this process, you can
test NetView automation table entries. This method works only if limited
information, such as the message identifier and message text, is checked in the
NetView automation table entry.
By using the AUTOCNT command with the STATS=DETAIL option, detailed

information, including the number of automated comparisons and matches, are
shown for each automation table statement. When your created message is
automated, the count of the number of comparisons and matches is incremented if
the message matches the intended automation statement.
Keeping a Record of Automation Command Lists Processed

Command lists can use the NetView MSG command to place information in the
network log. This transfer of information might be necessary because not all
command lists are run directly from the NetView automation table. Having
automation command lists send a message to the network log using the NetView
MSG command enables you to keep track of which automation command lists are
driven by which tasks and at what time.
For example, each automation command list could send a message to the log
containing the name of the command list and the parameters passed upon entry.
The task from which the message is issued and the time of the logged message are
automatically saved in the log. You can remove these MSG commands from the
automation command lists when testing is successfully completed.
Testing Automation Command List Processing

To test REXX automation command lists by tracing their processing, use the
TRACE command. If your command list is being run by a NetView automated
operator (autotask), the result of SAY or TRACE is not visible unless the autotask
is assigned an MVS console. The results are visible in the network log regardless of
whether the autotask is assigned to a console.
To test NetView command list language automation command lists by tracing their
processing, use the &CONTROL statement. If your command list is being run by a
NetView automated operator (autotask), the results of &WRITE, &BEGWRITE, or
&CONTROL are not visible unless the autotask is assigned an MVS console. The
results are visible in the network log regardless of whether the autotask is assigned
to a console. Refer to the AUTOTASK command in the NetView online help for
more information about assigning an autotask to an MVS console.
Chapter 5. Automation Resource Management 87

Advanced Topics
Recovering from Looping Command Lists

If you write a command list that is driven by a message issued by a command in
the same command list, looping can occur. If a looping message-driven REXX
command list contains an instruction that causes a wait, issue the STACK
command from the operator’s console to recover. Then, turn off NetView
automation with the command AUTOTBL OFF. If there is no instruction that
causes a wait, you can issue the AUTOTBL OFF command from your terminal.
Once the looping stops, you can revise the command list.
The REXX wait command is WAIT.
The NetView command list language wait statements are &WAIT and &PAUSE.
Considering Operator Interaction

Command lists used for automation of unsolicited messages should not ask the
operator for data.
For example, a REXX command list using a WAIT instruction requiring a GO

command is not appropriate.
For example, in NetView command list language, using either &PAUSE or &WAIT
statement and requiring a GO command is not appropriate.
Consider how messages from a command list affect operator requests, and try to
make automation command lists interfere as little as possible, because automation
runs at the same time operators enter requests.
Common Automation Problems

Because NetView automation is called after the command facility exit routines (for
example, DSIEX02A, DSIEX06, and DSIEX11) are called, changes made to messages
in these routines affect NetView automation. For example, if a message is deleted
by DSIEX02A, NetView does not call automation for that message. If a message is
assigned to SYSOP or LOG as the primary receiver, NetView does not call
automation for that message. Because NetView automation does not occur in the
preceding instances, the DISPLAY keyword in the NetView automation member
has no effect.
If the MVS message processing facility is used to suppress a message with

AUTO=YES coded and this message is used to drive a command list, when the
command list is driven and a WTO is issued, the WTO is also suppressed.
For REXX, you must change the setting of the MCSFLAG variable for the WTO to
be displayed.
For command list, you must change the setting of the &MCSFLAG control variable
for the WTO to be displayed.
Refer to the PARSEL2R command in the NetView online help for an example of
how to change a function or control variable.
If a multiline write-to-operator (MLWTO) message is used to drive a command list

and a WTO is issued from the command list, whether the WTO is displayed
depends on the setting of the MLWTO line type variable. If the setting of WTO is a
single-line message, change the setting to a blank.

Advanced Topics
The REXX MLWTO line type variable is LINETYPE.
The NetView command list language MLWTO line type variable is &LINETYPE.
Chapter 5. Automation Resource Management 89

Appendix A. Writing Simple Command Lists in the NetView
Command List Language
This chapter explains the basics of writing command lists for the NetView program
using the NetView command list language. This chapter also describes how
variables, assignment statements, and built-in functions fit together and how to
combine them in command lists.
What the NetView Command List Language Includes

The NetView command list language consists of six types of statements:
v Command
v Comment
v Control
v Assignment
v Label
v Null
Within command list statements, you can use the following:

v Parameter variables
v Control variables
v User variables
v Global variables
v Built-in functions
All except global variables are described in detail in later sections of this chapter.
Global variables and descriptions of passing parameter values are described in
Appendix C, “NetView Command List Language Global Variables,” on page 141.
The NetView command list language enables you to write application code to
perform repetitive or alternate processing (loop or if-then structures). These
features are implemented with the following control statements:
v &IF
v &GOTO
v &EXIT
v &WAIT
Control statements are described in Appendix B, “NetView Command List

Language Branching,” on page 123.
| Note: Command lists can interrupt the processing of other command lists. This is
| done using the CMDDEF statement in CNMCMD.
Coding Conventions for NetView Command List Language Statements

Like any other language, the NetView command list language requires that you
follow syntax rules. The following coding conventions for NetView are divided
into sections describing the conventions for:
v General coding
v Continuing a statement
v Double-byte character sets
v Suppression characters

NetView Command List Language Command Lists
Conventions for General Coding

Use the following coding conventions when writing command lists in the NetView
v Code a CLIST statement as the first line of your command list; the CLIST
statement is optional. Code CLIST statements as follows:
| – Optionally, code a label. The label must begin in column 1. You cannot branch
| to this label; the NetView program ignores the label.
| label CLIST
| – Code the word CLIST beginning in column 2 or later. The word CLIST must
be preceded by at least one blank.
v Do not code the name of the command list on the first line unless accompanied
by the word CLIST.
v Leave column 72 blank for all statements.
v Do not use columns 73-80. They are reserved for optional sequence numbers.
v Code at least one blank after a label (if there is one) or before a keyword.
v Code at least one blank between a control statement and the first operand.
v Separate operands with one or more blanks, or a single comma with no blanks.
v Code any number of leading or trailing blanks on your statements.
v Use lowercase letters only as comments or part of a message sent to the
operator. In all other cases, use uppercase for alphabetical characters A-Z.
v Code statements so that the maximum length is 32 000 characters after variable
substitution.
Note: To familiarize yourself with how variable substitution works, see

“Variable Substitution Order” on page 95.
v Code comment lines with an asterisk (*) as the first nonblank character of the
command list line. Place the comment after the asterisk. Comment lines cannot
appear on the first line of a command list.
v Code the command list so that it ends by processing the last command list
statement, or by reaching an &EXIT statement. An operator entering RESET also
ends the command list.
Conventions for Continuing a Statement

Use a plus sign (+) or a hyphen (-) as a continuation character to continue a
statement that is too long to fit on one line. Code the continuation character as the
last nonblank character before column 72 on the line to be continued.
Note: Do not code a comment between the beginning and end of a continued
statement.
v The plus sign causes the text of the continuation line to begin where the plus
sign was placed without any of the blanks leading up to the first nonblank
character on the continued line.
The plus sign causes these lines:
&WRITE THIS STATEMENT IS CODED +
AS +
THREE LINES
to become this single statement:

THIS STATEMENT IS CODED AS THREE LINES
v The hyphen causes NetView to keep all the blanks at the end of the line with
the hyphen (up to but not including column 72) and then fill the line to its end
with characters from the beginning of the continuation line. The hyphen is
replaced by a blank. When filling a line with characters from the beginning of
the continuation line, NetView does not split a word across lines of an output
screen. The last character used for filling in from the continuation line must be a
blank or the last character on the line.
For example, if you coded the following &WRITE statement to be displayed on
an 80-character-wide terminal:
&WRITE STATEMENT CONTINUED WITH THE HYPHEN TO KEEP -
BLANKS
All the blanks from the P in KEEP to the B in BLANKS would be kept. The first line
would write 64 characters to the output screen (43 characters of text plus 21
blanks from the end of the text to column 72). The output screen has 68 columns
to be used for display (80 minus the 12-character prefix), so the hyphen would
cause the first four characters of the second line to be placed at the end of the
first line. In the example, this would be two blanks and the letters BL. However,
because the NetView program does not split a word across lines of the output
screen, the message is displayed as:
STATEMENT CONTINUED WITH THE HYPHEN TO KEEP
BLANKS
Conventions for Double-Byte Character Set Text

In a double-byte character set (DBCS), each symbol is represented by a 2-byte code
rather than a 1-byte code.
v Use A-Z, 0-9, @, $, and # characters to code NetView commands and command
lists used as commands. The command list name must begin with a nonnumeric
character.
v DBCS data input is not supported.
v Enclose all DBCS strings within shift-out (X'0E') and shift-in (X'0F') control
characters. Be sure there are an even number of bytes in each DBCS string. (If
you are using an editor and terminal that supports double-byte characters, this
is done automatically.)
v You can code label names, variable names, and variable values in DBCS
characters. Restrict variable names and label names to a length of 11 bytes. This
11 bytes includes shift-out (X'0E') and shift-in (X'0F') control characters.
v When DBCS labels and variables are displayed on a DBCS terminal, the shift-out
and shift-in control characters appear as blanks.
v DBCS text can be split across multiple lines, using an EBCDIC plus sign (+) or
hyphen (-) as a continuation character. To split a string, end the string with a
shift-in (X'0F') control character followed by the continuation character. Start the
next line with a shift-out (X'0E') control character to resume the string.
v When writing DBCS text in a &BEGWRITE statement, the SUB option is
required.
v Comments can contain DBCS strings enclosed by shift-out (X'0E') and shift-in
(X'0F') control characters.
v &WRITE, &CONCAT, and &SUBSTR are enabled for DBCS.
Conventions for Suppression Characters

The following rules apply when coding suppression characters:
v The first nonblank character before a command is the suppression character.
v When you browse or list a file, you can see every line, even suppressed lines.
Appendix A. Writing Simple Command Lists 93

v In general, do not use suppression characters preceding a NetView CLIST

language label. The suppression character prevents you from branching to the
label unless the command list line containing that label has already been
processed.
In Figure 38, the control variable &SUPPCHAR is replaced with the character
defined as a suppression character. The last line of the command list in the
example is suppressed.
&CONTROL CMD
* COMMAND LIST UPDATED 2/5/95 BY OPERATOR CARL
START DOMAIN=&1
&WRITE ENTER GO WHEN MESSAGE DSI809I ARRIVES FROM &1
&PAUSE
&SUPPCHAR ROUTE &1,OPER1,123456
Figure 38. Example of Using Suppression Characters
When issuing a command that returns its status in the return code, you can
suppress synchronous output from the command by coding the suppression
character twice. For example, if you use the following code in a command list, no
synchronous output from the command list is displayed to the operator:
&DOUBLESUPP = &CONCAT &SUPPCHAR &SUPPCHAR
&DOUBLESUPP SET PF24 IMMED RETRIEVE
Use the double suppression character when sufficient status is provided by the
return code and to enhance performance on commands that produce line mode
messages synchronously. Using the double suppression character does not affect
output that is scheduled by a command (for example, D NET,APPLS), nor does it
consistently reduce output from a long-running command (for example, NLDM).
Labels
Labels identify command list statements for control of flow, for internal
documentation, or to indicate the target statement for a transfer of control.
Transferring control is explained in Appendix B, “NetView Command List
Language Branching,” on page 123.
You can code labels on any command list statement except a comment statement.
You can code labels on commands, control statements, assignment statements, and
null statements. If NetView cannot find the label, processing stops, and NetView
issues an error message.
A label must be the first nonblank word on a command list line. A label consists of
an EBCDIC hyphen (-) followed by 1 to 11 characters (A-Z, 0-9, #, @, $). You do
not have to code a command list statement after a label. If you do, however, start
the command list statement after the label, leaving at least one blank between the
label and a keyword.
You can also code other labels. All labels must be unique within a command list. If
you have two identical labels in one command list, NetView ends the command
list. You can also code labels as internal comments to show where different parts of
your command list start. For example, you can use labels to highlight certain
processing routines.
The following examples are labeled command list statements:

-MYLABEL VARY NET,INACT,ID=LU1234

-$PROC2 &LEN = &LENGTH &1
-SETUP &USER = 55
-ALLALONE
Note: Labels are used with &BEGWRITE to show where a message stops.
Variables are not allowed in labels, but you can code a variable as the label
name with the &BEGWRITE, &GOTO, or &WAIT statements. These
statements for transfer of control are described in Appendix B, “NetView
Command List Language Branching,” on page 123.
Variables
Variables enable you to accept from an operator, or define for yourself, different
values for the statements within a command list. With the following variables, you
can write a command list that operates correctly in many different situations:
v Parameter
v Control
v User
v Global
This section describes how to use parameter, control, and user variables. This
section also describes how to use the NetView PARSEL2R command to parse
variables in a command list. See Appendix C, “NetView Command List Language
Global Variables,” on page 141 for a description of global variables.
Code the variable as the first nonblank word in the command list.
A variable consists of an EBCDIC ampersand (&) followed by 1 to 11 characters

(A-Z, 0-9, #, @, $).
Variable Substitution Order

Variable substitution is performed when the NetView program scans each
statement from right to left and substitutes values for each variable as follows:
1. Each element is scanned from right to left for an ampersand (&).
v If found, the ampersand and the rest of the element to the right are
substituted with the value of that variable.
v If no value exists, the variable becomes null.
v If the first character to the right of the ampersand is a number, the variable is
assumed to be a parameter variable. The NetView program then scans to the
right and takes any following numbers as part of the parameter variable.
When the NetView program comes to a blank or a letter, the search stops. If
a special character (non-alphanumeric) is found, the NetView program
delimits the variable name.
For example, &21A is taken as &21 and is replaced by the value of &21.
Therefore, &21A becomes valueA. For another example, if an element
contains &A=&XYZ, the NetView program first substitutes the value of
&XYZ, then the NetView program replaces &A with the value substituted for
&XYZ.
Note: The value of X'50' (ampersand in the EBCDIC character set) is ignored
within double-byte character sets. If you want to use an ampersand,
end the string using a shift-in (X'0F') control character and enter the
variable. To resume the string, begin the string using a shift-out (X'0E')
control character.

2. The scan resumes at the next character to the left, and the search for an
ampersand continues. If found, the ampersand and the entire syntactical
element to the right, including the previous substitution, are taken as the name
of a variable and are replaced by the variable value.
Note: The value substituted is not scanned for an ampersand.

If the element is the target of an assignment statement, the scan stops on the
second character to preserve the variable name that is to be assigned a value.
For example, the statements in the following example set the value of user
variable &A1 to 2.
&B = 1
&A&B = 2
Variable substitution is not done on the following:

Control keywords
For more information, see “&CONTROL Statement” on page 104.
&PAUSE statement
The variables are assigned values when you enter a GO command. For
more information, see “&PAUSE Control Statement” on page 108.
&THEN clause on an &IF statement
If the &IF clause is true, the &THEN clause is made into a statement and
processed as if it is coded separately. For more information, see “&IF
Control Statement” on page 123.
Any statements in an &BEGWRITE NOSUB series of messages
For more information, see “&BEGWRITE Control Statement” on page 107.
Built-in functions
For more information, see “NetView Built-in Functions” on page 111.
Parameter Variables
A parameter variable is a positional variable that is defined at the time a command
list is run. Specify parameter variables by entering them as operands following the
name of the command list that you are running. Parameter variables have the
following characteristics:
v Identified within the command list by a numbered position, for example, &1
v Entered following the command list name at run time
v Delimited by commas, apostrophes, or blanks
When you code your command list with parameter variables, use the following
guidelines:
v You can use up to 31 parameter variables in a single command list.
v You can use the same parameter variables more than once in a command list.
v The value of a parameter variable can be 238 characters long.
v Parameter variables can contain either numerical or character values.
v When used in an arithmetic expression (for example, addition or subtraction), a
parameter variable can have a numerical value between -2147483647 and
2147483647. When used in a non-arithmetic expression (for example, assignment
statements, &IF statements, &CONCAT, or &SUBSTR statements), a parameter
variable can have a value up to 238 digits long, including the sign.
Note: When NetView receives a message coded in an &WAIT statement, NetView

sets some control variables (for example, &MSGORIGIN, &MSGID,

&MSGCNT, and &MSGSTR) and also changes the values of the parameter
variables (&1 – &31) to reflect the information in the received message.
See “Control Variables” on page 100 for information about these variables.
LINKPD sets the same control and parameter variables. See “LINKPD Results” on
page 151 for more information about the LINKPD command.
Passing Parameter Variable Information to a Command List

When activating a command list that uses parameter variables, the operator enters
the command list name followed by a value for each parameter variable in the
command list. The following example shows the format for an operator passing up
to 31 parameter variables to a command list:
cmdlistname _____,_____,_____,. . .,_____
&1 &2 &3 &31
The first value after the command list name replaces &1 in the command list, the
next value replaces &2, and so on. For example, the second parameter variable in a
command list would be coded &2 at the place where you want the value of that
parameter.
Assume that you wrote a command list named RESC to start resource LU100 as
shown in the following example.
RESC CLIST
&CONTROL ERR
VARY NET,ACT,ID=LU100
If you want the command list to use parameter variables, you can change it to
activate or inactivate any resource. The following example shows how the
command list looks with parameter variables:
RESC CLIST
&CONTROL ERR
VARY NET,&1,ID=&2;
The operator can then start resource LU100 by entering RESC ACT,LU100.
When the command list runs, &1 and &2 are replaced with the following
positional parameters:
v &1 with ACT
v &2 with LU100.
The command list takes the values for &1 and &2 from the entered operands in the
order in which the operands are entered after the command list name.
Note: The operator who uses the command list must be told how many parameter
variables to supply and what values to provide.
If a command list is activated by a message, each word of the message becomes a

separate parameter variable. This is explained in more detail in Chapter 5,
“Automation Resource Management,” on page 85.
Using Parameter Variables in a Command List

There is no set order for placing the parameter variables in the command list. The
following example shows that you can use &2 before &1.
V NET,&2,ID=&1

&1 is given the first value the operator enters, and &2 is given the second value.
If there are two or more parameter variables in one command list statement, the
rightmost variable is changed first. The NetView program continues to scan right
to left and replaces the next variable. You can use this method to change the
meaning of some of your parameter variables. If you need to test how many
parameters an operator entered or what parameter values were entered, use the
control variables &PARMCNT and &PARMSTR. They are described in “Control
Variables” on page 100.
Passing Parameter Variables to a Nested Command List

You can code parameter variables on the command list statement that activates the
nested command list. These parameter variables follow the same basic rules as
other parameter variables. In addition, you can pass either actual values or other
variables as parameter variables. If you pass other variables, make sure these
variables are known to the next activated command list.
The following are examples of passing parameters.
Command list CALLER contains a line of code such as:

CALLEE LINES,TERMS,CDRMS
Command list CALLEE uses the following variables:

&1 LINES
&2 TERMS
&3 CDRMS
Command list MAJOR is activated by entering MAJOR ALPHA,BETA and contains

the following statements:
&A = 55
MINOR &A,&1,&2
Command list MINOR uses the following variables:

&1 55
&2 ALPHA
&3 BETA
Command list MINOR takes the value of &A (55) as its first parameter, the value
of MAJOR’s first parameter (ALPHA) as its second parameter, and the value of
MAJOR’s second parameter (BETA) as its third parameter.
If you need to pass a nested command list a variable containing a quoted string,
enclose the variable in single quotation marks on the nested command list call. In
the following example, CLIST1 calls CLIST2:
CLIST1 CLIST
&STR = &1
CLIST2 ’&STR’
&EXIT
Note: The parameter variable on the nested command list call must be surrounded
by quotation marks.

Using Quoted Strings or Special Characters in Parameter

Variables
If you need to use a blank, apostrophe, or comma as part of a value, you must
make the value a special character string by using single quotation marks. If you
want a text string to be taken as the value for one parameter, it must also be made
a special character string.
A NetView command list language quoted string is any text that meets one of the
following requirements:
v Text preceded by a delimiter and a single quotation mark, followed by either a
single quotation mark and a delimiter or a single quotation mark that is the
rightmost nonblank character
v Text preceded by a single quotation mark that is the leftmost nonblank character,
followed by a single quotation mark and a delimiter
v Text preceded by a single quotation mark that is the leftmost nonblank character,
followed by a single quotation mark that is the rightmost nonblank character.
Suppose you activate a command list name RESC by entering the following:
RESC ACT,’LU200,LOGMODE=S3270’
The parameter variables in the RESC command list would contain the following
values:
&1 = ACT
&2 = LU200,LOGMODE=S3270
Suppose you activated the RESC command list by entering:

RESC ACT,LU200,LOGMODE=S3270
The parameter variables in this case contain the values:

&1 = ACT
&2 = LU200
&3 = LOGMODE=S3270
Null Parameter Values

Use a comma immediately following another comma (,,) to give a parameter
variable a null value when it is followed by other non-null parameters. After the
last non-null parameter, all remaining parameter variables up to &31 are
automatically given null values. Null parameters are useful when a value is not
required. For example, assume you wrote a command list called CONN that
contained the following statement:
BGNSESS FLSCN,APPLID=&1,SRCLU=&2,LOGMODE=&3,INT=&4,D=&5
If you do not want to specify all the values, you can enter the following:
CONN TSO,TAF01F00,,,PF12
In this example, &1 is TSO, &2 is TAF01F00, &3 and &4 are null, and &5 is PF12.
The extra commas between TAF01F00 and PF12 represent positional place holders
for &3 and &4, and tells the command list that they are null. If you use only one
comma, the command list takes PF12 as &3 and incorrectly uses PF12 as the
LOGMODE.
Test for null parameter variables in your command list and provide default values
to avoid possible syntax errors.

Control Variables
The following sections describe the control variables as used in NetView command
list language.
Control variables are set by the NetView program based on system information. To
use a control variable, place the variable name in the command list at the location
where you want the information to be accessed. When the command list runs,
NetView gives the correct values to each control variable. Use the LISTVAR
command to view the values of some of the control variables.
For more information about control variables used with the SPCS commands
LINKDATA and LINKTEST, see “LINKDATA and LINKTEST Results” on page 150.
Note: A command list can create a user variable that the NetView program has
already defined as a control statement, control variable, or built-in function.
However, if such a user variable is created, you cannot use that NetView
provided control statement, control variable, or built-in function in that
command list anymore.
User Variables
User variables are variables you create and set within the command list. You can
set user variables with an assignment statement or an &PAUSE control statement.
Assignment statements are explained in “Assignment Statements” on page 102.
The &PAUSE control statement halts the command list, enables the operator to
enter data, and picks up the value of the user variable from the operator when the
command list continues. &PAUSE is described in “&PAUSE Control Statement” on
page 108.
When you create user variables, observe the following rules:

v The first character must be an ampersand (&).
v The first character following the ampersand must be a letter or a symbol, not a
number. Otherwise, the NetView program treats it as a parameter variable.
v The ampersand must be followed by 1 to 11 characters. A-Z, 0-9, #, @, and $ are
valid characters.
v The value of the user variable can be 255 characters long. The maximum number
of double-byte characters between the shift-out (X'0E') and shift-in (X'0F') control
characters is 126.
v A user variable can have a numerical value that is 255 digits long, including the
sign. However, if the value of the user variable is obtained using an arithmetic
expression (for example, addition or subtraction), or if the user variable is used
in an arithmetic expression, the user variable can have a numerical value
between -2147483647 and 2147483647. The only characters you can use in a
numeric value are 0-9. The numeric value can be immediately preceded by a
character indicating whether the value is positive (+) or negative (-).
Note: A command list can create a user variable that the NetView program has
already defined as a control statement, control variable, or built-in function.
However, you cannot use that NetView-provided control statement, control
variable, or built-in function anymore in the command list.

Table 17 on page 101 shows some examples of user variable names.

Table 17. User Variable Names
Valid Non-valid Reason
&A &2A Is read as &2, a parameter variable
&USERNAME &INVALIDUSERNAME Too long
&@23456 &A% % is not a valid character
The following example shows how to manipulate user variables in assignment

statements to set parameters and to communicate with the operator.
&PAUSE VARS &ONE &TWO
&SUM = &ONE + &TWO
CLEAR
&WRITE >>> THE SUM OF &ONE + &TWO IS --->&SUM
Hexadecimal Notation
The NetView command list language provides a hexadecimal notation capability to
process hexadecimal data. You can use hexadecimal notation anywhere you can
use a command list variable, except as the receiver in an assignment statement.
The following syntax describes the hexadecimal notation for the NetView
X'n'
where:
n Is an even or odd number of hexadecimal digits (0-9 or A-F in uppercase) with
no embedded blanks. If n is an odd number of digits, the NetView program
prefixes the number with a zero (for example, X'2C6' would be converted to
two bytes whose hex value would be 02C6). The maximum length of n is 255
hexadecimal digits.
The following are examples of the use of hexadecimal notation:
&A = X'3B9' &IF &A = X'3B9' &THEN....
Comments
It can be helpful to code comments in a command list. Command lists with
comments are easier to maintain and expand than command lists without
comments.
You can use comments to show the following:

v When the command list was created and updated
v Who wrote the command list
v The function of the command list
v What input and output is expected
v Whether the command list depends on other programs or on other command
lists.
To write a comment, code an asterisk (*) as the first nonblank character of the
command list line. Be sure that you do not use a string of hyphens to separate
sections of the command list.

Null Statements
A null statement contains all blanks or a label followed by all blanks. A null
statement with a label can be the target of flow control (conditional processing)
statements or &BEGWRITE statements. See “Labels” on page 94 for details about
using labels.
You can use a null statement to help format a message to the operator or to break
up a long command list so that it is easier to read and update. If a null statement
is part of a message written with an &BEGWRITE statement, it is sent to the
operator as a blank line. If a null statement is used to break up the command list,
NetView ignores the statement when the command list is run.
Assignment Statements
Assignment statements give values to variables and do arithmetic operations
within a command list. The syntax of an assignment statement is:
assignment
&variable = expression
Figure 39. Assignment Statement
There must be a blank before and after the equal sign.
When the command list runs, the value of the user variable is set to the value of
the expression. For example, the assignment statement &A = 5 sets the &A to 5.
The assignment statement &B = &1 sets the &B to the value of &1, and &1 keeps
its value.
An expression is one of the following:

Constant
A constant consists of alphanumeric characters that are not replaced by
other values. The values are fixed. For example, if you code the following
assignment statement:
&VAR = 5
the value 5 is assigned to user variable &VAR.
If you want to use a constant that contains a blank, comma, apostrophe, or

hyphen, use single quotation marks. For example:
&NAME = ’JOHN B. DOE’
The constant cannot be longer than 255 characters. If it is a number, the

constant must be between -2147483647 and 2147483647. The only characters
you can have in a numeric value are 0-9. The numeric value can be
immediately preceded by a character indicating whether the value is
positive (+) or negative (-).
Variable
A variable can be a parameter variable, control variable, user variable, or
global variable.
The following assignment statement:

&PARMVAR = &4
assigns the value of parameter variable &4 to user variable &PARMVAR.
To assign the value of control variable &OPID to user variable &USERVAR,

code the following:
&USERVAR = &OPID
Note: Using a control statement as a variable is not valid, even if the

control statement is enclosed in single quotation marks. For
example, the following assignment statements are not valid:
&A = &IF
&A = ’&WAIT ERROR’
Arithmetic operation
The addition and subtraction operations are allowed in an assignment
statement. The format is two numbers separated by a plus (+) or minus (−)
sign. You can also use a variable that is to be set to a number. The only
characters you can use in a numerical value are 0-9. The numerical value
can be immediately preceded by a character indicating whether the value
is positive (+) or negative (−).
The plus or minus sign must be separated from the numbers on each side
by at least one blank unless it indicates a positive or negative number (−2,
−4). For example, both 4 − 2 and 4 − −2 are correct, but 4 −2 does not
work.
The result of the arithmetic operation must be between −2147483647 and
2147483647. The following assignment statement shows how you can use a
control variable in an arithmetic operation:
&SUM = 38 − &PARMCNT
The value of control variable &PARMCNT is subtracted from 38, and the
resulting value is assigned to variable &SUM.
In arithmetic expressions with leading zeros, the leading zeros are not
shown in the result. For example, assume &A is 01 and you code the
following:
&C = &A + 1
The value of &C becomes 2, not 02.
Note: To avoid an error condition in an arithmetic operation, code a zero

before a potential null variable.
Built-in function
You can use a built-in function in an assignment statement. The result of
the operation is placed in the user variable. See “NetView Built-in
Functions” on page 111 for a detailed description.
The following examples show how to code built-in functions in assignment
statements:
&STR2 = &SUBSTR &STRING 2 1
&STR1 = &SUBSTR &STRING 1 1
&NEWSTR = &CONCAT &STR5 &STR4
&NEWSTR = &CONCAT &NEWSTR &STR3

Control Statements
Control statements are unique command list statements that control the way the
NetView program acts on other statements in the command list. You can use the
control statements in this chapter either for straight-line coding or in conjunction
with the statements described in Appendix B, “NetView Command List Language
Branching,” on page 123 for conditional processing.
You can use control statements to change the sequential order of processing.
Command list control statements enable you to:
v Send messages to the operator from the command list.
v Control the order in which commands are run.
v Ask the operator to enter information needed to continue the command list.
v Wait for a solicited message to arrive before continuing the command list.
Each command list control statement begins with the control symbol in the form
&word. Only one control statement can be coded on a line, except when using &IF.
After reading the descriptions of the control statements, you should have a general
idea of the capability of these basic statements. Read the sections that follow for
details concerning each control statement.
The control statements follow:

&BEGWRITE
Writes a message or series of messages to the operator.
&CONTROL
Indicates the command list statements that are shown on the operator’s screen
while the command list is running.
&PAUSE
Halts the command list until the operator enters information needed to
continue the command list.
&WRITE
Writes a message to the designated operator.
&CONTROL Statement
The &CONTROL statement lets you indicate which command list statements are
displayed at the operator’s terminal while the command list is running. The
indicated command list statements are displayed after all substitutions have been
made and before the command list statements run. You can use the display of the
command list statements from &CONTROL ALL or &CONTROL CMD to help
debug your command list.
Set &CONTROL at the beginning of the command list. You can change the
&CONTROL setting within the command list as many times as necessary.
&CONTROL is in effect from that point in the command list until the next
&CONTROL statement is reached. For example, if you just added a new section of
code to a command list, you can display the entire new section of code but view
only the errors for the existing sections of code. Code this control statement by
typing &CONTROL followed by a blank and an operand. The syntax of the
&CONTROL control statement is:

&CONTROL
ALL
&CONTROL
CMD
ERR
where:
ALL
Displays all command list statements at the operator’s terminal. Each statement
is displayed just before it is processed. &CONTROL ALL is a good choice
when you first write the command list and want to test it. Once your
command list is tested, &CONTROL CMD or &CONTROL ERR is a better
choice. When processing for this command list is complete, the following
message is displayed:
DSI013I COMMAND LIST clistname COMPLETE
If you code &CONTROL without operands, or if you do not code

&CONTROL, the default is &CONTROL ALL.
CMD
Displays all commands at the operator’s terminal. Each command is displayed
just before it runs. The other command list statements—such as comments,
control statements, and other command list language statements—are not
displayed unless they contain an error. When processing for this command list
is complete, message DSI013I COMMAND LIST clistname COMPLETE is displayed.
ERR
Displays only statements that contain errors and commands that have nonzero
return codes. If &CONTROL ERR is in effect at the end of a command list,
message DSI013I is not displayed.
Writing to the Operator

The &WRITE and &BEGWRITE statements send messages to the operator terminal.
&WRITE sends a one-line message, and &BEGWRITE sends multiline messages.
These statements are used to give the operator information, such as what the
command list is doing.
The messages are sent to the operator regardless of the &CONTROL setting. If you
code a command on an &WRITE control statement, the text is sent to the operator
as a message, but it is not run as a command list command.
Do not confuse the use of &WRITE and &BEGWRITE with the use of command
list comments. Comments are for the person writing the command list and are not
sent to the operator, unless &CONTROL ALL is set. &WRITE and &BEGWRITE
send messages to the operator.
If you are sending more than one message line or displaying a table that takes up
the whole screen, you might want to use the NetView VIEW command instead of
using &WRITE or &BEGWRITE.
&WRITE Control Statement

The &WRITE statement sends one line of text to the operator. The NetView
program performs variable substitution on the message text before sending the
message to the operator. If you do not want substitution performed on the message

text, use &BEGWRITE. If you do not include message text, the NetView program
sends a blank line to the operator. The syntax for the &WRITE statement is:
&WRITE
&WRITE message_text
If you want to include blanks in front of the first character of the line, code a
nonblank character after &WRITE.
In the following line:

&WRITE . THIS LINE WILL START IN COLUMN 8
the period causes the line to print like this:

. THIS LINE WILL START IN COLUMN 8
Otherwise, the line shifts left until the first nonblank character is in column 1.
The following line has no period:

&WRITE THIS LINE WILL SHIFT TO COLUMN 1
so it prints like this:

THIS LINE WILL SHIFT TO COLUMN 1
The following is an example of a command list called PATH that uses the &WRITE
control statement and a VTAM command.
PATH CLIST
&CONTROL CMD
* THIS COMMAND LIST DISPLAYS INFO ON VTAM SWITCHED PATHS
&WRITE *** STATUS OF VTAM SWITCHED PATHS FOR &1 ***
D NET,PATHS,ID=&1
Activating this command list by entering PATH HD3790N1 causes Figure 40 to be

displayed.
*** STATUS OF VTAM SWITCHED PATHS FOR HD3790N1 ***

D NET,PATHS,ID=HD3790N1
IST097I DISPLAY ACCEPTED
IST148I DIAL OUT PATH INFORMATION FOR PHYSICAL UNIT HD3790N1
IST149I LINE GRP TELEPHONE NUMBER OR LINE NAME PID GID CNT
IST168I EGROUP40 4094 001 001 005 AVA
AUT
IST168I EGROUP50 4094 002 002 001 AVA
MAN
IST314I END
Figure 40. Result of PATH Example Command List
Notice that the &1 in the &WRITE statement is replaced by the value HD3790N1
before it is sent to the operator. Because &CONTROL CMD was coded, the
command is also shown. The rest of the display is the response to the VTAM
command.
Figure 41 on page 107 shows several &WRITE statements, which send one-line
messages to the operator.

CLEAR
&WRITE >>> THE SUM OF &ONE + &TWO IS --->&SUM
&WRITE THE MIRROR IMAGE IS: &NEWSTR
&WRITE TOTAL CHARACTERS ENTERED: &LEN
&WRITE *** END OF SAMPLE CLIST ***
Figure 41. Sending One-line Messages to the Operator
&BEGWRITE Control Statement

You can use &BEGWRITE to write a series of lines to the operator terminal. You
can also control whether variables are replaced before sending the messages.
Code the &BEGWRITE statement on a line by itself, one line above the first
operator message you want to send. You can also specify a label on &BEGWRITE.
The label tells the command list where the messages end and command list
processing continues. See “Labels” on page 94 for more information about labels.
You can indicate that you want variables replaced by their actual values before the
messages are sent to the operator. If you do not indicate a choice, variables are not
replaced.
The syntax for the &BEGWRITE statement is:
&BEGWRITE
NOSUB
&BEGWRITE
SUB −label
where:
-label
Indicates the line that follows the text to be displayed to the operator. If you
code a label in the statement, this label must be on a statement following the
end of the message text lines in the command list. The command list lines
between &BEGWRITE and the statement with the label are sent to the
operator. The command list statement with the label is not sent to the operator;
it is processed as the next command list statement. If the NetView program
cannot find the label, the rest of the command list statements are sent to the
operator as comments and the command list is ended. If there is no label on
&BEGWRITE, only the first command list statement after &BEGWRITE is sent
to the operator.
You can code a variable for your label on &BEGWRITE. Replace the variable
with a valid value.
NOSUB
Writes the messages to the operator exactly as they are typed, with no variable
substitution. In other words, &1 is sent as &1, not as the value of &1. Use this
operand to write about the command list variables in your messages. NOSUB
does not remove blanks. It displays the text exactly as it is entered. If you code
&BEGWRITE without an operand, the NetView program assumes NOSUB.

SUB
Causes the NetView program to carry out substitution on the message text
before sending the messages to the operator. See “Variable Substitution Order”
on page 95 for information about how the NetView program carries out
variable substitution.
If there are blanks before the first character on a message line, the line is
shifted left until the first nonblank character is in column 1. If you want the
blanks sent to the operator’s screen, code a nonblank character in column 1. If
you are using &BEGWRITE to write a message containing double-byte
character set (DBCS) characters, you must use the SUB option. These coding
rules are the same as those for &WRITE.
Figure 42 is an example of a &BEGWRITE statement with variable substitution.
&BEGWRITE SUB -ENDTEXT

.
>>> HELLO &OP.
>>> YOU CAN INITIATE CROSS-DOMAIN SESSIONS WITH &ID.
.
. NOW FOR SOME CHARACTER MANIPULATION
. ENTER ’GO’ FOLLOWED BY A FIVE CHARACTER STRING.
. THE CLIST WILL PRINT OUT THE MIRROR IMAGE TO YOU.
.
-ENDTEXT
Figure 42. &BEGWRITE with Variable Substitution
In some cases, you might not want variable substitution. In the following example,
the &BEGWRITE statement shows the operator how to use the ENDIT command
list:
&CONTROL ERR
&BEGWRITE NOSUB -OVER
TO END FULL SCREEN SESSIONS,
TYPE "ENDIT &1,&2,&3"
REPLACE &1,&2,&3 WITH
THE APPLID NAMES OF THE
FLSCN SESSIONS TO BE ENDED
-OVER
The ENDIT command list is called by entering ENDIT. Figure 43 shows the
messages that the operator sees when ENDIT is used.
TO END FULL SCREEN SESSIONS,

TYPE "ENDIT &1,&2,&3"
REPLACE &1,&2,&3 WITH
THE APPLID NAMES OF THE
FLSCN SESSIONS TO BE ENDED
Figure 43. Result of ENDIT Example Command List
Notice that &1, &2, and &3 are not replaced by their values when the messages are
sent to the operator.
&PAUSE Control Statement

Using the &PAUSE control statement along with other commands, you can code
command lists that ask the operator questions and pick up the entered responses.
Use the &BEGWRITE and &WRITE control statements to send instructions to the
operator. For example, you can code the command list to instruct the operator to
enter the NetView GO command followed by a value or values for a user variable.

Then code the &PAUSE statement to temporarily halt the command list. The
command list pauses until the operator enters the GO command to continue
processing, or the RESET command to end the command list. You can code the
&PAUSE command to enable the command list to pick up the operands following
the GO commands and take them as user variables. See “User Variables” on page
100 for more information.
Notes:
1. Using &PAUSE in an automation task command list or a command list that
runs under the PPT is not valid.
2. The VIEW command obtains operator input without requiring the use of the
GO command.
The syntax for the &PAUSE statement is:
&PAUSE
NOINPUT
&PAUSE
VARS variable
STRING variable
where:
NOINPUT
Pauses until the operator enters the GO or RESET command. Operands cannot
be specified with the GO command. If the operator enters operands, an error
message is returned. NOINPUT is the default.
STRING variable
Pauses until the operator enters the GO command with or without a string, or
the RESET command. A previous &WRITE or &BEGWRITE statement notifies
the operator to enter operands with the GO command. The entire string of
operands is taken as one user variable. The variable can then be used in the
command lists.
VARS variable
Pauses until the operator enters the GO command with or without the correct
number of operands, or the RESET command. A previous &WRITE or
&BEGWRITE statement notifies the operator to enter operands with the GO
command. Each operand is taken as a user variable coded on the &PAUSE
VARS statement. These variables can then be used in the command list.
When the command list interprets an &PAUSE control statement, the letter P
appears in the upper right corner of the panel to alert the operator that the
command list is in pause state. Pause state means that the command list has halted
and is waiting for input from the terminal.
Note: If a command list in pause state was called by an NNT session, the P
indicator is not displayed on the OST panel.
Using NetView Commands with &PAUSE

The operator can enter the NetView commands GO, RESET, STACK, and
UNSTACK during a pause.

STACK and UNSTACK enable the operator to suspend and then resume command
list processing during an &PAUSE. Once the STACK is issued, the operator can
enter any network command.
Note: While an &PAUSE is suspended with the STACK command, the P is

removed from the upper right corner of the panel. The P reappears after
UNSTACK is issued. After UNSTACK is issued, the operator enters GO,
with or without operands, to continue the command list, or enters the
RESET command to end the command list. RESET also ends any nested
command lists.
The operands on the GO command are positional. This means the first operand
becomes the first user variable, the second operand becomes the second user
variable, and so on. Operands are separated by either a blank or a comma. If you
want to include a blank or a comma as part of one variable, use either &PAUSE
STRING or put the operand between single quotation marks.
Code a user variable for each expected operand. If the operator enters more
operands on the GO command than expected by the command list, the extra
operands are ignored. If the operator enters fewer operands than expected, the
remaining variables are set to null. The operator can also skip over one operand by
coding two commas in a row.
Precede the pauses for operator input with messages that supply the information
to enter. Use the &WRITE or &BEGWRITE statements to send this information.
Note: The operator can call your command list from any NetView component. If
you expect the command list to run from components other than the
command facility, use the NetView command NCCF in the command lists to
present the operator with the command facility panel and command panel
input area. (Do this before issuing any messages.) If the command list is
running in the command facility, the NCCF command has no effect. Refer to
the NetView online help for more information about NetView commands.
An Example Using &PAUSE

The following example contains a portion of a command list that illustrates how to
request information from an operator:
&BEGWRITE SUB -ENDTEXT
. ENTER ’GO’ FOLLOWED BY YOUR LAST NAME,
. FIRST NAME, AND MIDDLE INITIAL.
-ENDTEXT
* GET THE INPUT FROM THE USER
&PAUSE VARS &LAST &FIRST &MI
The example writes a message to the operator prompting for the operator’s last
name, first name, and middle initial. The command list pauses until the operator
enters a GO or RESET command. To continue processing the current command list,
the operator enters the GO command followed by the string required by the
command list.
If the operator enters the following:

GO SMITH JOHN A
The value of &LAST becomes SMITH, the value of &FIRST becomes JOHN, and
the value of &MI becomes A. These variables can then be used by other statements
in the command list.

Built-In Functions
NetView Built-in Functions

Built-in functions perform predefined operations. They are used as expressions
either in an assignment statement or in an &IF control statement. (See “&IF
Control Statement” on page 123 for information about the &IF control statement.)
In an assignment statement, the value of the user variable is set to the result of the
built-in function’s operation. Two of the NetView built-in functions, &HIER and
&MSUSEG, have REXX-format functions—HIER() and MSUSEG()—for use in
NetView REXX-only command lists.
Do not confuse built-in functions with variables of the same name. (All NetView
command list language variables are described in Chapter 4, “REXX Instructions
for NetView REXX Command Lists and Data REXX Files,” on page 37.) Although
they appear similar, they are not the same. With the exception of HIER() and
MSUSEG(), both built-in functions and NetView command list language variables
start with an ampersand (&). The difference is as follows:
v A variable is replaced by its value when the command list runs. The variable is
really just a placeholder for the value.
v A built-in function is never replaced by a value. A built-in function is an action
indicator rather than a placeholder.
These are the built-in functions you can use:

v &BITAND
v &BITOR
v &BITXOR
v &CONCAT
v &HIER
v &LENGTH
v &MSUSEG
v &NCCFID
v &NCCFSTAT
v &SUBSTR
The examples in this section use built-in functions in assignment statements.

Examples with built-in functions in the &IF control statement are in “&IF Control
Statement” on page 123.
In an &IF control statement, the result of the built-in function is used as one or
both of the compared expressions. For example, you might use the &LENGTH
built-in function to compare the lengths of two variables.
&BITAND
The &BITAND function returns a string composed of the two input strings
logically ANDed together, bit by bit. The length of the result is the length of the
longer of the two strings. If the AND operation ends when the shorter of the two
strings is exhausted, the unprocessed portion of the longer string is appended to
the partial result. If the value of both strings is null, the result is a null string.
The following syntax describes the &BITAND function:

Built-In Functions
&BITAND
&BITAND string1
string2
where:
string1
Can be either a constant or a command list variable.
string2
The following are two examples of the &BITAND operation:
&BITAND X’73’ X’27’ results in X’23’
&BITAND X’13’ X’5555’ results in X’1155’

Notes:
1. If string2 is null, the result is string1 unchanged.
2. If you specify more than two strings, message DSI186I is issued and the
command list ends. This is consistent with the equivalent REXX function.
3. If you do not specify string1, message DSI187I is issued and the command list
ends. This is consistent with the equivalent REXX function.
&BITOR
The &BITOR function returns a string composed of the two input strings logically
ORed together, bit by bit. The length of the result is the length of the longer of the
two strings. If the OR operation ends when the shorter of the two strings is
exhausted, the unprocessed portion of the longer string is appended to the partial
result. If the value of both strings is null, the result is a null string.
The following syntax describes the &BITOR function:
&BITOR
&BITOR string1
string2
where:
string1
string2
The following are two examples of the &BITOR operation:
&BITOR X’15’ X’24’ results in X’35’
&BITOR X’15’ X’2456’ results in X’3556’

Notes:

Built-In Functions
2. If you specify more than one string, message DSI186I is issued and the
&BITXOR
The &BITXOR function returns a string composed of the two input strings logically
exclusive ORed together, bit by bit. The length of the result is the length of the
longer of the two strings. If the XOR operation ends when the shorter of the two
strings is exhausted, the unprocessed portion of the longer string is appended to
the partial result. If the value of both strings is null, the result is a null string.
The following syntax describes the &BITXOR function:
&BITXOR
&BITXOR string1
string2
where:
string1
string2
The following are two examples of the &BITXOR operation:
&BITXOR X’12’ X’22’ results in X’30’
&BITXOR X’1211’ X’22’ results in X’3011’

Notes:
2. If you specify more than one string, message DSI186I is issued and the
&CONCAT
The &CONCAT function concatenates the values of two variables, two constants,
or a variable and a constant to form a new value. The syntax of the &CONCAT
built-in function is:
&CONCAT
&CONCAT variable variable

constant constant
Ensure that when the two items are joined, the resulting value does not exceed the
maximum of 255 characters; higher values are truncated. If the value of both items
being joined is null, the result is null.

Built-In Functions
For example, suppose you had the following statement:
&PREFIX = SN/
&ID = 5497
&SERIAL = &CONCAT &PREFIX &ID
After processing, the user variables are set as follows:

&PREFIX SN/
&ID 5497
&SERIAL SN/5497
Note: When &CONCAT is used to concatenate two double-byte character set

(DBCS) strings, it removes adjacent shift-in (SI) and shift-out (SO) characters.
&HIER
The &HIER function provides user access to the NetView hardware monitor
hierarchy data associated with an MSU.
The &HIER syntax is:
HIER
&HIER
n
where:
n Specifies the index number (1–5) of a specific name/type pair.
Notes:
1. &HIER without n returns a resource hierarchy slightly different than that found
in BNJ146I messages. The name/type pairs look like:
aaaaaaaa1111bbbbbbbb2222....eeeeeeee5555
The letters represent the resource name and numbers represent the resource
type.
The hardware monitor defines from one to five name/type pairs. Each name is
eight characters long and each type is four characters. The names and types are
padded with blanks if necessary.
2. &HIER with n returns the name/type pair, such as aaaaaaaa1111 that
corresponds to n. If there is no name/type pair that corresponds to n, then a
null value is returned.
3. &HIER returns null under the following conditions:
v If the command list is not run by the automation table
v If the automation table was not driven by an MSU
v If the MSU does not have a hardware monitor resource hierarchy
4. You can test whether a resource is present in a resource hierarchy by using the
example NetView command list language parsing template shown in Figure 44
on page 115.
5. If a complex link exists in a resource hierarchy, there might be resource levels
that do not appear in the information returned by the &HIER function. You
must use a system schematic to determine the complete hierarchy configuration
when a complex link is present.

Built-In Functions
*
* Set up variables for search
*
&RESNAME = AAAA
&RESLN = &LENGTH &RESNAME
&SOURCE = &HIER
&SOURCLN = &LENGTH &SOURCE
*
* Check for existence of Hierarchy
*
&IF &SOURCLN = 0 &THEN -
&GOTO -NOTFOUND
*
* Parse out desired resource name with PARSEL2R
*
PARSEL2R SOURCE FIRSTSEG /&RESNAME/ LASTSEG
*
* If the last segment is non null, we found the resource name
* imbedded in the hierarchy.
*
&IF &LASTSEG = ’’ &THEN -
&GOTO -CKLAST
&GOTO -FOUNDMSG
*
* Check last segment of the hierarchy for desired resource name.
* (If the desired resource name is the last entry in the hierarchy,
* PARSEL2R will not detect it. We need to make a special check for
* the last entry.)
*
-CKLAST
*
* Trim any trailing blanks
*
-TRIMBLANK
&LASTCHAR = &SUBSTR &SOURCE &SOURCLN 1
&IF &LASTCHAR ¬= ’ ’ &THEN -
&GOTO -OUTTRIM
&SOURCLN = &SOURCLN - 1
&IF &SOURCLN > 0 &THEN -
&GOTO -TRIMBLANK
-OUTTRIM
*
Figure 44. Example of a &HIER Parsing Template (Part 1 of 2)

Built-In Functions
&IF &SOURCLN < &RESLN &THEN -

&GOTO -NOTFOUND
&INDEX = &SOURCLN - &RESLN
&INDEX = &INDEX + 1
&LASTENT = &SUBSTR &SOURCE &INDEX &RESLN
&IF &LASTENT = &RESNAME &THEN -
&GOTO -FOUNDMSG
&GOTO -NOTFOUND
*
* Issue found message
*
-FOUNDMSG
&WRITE THE RESOURCE &RESNAME EXISTS IN THE HIERARCHY
&GOTO -LAST
*
* Issue not found message
*
-NOTFOUND
&WRITE THE RESOURCE &RESNAME DOES NOT EXIST IN THE HIERARCHY
*
* Exit
*
-LAST
&EXIT
Figure 44. Example of a &HIER Parsing Template (Part 2 of 2)
&LENGTH
The &LENGTH function returns the length of a variable or a constant. The syntax
of &LENGTH is:
&LENGTH
&LENGTH variable
constant
The length of the variable value or constant is returned. If the variable is null or
the constant is a null string, the value returned is 0.
The following is an example of how to use &LENGTH. Suppose you called

command list SAMP by entering SAMP LU2525. Assume the name of the hardcopy
printer (&HCOPY) control variable is HC55.
SAMP CLIST
&HCLENGTH = &LENGTH &HCOPY
&RESLEN = &LENGTH &1
After processing, the variable settings are:

&HCOPY HC55
&HCLENGTH
4
&1 LU25257
&RESLEN 6
User variable &HCLENGTH is set to the length of the hardcopy device name. The
hardcopy device is HC55. HC55 has four characters, so &HCLENGTH becomes 4.
&RESLEN becomes the length of the first parameter variable. The first parameter
variable is LU2525, so &RESLEN becomes 6.
Built-In Functions
&MSUSEG
The &MSUSEG function provides the parsing capability needed to extract
information from a management services unit (MSU) or other similarly architected
pieces of data. Use this function in a command list that is called by the NetView
automation table or an LU6.2 application.
The &MSUSEG syntax is:
&MSUSEG
.
(1)
&MSUSEG id
H (occ) 1
,
byte ,length
where:
byte
The byte position into the lowest ID specified in id, counting from 1 in
decimal. Position 1 is the first length byte in the header of the lowest ID. The
header is composed of one or two length bytes followed by the 1- or 2-byte ID.
This entry is optional. The default is 1.
H Is inserted if the first ID is to be obtained from the next higher level
multiple-domain support message unit (MDS-MU) as opposed to the
NMVT/control point management services unit (CP-MSU) level. You can code
the H in uppercase or lowercase. You can place H inside or outside of the
quotation marks when quotation marks are coded.
id Is the 2- or 4-character representation of 1- or 2-byte hexadecimal ID of GDS,
major vector (MV), subvector, subfield, or sub-subfield. The hexadecimal
characters (0–9, A–F, a–f) can be mixed case. The first ID is required; additional
IDs are optional.
length
Is the number of bytes in decimal to be returned from the lowest ID specified
in id and starting at the byte position. This entry is optional. The default is
equal to the remainder of the lowest id specified, and starting at the byte
position.
occ
The occurrence number, counting from one (1) in decimal. You can use an
asterisk (*) to specify the first occurrence found. This entry is optional at every
level. The default is 1.
. The period establishes a hierarchy of IDs. Thus, the vector ID specified on the
right side of the period is contained within the vector specified on the left side.
Notes:
1. You can use blanks as delimiters between operands, but blanks do not act as
place holders. For example, if you code a variable for the byte and the value of
the variable is null and you used a blank as a delimiter, the length is considered
to be the byte operand.

Built-In Functions
2. If the location is not found, or if the command list containing the &MSUSEG
function was not processed by an automation table statement because of an
MSU, or if the function was not driven by an MSU, then the value of the
&MSUSEG function is null.
3. If you do not specify a byte position, the data returned includes the 1- or 2-byte
length followed by the 1-or 2-byte ID of the lowest ID specified in id.
4. If the byte position is beyond the end of the location, a null value is returned.
5. If the specified length is longer than what remains at the location specified,
whatever remains at the location is returned.
For more information about the automation table, refer to the IBM Tivoli NetView
for z/OS Automation Guide. For more information about vector definitions, refer to
the SNA library. For more LU6.2 and MSU information, refer to the IBM Tivoli
NetView for z/OS Application Programmer’s Guide.
&NCCFID
| The &NCCFID function returns the NetView domain identifier of a domain with
| which you can establish a cross-domain session. The domains with which you can
| establish cross-domain sessions are defined by the DOMAINS statement of your
| operator profile. However, if your profile specifies AUTH CTL=GLOBAL, you can
| establish cross-domain sessions with the domains specified by the RRD statements
| in CNMSTYLE or its included members. If you do not specify DOMAINS or
| CTL=GLOBAL in the operator profile, you receive an error message when using
| this function.
For more information about the domains and RRD statements, refer to the IBM
The syntax of NCCFID is:
&NCCFID
&NCCFID number
where:
number
Is either a number or a variable that becomes a number. The largest number
permitted is the value of &NCCFCNT, the control variable that shows the total
number of cross-domain sessions this operator can start.
The command list can use &NCCFID to automatically start or stop a cross-domain
session.
The following is an example of how to use &NCCFID:

&DOM1 = &NCCFID 1
&DOM2 = &NCCFID 2
&DOM3 = &NCCFID 3
START DOMAIN=&DOM1
START DOMAIN=&DOM2
START DOMAIN=&DOM3
Assume your operator profile defines three domains with which you can establish
cross-domain sessions:
1 ALPHA

Built-In Functions
2 BETA
3 GAMMA

&DOM1 ALPHA
&DOM2 BETA
&DOM3 GAMMA
The three domains are then started with the NetView START command.
In this example, the operator must know there are three domains that can be
started. You can also use the &IF control statement to test &NCCFCNT to find the
number of domains and start them.
&NCCFSTAT
The &NCCFSTAT function returns a value indicating whether you have an active
cross-domain session with the specified domain. The syntax of &NCCFSTAT is:
&NCCFSTAT
&NCCFSTAT domain
where:
domain
Is either a domain name or a variable that becomes a domain name.
The function call is replaced by the characters ACT if the operator has an active
cross-domain session with the domain. The function call is replaced by the
characters INACT if the operator does not have an active cross-domain session
with the domain.
For example, you can write a command list to check the status of a domain and
start that domain if it is not active. Assume you activated the STARTEM command
list in the following example by entering STARTEM NCCFA.
STARTEM CLIST
&CONTROL ERR
&STATUS = &NCCFSTAT &1
&IF &STATUS = INACT &THEN START DOMAIN=&1
&IF &STATUS = ACT &THEN &WRITE DOMAIN &1 IS ALREADY ACTIVE
After processing, the variables are set as follows:

&1 NCCFA
&STATUS ACT|INACT
The parameter variable &1 is set to NCCFA, and the status of domain NCCFA is
checked. If you have an active cross-domain session with NCCFA, &STATUS is set
to ACT. If not, &STATUS is set to INACT. The &IF statement tests whether
&STATUS is set to ACT or INACT (for more information, see “&IF Control
Statement” on page 123).
If NCCFA is inactive, the command list starts it. If NCCFA is active, you receive
the following message:
DOMAIN NCCFA IS ALREADY ACTIVE

Built-In Functions
&SUBSTR
The &SUBSTR function returns the specified portion of an input variable by
parsing the variable, starting at position start for length characters. The syntax of
&SUBSTR is:
&SUBSTR
&SUBSTR variable start

length
where:
length
The number of characters to parse, beginning with the specified start position.
If no length is specified, the parsing is from the start to the end of the variable.
start
Is the starting position of the parsing operation within the variable.
variable
Is the variable to be parsed.
For example, suppose you have the following statements:
&HOLD = ACF/VTAM
&FIRST = &SUBSTR &HOLD 1 3
&SECOND = &SUBSTR &HOLD 5 4
&THIRD = &SUBSTR &HOLD 6

&HOLD ACF/VTAM
&FIRST ACF
&SECOND VTAM
&THIRD TAM
The first line of the previous example sets the value of variable &HOLD to
ACF/VTAM. In the next line, &SUBSTR starts at the first character of &HOLD (the
letter A) and moves three characters to the right (to the character F). The letters
ACF become the value of the variable &FIRST. In the next line, &SUBSTR starts at
the fifth character of &HOLD (the letter V) and goes for a length of four (to the
character M). The letters VTAM are put into variable &SECOND. In the last line,
&SUBSTR starts at the sixth character of &HOLD (the character T) but does not
specify a length. &THIRD is therefore TAM, the value of &HOLD from the letter T
through the end of the variable (M). The starting positions are determined as
shown:
1 2 3 4 5 6 7 8
A C F / V T A M
Note: The first starting position is 1, the second is 2, and so on. Zero is not a valid
position. Because the largest variable value is 255 characters, it is not valid
to have a starting point greater than 255.
You do not have to specify a length. If the length is not specified, the remainder of
the string to the right beginning with the starting position becomes the substring.
NetView never pads substrings with blanks. If you specify a length that is too

Built-In Functions
long, NetView assumes no length was specified and uses the entire string
beginning at the starting position. If the length is 0, or the starting position is
beyond the variable length, the result of &SUBSTR is null.
Figure 45 shows how you can use a substring of the &APPLID control variable to
determine the name of the domain running the command list:
GETDOMID CLIST
&CONTROL ERR
* DETERMINE THE LENGTH OF THE APPL ID
&LENAPPL = &LENGTH &APPLID
* SUBTRACT 3 TO GET THE LENGTH OF THE DOMAIN ID
&LENAPPL = &LENAPPL - 3
* START AT COLUMN 1 OF NEW LENAPPL FOR LENGTH OF DOMAIN ID
* THE VALUE OF &DOMAIN WILL BE THE DOMAIN ID
&DOMAIN = &SUBSTR &APPLID 1 &LENAPPL
* &DOMAIN NOW CONTAINS THE DOMAIN ID
Figure 45. Using &APPLID to Determine the Domain Name
When using double-byte characters along with Roman characters (A–Z; a–z), the
&SUBSTR function adjusts the variable as follows:
Start byte = shift-out character
No adjustment
Start byte = shift-in character
Replace with blank
Start byte = first half of double-byte
Replace with blank and shift-out character
Start byte = second half of double-byte
Replace with shift-out character
Last byte = shift-out character
Replace with blank
Last byte = shift-in character
No adjustment
Last byte = first half of double-byte
Replace with shift-in character
Last byte = second half of double-byte
Replace with shift-in character and blank.
The following is an example of the &SUBSTR statement used on a double-byte

character and Latin character string:
&DBCS = ’AB<D1D2D3>EFG’
where:
v A, B, E, F, G are Latin characters.
v < (X'0E') represents the shift-out control character.
v > (X'0F') is the shift-in control character.
v D1, D2, D3 are double-byte characters.
Using this value, &SUBSTR works as follows:

&FIRST= &SUBSTR &DBCS 1 3
= ’AB<’ (interim string)
= ’AB ’ (recovery string)

Built-In Functions
&SECOND = &SUBSTR &DBCS 3 5

= ’<D1D2’ (interim string)
= ’<D1> ’ (recovery string)
&THIRD = &SUBSTR &DBCS 4 5

= ’D1D2D’ (interim string)
= ’ <D2D’ (interim string)
= ’ <D2>’ (recovery string)
Note: The DBCS delimiters are 1 byte long; the DBCS codes are 2 bytes long.

Appendix B. NetView Command List Language Branching
This chapter describes the conditional and unconditional branching statements in
NetView command list language.
v The &IF statement causes a conditional branch based on logical or arithmetical
comparisons. The result of a test or comparison in an &IF statement determines
the alternative to perform. Conditional processing statements give you the
flexibility to code if-then and loop structures.
v The &GOTO statement causes unconditional branching.
v The &EXIT statement lets you code logical exit points within a command list.
v The &WAIT statement suspends processing and waits for the completion of an
event.
&IF Control Statement

The &IF control statement tests a condition and performs processing based on the
results of the test. The condition consists of two expressions and a logical or
arithmetical operator.
If the condition is true, the &THEN clause is processed. If the condition is false,
processing continues at the statement following the &IF control statement. The
syntax of the &IF control statement is:
&IF&THEN
&IF expression_1 = expression_2 &THEN statement

EQ
¬=
NE
<
LT
>
GT
<=
LE
>=
GE
¬>
NG
¬<
NL
where:
= or EQ
Equal
expression_1
Is any expression that can be used in an assignment statement. It can be a
constant, a variable, an arithmetic operation, or a built-in function. For more
information, see “Assignment Statements” on page 102.

NetView Command List Language Branching
expression_2
Is the second term of comparison. It follows the same rules as expression_1.
> or GT
Greater than
>= or GE
Greater than or equal
< or LT
Less than
<= or LE
Less than or equal
¬= or NE
Not equal
¬> or NG
Not greater than
¬< or NL
Not less than
Note: You can use either the symbol code or the 2-character letter code. Both
have the same meaning.
&THEN
Separates the comparison from the command list statement that is processed if
the condition is true. You must code &THEN in every &IF statement.
Note: Coding the ampersand (&) with THEN identifies the word as part of the
control statement.
statement
Is the command list statement that is processed if the comparison is true,
otherwise it is ignored. The statement can be any NetView command list
language statement.
Variables coded in the comparison expressions are replaced by their values before
the comparison is checked. You can use two single quotation marks with no space
('') to test whether a variable is null. For example, the comparison &1 = '' is true
when &1 is null.
The following example shows comparisons:

5 = &A
&1 = ’
2 + 2 NE &ANSWER
&PARMCNT LE 5
If a variable used in an arithmetic expression can be equal to null, then the

following syntax should be used:
7 > 3 + 0&1
In this example, the zero (0)&1 is evaluated as zero (0) because &1 is null.
Therefore, the expression 3 + 0 is compared to 7. If &1 was equal to 9, the
expression 3 + 09 would be compared to 7.
The following five examples use the &IF control statement:

&IF &APPLID = NCCFA001 &THEN &USERVAR = 10
&IF &NCCFID = NCCFA &THEN &GOTO -PROC2
&IF &1 = LU200 &THEN VARY NET,ACT,ID=&1
&IF &SUBSTR &DATE 1 5 = ’01/01’ &THEN &WRITE HAPPY HOLIDAY
&IF &A = X'41' &THEN &GOTO -PROC1
&GOTO Control Statement

The &GOTO statement unconditionally transfers control to another part of the
command list. &GOTO lets you rerun statements or jump ahead to a statement of
the command list. A statement label identifies the target or destination statement.
When you use both &IF and &GOTO, you can test for various conditions and go
to different parts of the command list, depending on the results. The syntax of the
&GOTO control statement is:
&GOTO
&GOTO -label
where:
-label
Identifies the target statement in this command list where processing
continues.
When the NetView program interprets the &GOTO statement, it searches the
command list for a statement starting with this same label. The NetView program
transfers control to that statement and continues the command list processing. The
statement identified by the label can be before or after the &GOTO statement.
You can code a variable for your label as long as the variable is replaced by a
value before the NetView program processes the &GOTO statement. See “Labels”
on page 94 for more information about labels.
&EXIT Control Statement

When the command list reaches the &EXIT control statement, the command list
processing ends.
You can use &EXIT with &IF to check the command list and exit if there is an
error. You can use &EXIT with &GOTO to control the flow of the command list.
The syntax of the &EXIT control statement is:
&EXIT
&EXIT
number
where:
Appendix B. NetView Command List Language Branching 125

number
Is an error return code. It can be equal to -1, 0, or any positive number up to
2147483647. To debug potential problems in nested command lists, code a
return code on &EXIT.
The return code you set on the &EXIT control statement is placed in the
&RETCODE control variable. The calling command list can test &RETCODE and
take action based on the return code. See “Command List Information” on page 40
for more information about &RETCODE.
You can define meanings for the positive numbers. If you code a nonzero return
code on the &EXIT statement, and if &CONTROL ERR is in effect, the command
list command that generated the nonzero return code is echoed on the panel.
When a command list returns a -1, that command list, and all command lists in the
nested chain, end. If you do not code a return code on &EXIT, or if the command
list ends when the last line is processed and there is no &EXIT statement, a zero
return code is set.
Figure 46 shows an example command list named STOPTAF that uses the
ENDSESS command to stop all terminal access facility sessions. The command list
checks for errors. To start the command list, enter STOPTAF or STOPTAF ALL. If
you forget what the command list does or forget what to enter, use STOPTAF ? to
get help.
STOPTAF CLIST
&CONTROL ERR
* IF USER ENTERS STOPTAF ?, GO TO HELP SECTION
&IF &1 EQ ? &THEN &GOTO -HELP
* IF NO PARAMETERS, GO TO COMMAND
&IF &1 EQ '' &THEN &GOTO -CMD
* IF PARAMETER IS ALL, GO TO COMMAND. ELSE PRINT ERROR MSG
&IF &1 NE ALL &THEN &GOTO -ERROR
-CMD
ENDSESS OPCTL,ALL
ENDSESS FLSCN,ALL
&EXIT
-ERROR
&WRITE YOU ENTERED: STOPTAF &PARMSTR WHICH IS NOT CORRECT
-HELP
&BEGWRITE -END
ENTER: STOPTAF TO STOP ALL TERMINAL ACCESS FACILITY SESSIONS
-END
&EXIT 4
Figure 46. Example of a CLIST to Stop TAF Sessions
If you enter STOPTAF or STOPTAF ALL, only the results of the two ENDSESS
commands are displayed.
If you enter STOPTAF FLSCN, the following message is displayed:

YOU ENTERED: STOPTAF FLSCN WHICH IS NOT CORRECT
If you enter STOPTAF ?, the following message is displayed:


&WAIT Control Statement

Sometimes you want a command list to wait for a specific event or message. With
the &WAIT control statement, you define what event causes the command list to
resume processing. The command list can wait for any message with a 1- to
10-character message identifier.
Notes:
1. You cannot use &WAIT when operating under the primary POI task (PPT), or
when using common operations services (COS) commands. See “Primary POI
Task Restrictions” on page 12 for more information using &WAIT under the
PPT. For additional information about using &WAIT with common operations
services commands, see Appendix D, “Common Operations Services
Commands,” on page 149.
2. NetView pipelines, called with the PIPE command, provide both extended
function and reduced complexity for the automation of message handling. The
PIPE command is therefore a recommended alternative to the &WAIT control
statement. For information about NetView pipelines, refer to the IBM Tivoli
NetView for z/OS Programming: Pipes book.
If you use &WAIT in an automation task command list, be sure to specify a

reasonable time-out value. For instructions about coding a time-out event, see “The
Event=-Label Pair” on page 129.
If the trapped message satisfies the wait condition, processing of the waiting
command procedure resumes. If you do not suppress the message at this point, it
continues with the message flow. If you suppress the message, however, the
NetView program marks it for deletion. In this case, automation-table processing
does not occur and the NetView program does not display or log the message.
&WAIT does the following in a command list:

v It causes the NetView program to monitor the operator station task (OST) for
specific messages and takes action if the message arrives. For example, the
command list issues a VTAM command to activate a resource. When VTAM
sends the message saying the resource is active, &WAIT initiates a specific action
based on the successful activation of the resource.
v It initiates a specific action if a message does not arrive in a specified period of
time. For example, for your installation, you might want to display resources if
the activation message does not arrive within 5 minutes.
Therefore, you can use &WAIT in the following applications:
v The command list starts a session with an application program, such as IMS/VS,
or another NetView domain. The &WAIT causes the NetView program to
monitor the OST for messages indicating the session is started. This satisfies the
&WAIT condition. When the &WAIT condition is fulfilled, the command list
resumes processing and sends the logon and other information.
v The command list issues requests for status information from VTAM, and then
processes or reformats this information before sending it to the NetView
operator.
&WAIT and &PAUSE work differently. With &PAUSE, the command list does not
continue until the operator enters the GO command. Operands on the GO
command are used in the command list. However, because &WAIT causes the
command list to wait for a specific event or events, GO is used to resume the
command list only if the event never occurs. When a command list is in a wait

state, the NetView program ignores operands on the GO command. RESET,

STACK, and UNSTACK work the same way for &WAIT and &PAUSE.
Coding an &WAIT Control Statement

You can code an &WAIT statement in several ways. This section describes the basic
format. “Customizing the &WAIT Statement” on page 135 describes ways to
customize &WAIT.
When the command list begins processing a &WAIT control statement, NetView
displays the letter W in the upper right corner of the panel if the panel is refreshed
because a message is received or the ENTER key is pressed. This W notifies the
operator that a command list process is in a wait state. Wait state means the
command list has halted its processing and is waiting for a specific message or
group of messages. When the specific message arrives, the control variables and
the parameter variables are set to their current values. The syntax of the &WAIT
control statement is:
&WAIT
&WAIT event=−label
'command'
where:
'command'
Is any command or command list that you can issue from the NetView
program. This command is optional. It is usually the command from which the
command list is waiting for messages. For example, if you want the command
list to wait for a successful session startup, the entire BGNSESS command is
coded between single quotation marks. Be sure to code command list
continuation characters before the event=-label pairs. The command is run as
soon as it is reached in the command list.
You can code one of the NetView timer commands, AT®, EVERY, or AFTER, in
the &WAIT statement. If the scheduled command is a command list, it cannot
run until either the current command list is complete or the STACK command
is entered.
event=-label
Is an event=-label pair. You can code as many of these pairs as you want on an
&WAIT statement, up to the limit of 255 characters. The event is usually a
message for which the command list is waiting. The event can be a trigger that
ends the wait state before the message arrives. The &WAIT statement causes
the NetView program to scan all messages sent to the operator. If a message
matches one of the events coded, the command list goes to the line with the
specified label and continues processing from the labeled statement. For more
information about the types of events that can satisfy an &WAIT, see “The
Event=-Label Pair” on page 129.
When the NetView program receives the message it is waiting for, the message is
displayed on the operator terminal, as are all NetView messages. However, in this
case, the message type is W unless the message satisfying the &WAIT originated

from a command list, in which case the message type remains C. If you do not
want the operator to see this message, see “Customizing the &WAIT Statement” on
page 135.
The NetView program checks only messages that are intended for the operator’s
screen. If you code exit routine DSIEX02A (output to the operator), the &WAIT
control statement might not set the message for matching. For example, if
DSIEX02A deletes the message, &WAIT does not get the message so a match is not
made. Because the operator does not receive the message, neither does the waiting
command list. Therefore, you should wait only for messages that are displayed on
the NetView console.
Notes:
1. When coding the &WAIT command control statement, it is important to code
an event=-label pair for message DSI210I and *NN. The DSI210I message is
returned when the command found in the command list is not authorized for
this operator, and the *NN event prevents waiting indefinitely for operator
intervention. The statements following labels should notify the operator of the
error and exit the command list.
2. The W signifying a wait state, if present, remains in the upper right corner of
the panel while this initial &WAIT command is processed. The W tells the
operator that NetView is still waiting for messages. If the operator enters GO
before this command or command list completes processing, the GO is rejected
with message DSI016I NOT IN PAUSE OR WAIT STATUS. When the command or
command list is complete, the GO is accepted. RESET ends a command list that
is in a wait state. If you enter the STACK command, the W does not remain in
the upper right corner of the panel.
3. You can code several event=-label pairs, but the first message or other condition
that matches one of the events stops the command list from waiting for more
messages. You can change this if you want to process several messages with
one &WAIT statement. See “Customizing the &WAIT Statement” on page 135.
The Event=-Label Pair

The event=-label pair on the &WAIT statement lets you pass control to a statement
with a label when one of four types of events occurs. The label is a standard label
as described in “Labels” on page 94. The label coded on the &WAIT statement can
be a variable, but you should not use parameter variables.
You can pass control to the label on an &WAIT statement by specifying an

event=-label pair. The events you can use are:
v token
v *ERROR
v *nn
v *ENDWAIT
Descriptions of the previously mentioned events are as follows:

token This event occurs when the NetView program receives a message matching
token. The token variable can be 1–10 characters that identify the first token
of the message or messages for which the command list is waiting.
Optionally, you can identify the domain of a message for which the
command list is waiting. If a domain identifier is specified, it precedes the
token and is separated from the token by a period (domainid.token). You can
also use an asterisk (*) to indicate you are specifying a partial domain
identifier or token. If you do not specify a domain identifier, the message
for which the command list is waiting can be from any domain.

The following are examples of some of the ways you can specify the
messages for which you want the command list to wait:
domainid.token
The event occurs when the NetView program receives any message
whose domain identifier matches the 1–5 character domainid and
whose first token matches token.
dom*.token
The event occurs when the NetView program receives any message
whose domain identifier matches the partial domain identifier
specified by dom* and whose first token matches token. For
example, NCCF*.DSI463I means the event occurs when a DSI463I
message is received from any domain with an identifier that starts
with NCCF (such as NCCFA or NCCFB).
*.token The event occurs when the NetView program receives any message
whose first token matches token. The message can be from any
domain.
token The event occurs when the NetView program receives any message
whose first token matches token. The message can be from any
domain.
tok* The event occurs when the NetView program receives any message
whose first token matches the partial token specified by tok*. For
example, DSI* means the event occurs when the NetView program
receives any message whose first token begins with DSI (such as
DSI463I or DSI386I).
* The event occurs when the NetView program receives any message
or other output. For example, if you code &CONTROL ALL in the
command list, every line of the command list is echoed on the
panel. These echoes satisfy the * condition, and depending on the
code in the command list, could cause a loop or other undesirable
results. Therefore, use the *=-label condition with caution.
If you specify a token that contains a special character such as a comma,

period, asterisk, or most other non-numeric and non-alphabetic characters,
use the DOMAIN.TOKEN format. Remember, however, that the NetView
program does not accept single quotation marks ('), commas (,), or blanks
when you specify a token because these characters are reserved as
NetView default delimiters. If the token contains the ampersand (&) then
&CONCAT must be used to concatenate the ampersand with the rest of
the token.
Figure 47 on page 130 shows examples of coding tokens that contain

special characters:
&WAIT DOMAIN1.*HASP=-MSG1
&WAIT DOMAIN1.=HASP=-MSG1
&X = &CONCAT & HASP
&WAIT DOMAIN1.&X=-MSG1
Figure 47. Examples of Coding Tokens with Special Characters
Multiline messages such as multiline write-to-operators (MLWTOs) are

treated as one message. Therefore, only the message identifier of the first
message in a multiline message is available to the &WAIT, and the &WAIT
statement can be satisfied only by that message identifier. Use GETMSIZE,

GETMTYPE, GETMLINE, GETMPRES, and GETMTFLG to access the other

lines of a multiline message. Refer to the these commands in the NetView
online help for more information about multiline messages and an example
of using &WAIT with multiline messages.
Notes:
1. When using a token event, messages not related to the command issued
by the &WAIT statement can be matched to the event and, depending
on the options on the &WAIT statement, can be suppressed. However,
use caution when coding * or *.* with SUPPRESS when specifying a
domain identifier or token. If the command list is suspended and the
SUPPRESS option is in effect on the &WAIT statement, any messages
the task receives are suppressed before the command list is resumed.
2. Because NetView-NetView tasks (NNTs), PPT, OSTs, and autotasks do
not process any commands or messages queued to the low priority
queue of a task that is running any command (assembler command or
HLL, REXX or NetView command list language command procedure),
only messages that are queued to the high or normal priority queue of
a waiting task are checked for matches to satisfy a wait condition.
3. Usually, messages queued to tasks through assign...copy= processing
can satisfy an outstanding &WAIT. However, a message is not sent to
the waiting task through assign...copy= processing if the message
contains a message automation table entry specifying DISPLAY(N). The
assign...copy= processing requires a displayed message, but
DISPLAY(N) specifies no display, which prevents that processing. The
message is not passed on; therefore, it cannot satisfy the &WAIT
condition.
For more information about message flow, refer to the IBM Tivoli
NetView for z/OS Automation Guide book.
*ERROR
This event occurs when the command specified on the &WAIT statement
returns a nonzero return code. If you do not code *ERROR, the NetView
program continues to wait for the messages associated with this command
even if the command ends with an error. If the NetView program is
waiting for a message that says the command was successful, the operators
running this command list are delayed until someone issues GO or RESET.
If *ERROR is satisfied, the message control variables are set as follows:
&MSGID *ERROR
&MSGORIGIN Name of domain where the command list
is running
&MSGSTR Null
&MSGCNT 0
Note: Messages associated with the command can be received before the
command returns a nonzero return code. If such a message is coded
on an event=-label pair, control is passed to the first statement whose
event has occurred.
For example, if you code the name of the &WAIT command on a
MSGID=-label pair, and you also code an *ERROR=-label pair, the NetView
program honors the MSGID=-label pair first because that event occurs first.
*nn This event occurs after nn seconds. If no other event occurs, the &WAIT
ends and control passes to the labeled statement. You can code a value
between 1 and 32767 seconds (9 hours, 6 minutes, 7 seconds). If you do not

code *nn and none of the events of the &WAIT are satisfied, &WAIT
continues until the operator enters a GO or RESET command.
*ENDWAIT
This event occurs when the operator or a command list issues a GO
command. If you do not code *ENDWAIT=-label, the GO command
continues processing with the statement following the &WAIT command.
Error Conditions
If an error condition occurs, the NetView program should be able to go to another
part of the command list and take appropriate action. Consider the types of errors
you can have and plan to handle them by coding *ERROR, *nn, and *ENDWAIT
events.
Coding Message=-Label Pairs

The order in which you code MSGID=-label pairs is important. The NetView
program scans the pairs in the order you code them, from left to right.
For example, assume you code the following statement:
&WAIT IST*=-ALL,IST123I=-SPECIAL
When the NetView program receives IST123I, it goes to the label -ALL, not
-SPECIAL. You should code IST123I before IST*.
You can code as many events as required on one &WAIT control statement up to
255 characters. Remember to use continuation characters if the event pairs take up
more than one line. Code the message and domain identifiers in the order that you
want them processed. The NetView program scans the list from left to right until a
match is found.
Ending an &WAIT
An &WAIT statement can end in one of the following ways:
v The operator enters the GO command. Processing continues with the next
statement, unless *ENDWAIT is specified on the &WAIT statement. If
*ENDWAIT is specified, processing continues with the statement marked by the
label.
v The operator enters the RESET command. The command list and all of its nested
command lists end.
v Coding *ERROR on the &WAIT statement. If the command specified on the
&WAIT statement ends with an error, the command list continues processing at
the statement marked with the label. If you do not code *ERROR in this
situation, the &WAIT does not end until the operator enters GO or RESET.
v Coding *nn on the &WAIT statement. The command list continues processing at
the statement specified by the label if another event does not occur within nn
seconds.
v Receipt of a message matching an event=-label pair. The command list continues
processing with the statement marked with the label.
Using NetView Commands with &WAIT

When a command list written in the NetView command list language is in a pause
or wait state, operator commands that are entered can be deferred. Whether the
commands are deferred is based on the NetView DEFAULTS, OVERRIDE, and
CMD commands.

The GO, STACK, UNSTACK, and RESET commands affect the processing of
command lists in a wait state as follows:
GO Ends the wait.
If *ENDWAIT is coded, processing continues with the labeled statement.
STACK
Suspends command list processing and causes any commands that are
deferred to be processed. You can enter any command or command list for
normal processing while a command list is suspended. The &WAIT is not
suspended, and events are still matched as they occur. The command list
using &WAIT does not process messages as they occur, but, instead, after
the command list is given control again. The W does not remain in the
upper right corner of the NetView panel. The GO command is rejected
until the command list resumes processing.
UNSTACK
Resumes command list processing. The &WAIT resumes processing events
that were matched while the command list was suspended.
RESET
Ends a command list that is in a wait state, and all command lists related
to it by nesting.
Note: When processing MLWTO messages received in response to an &WAIT

control statement, use the GETMLINE, GETMSIZE, and GETMTYPE
commands. For more information about these commands, and the GO,
STACK, UNSTACK, and RESET commands, refer to the NetView online
help.
Control and Parameter Variables Used with &WAIT

The NetView program sets the values of the control variables. The following
variables are based on the receipt of a message coded on an &WAIT control
statement:
&ACTIONDL &KEY &MSGGSYID

&ACTIONMG &LINETYPE &MSGGTIME
&AREAID &MCSFLAG &MSGID
&ATTNID (VSE only) &MSGASID &MSGORIGN
&AUTOTOKE &MSGAUTH &MSGSRCNM
&CART &MSGCATTR &MSGSTR
&DESC &MSGCMISC &MSGTOKEN
&HDRMTYPE &MSGCMLVL &MSGTSTMP
&IFRAUGMT &MSGCMSGT &MSGTYP
&IFRAUIND &MSGCNT &MVSRTAIN()
&IFRAUIN3 &MSGCOJBN &NVDELID
&IFRAUI3X &MSGCPROD &PARTID (VSE only)
&IFRAUSB2 &MSGCSPLX &PRTY
&IFRAUSC2 &MSGCSYID &REPLYID
&IFRAUSDR &MSGDOMFL &ROUTCDE
&IFRAUSRB &MSGGBGPA &SESSID
&IFRAUSRC &MSGGDATE &SMSGID
&IFRAUTA1 &MSGGFGPA &SYSCONID
&IFRAUWF1 &MSGGMFLG &SYSID
&JOBNAME &MSGGMID &1–&31
&JOBNUM &MSGGSEQ

The NetView program changes the values of the &1–&31 parameter variables to
reflect the text of the message. Each parameter variable is set to a token of the
message. Tokens are delimited by commas, apostrophes, or blanks. &1 is set to the
first token following the message identifier (the token used by the &MSGID control
variable). &2 is set to the next token to the right of &1, and so on up to a
maximum of 31 variables.
For more information, see “Message Processing Information Functions” on page 48

and “MVS-Specific Message Processing Information” on page 55.
The following is an example of how the variables are set when the message
DSI008I SPAN1 NOT ACTIVE from domain DOM01 is intercepted by an &WAIT
statement:
&MSGORIGIN DOM01
&MSGID DSI008I
&MSGSTR SPAN1 NOT ACTIVE
&MSGCNT 3
&1 SPAN1
&2 NOT
&3 ACTIVE
&4–&31 NULL
Notes:
1. If the NetView program receives a multiline message, the control variables and
parameter variables are set according to the first nonblank line of the message.
Refer to the GETM commands in the NetView online help for information
about multiline messages.
2. If &1–&31 are given values when the command list runs, save the parameter
variables in user variables before calling the &WAIT control statement. This
procedure lets you use the original values after &WAIT changes them.
3. After issuing an &WAIT control statement, save the values of the control
variables in user variables before issuing another &WAIT control statement.
This procedure lets you use the values after another &WAIT changes them.
4. If you are using &WAIT CONTWAIT, be careful when using the control
variable &MSGID before the &WAIT has ended. If &MSGID is the first
character string on an &WRITE or &BEGWRITE, the output might be
suppressed or cause the command list to loop. If the &WAIT SUPPRESS option
is in effect, an &WRITE or &BEGWRITE with &MSGID as the first character
string of the text matches the MSGID=-label operand of the active &WAIT.
Therefore, the text of the &WRITE or &BEGWRITE is not sent to the operator’s
screen. If an &WAIT CONTINUE statement is encountered after a
MSGID=-label is matched, and there is no other statement to end the command
list or the &WAIT, the command list loops.
Using &WAIT in Nested Command Lists

The command in the &WAIT statement can be a command list. The nested
command list can contain an &WAIT statement, too. You should be aware of the
following considerations when using &WAIT with nested command lists:
v Messages that arrive for the waiting command lists are queued until the nested
command list is finished processing.
v If you specify the same message number on &WAIT statements in both the
waiting and nested command lists, the message satisfies the &WAIT in the
nested command list.

If the nested command list ends before the message satisfies the &WAIT, the
message is queued for the waiting command list. Without the ending of the
&WAIT or the waiting command list, the message queue continues to grow and
the NetView program can run out of storage.
Customizing the &WAIT Statement

The previous sections described the simplest form of the &WAIT command, in
which the first message received that satisfies the wait is displayed on the
operator’s terminal and causes the command list to continue processing.
This section describes how to customize the &WAIT statement for more flexibility.
To customize your &WAIT statements, use the following syntax.
&WAIT
DISPLAY ENDWAIT
&WAIT
SUPPRESS CONTWAIT
or
&WAIT
&WAIT CONTINUE
where:
DISPLAY
Indicates that the message the command list is waiting for is to be displayed at
the operator’s terminal upon arrival to the NetView program. DISPLAY is the
default value.
SUPPRESS
Indicates that any messages that satisfy an &WAIT are not displayed, logged,
or automated.
CONTWAIT
Indicates that the next &WAIT event=-label statement encountered waits for
additional events until the wait is ended. CONTWAIT enables one &WAIT
statement to process more than one event. This operand is useful when you
want to retrieve more than one message from a single command, such as a
LIST command.
ENDWAIT
Sets up processing for the next event=-label pair to be processed. ENDWAIT is
the default value. ENDWAIT indicates that the wait ends after the first event
that satisfies the &WAIT. Although ENDWAIT does not end a wait already in
process, operators can still use the GO command to end the wait. The RESET
command, which ends a wait, also ends the command list.
CONTINUE
Directs the command list to continue waiting for the next event that satisfies
the original &WAIT statement. CONTINUE is used only when &WAIT
CONTWAIT is specified prior to the &WAIT event=-label. If you want the wait

to continue after event processing is finished, code &WAIT CONTINUE. It is

similar to branching back into the &WAIT statement.
Notes:
1. If neither DISPLAY nor SUPPRESS is specified, then either ENDWAIT or
CONTWAIT must be specified.
2. DISPLAY is the default only if ENDWAIT or CONTWAIT is specified and
SUPPRESS is not specified. See Table 18 for valid option combinations.
3. The DISPLAY and SUPPRESS options can be changed at any point in a
command list. Once messages are suppressed, you must code another &WAIT
statement with the DISPLAY operand to begin displaying messages again.
4. &WAIT SUPPRESS overrides DISPLAY because the command list has been
given the message and does not issue an echo.
5. When SUPPRESS is in effect, you do not know whether messages are received.
Therefore, all of the messages might not be processed when an operator issues
a GO or RESET command to end an &WAIT.
6. If neither ENDWAIT nor CONTWAIT is specified, then either DISPLAY or
SUPPRESS must be specified.
7. ENDWAIT is the default only if DISPLAY or SUPPRESS is specified and
CONTWAIT is not specified. See Table 18 on page 136 for valid option
combinations.
8. The ENDWAIT and CONTWAIT options can be changed at any point in a
command list. Once CONTWAIT starts, you must code another &WAIT
statement with the ENDWAIT operand to return to the default value.
Table 18. &WAIT Customization Options Matrix.
S = Specified operand
v = Default called
DISPLAY SUPPRESS ENDWAIT CONTWAIT

S S
S S
S S
S S
v S
v S
S v
S v
Note: At least one option must be specified. Defaults are not called if no option is
specified.
The operands of this format are optional and can be coded in any order. However,
they cannot be coded on the &WAIT event=-label statement. The &WAIT statement
does not put the command list into a wait state. Instead, it indicates how the
command list processes the next &WAIT event=-label control statement.
If you update this statement using SUPPRESS, CONTWAIT, or CONTINUE, the

new settings remain in effect for the rest of the &WAIT statements in the command
list, including an &WAIT currently in process. To reinstate the initial settings, you
must code another &WAIT statement with the appropriate operands. If you

activate a nested command list, the default settings are in effect for that command
list unless an &WAIT statement is coded for the nested command list.
Ending &WAIT If CONTWAIT Is in Effect

“Ending an &WAIT” on page 132 describes ways to end a wait when a command
list is waiting for only one event. When the command list is waiting to match more
than one event, you can end the wait in one of the following ways:
v By entering the GO command at the terminal.
If an &WAIT CONTINUE was the last &WAIT statement encountered,
processing continues with the next command list statement following the
&WAIT CONTINUE statement. If the *ENDWAIT event is coded, processing
continues at the label statement. If no event=-label match occurred, processing
continues with the line following the &WAIT statement.
v By coding the GO command in the command list statement that follows an
&WAIT ENDWAIT statement.
If the *ENDWAIT event is coded, processing continues at the label statement. If
no event=-label match occurred, processing continues with the line following the
GO command.
v By coding *ERROR as the event on the &WAIT statement.
If the command specified on the &WAIT statement ends with an error, the
command list continues processing at the statement specified with a label. The
&WAIT does not end unless an error occurs. However, if there is an error in the
command list and you do not have *ERROR coded, the wait might not end
without intervention.
v By coding *nn on the &WAIT statement.
The command list continues processing at the statement specified with a label if
the event does not occur within nn seconds.
v By coding *ENDWAIT on the &WAIT statement.
The command list continues processing at the statement specified with the label
when the operator enters the GO command.
v By coding &EXIT following a label.
The command list ends normally.
v By entering the RESET command.
The command list, including the command list that initiated it, ends.
Note: Because &WAIT CONTWAIT queues NetView messages, you should also
code &WAIT CONTINUE to receive these queued messages. If you code
&WAIT CONTWAIT with SUPPRESS and end the wait, you might lose
some messages.
Suggestions for Coding &WAIT

For the best performance, use the &WAIT [ENDWAIT|CONTWAIT] options in the
following way:
1. Set up options for the &WAIT event=-label statement by coding &WAIT with
CONTWAIT, SUPPRESS, or their defaults.
2. Enter an &WAIT state by using an &WAIT event=-label statement.
v If you specify &WAIT ENDWAIT before the &WAIT event=-label statement, or
if &WAIT ENDWAIT is in effect by default, the first matched event ends the
wait, and command list processing continues. See “Ending an &WAIT” on
page 132.

v If you specify &WAIT CONTWAIT, the receipt of the first event does not end
the &WAIT unless this event is specified as shown in “Ending &WAIT If
CONTWAIT Is in Effect” on page 137. The command list goes to the label
specified for the event and continues processing.
To complete this section of the command list, do one of the following:
– Continue the wait by coding &WAIT CONTINUE.
– Specify that the next event is the last event of this wait by coding &WAIT
ENDWAIT and then &WAIT CONTINUE.
– End the wait by coding the &WAIT ENDWAIT statement and GO
command in the command list.
– End the command list by coding &EXIT.
Sample Using &WAIT

Figure 48 shows the use of &WAIT to wait for one message. The command list is
named ACTONE, and it issues a VTAM command to activate a logical unit. The
command list traps the messages responding to the activate command, reformats
the messages, and writes them to the operator’s screen.
&CONTROL ERR
* ACTONE COMMAND LIST
* THIS COMMAND LIST ISSUES A VTAM "V NET,ACT" COMMAND, TRAPS ITS
* MESSAGES AND REFORMATS THEM.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* IF THERE IS NO INPUT PARAMETER, ASK FOR ONE
&IF &1 = '' &THEN &GOTO -BADIN
* SAVE THE INPUT PARAMETER
&LU = &1
* END THE WAIT WITH THE FIRST MESSAGE AND DO NOT DISPLAY THE
* INPUT MESSAGE ON THE SCREEN
&WAIT ENDWAIT SUPPRESS
* ISSUE WAIT WITH THE COMMAND
&WAIT ’V NET,ACT,ID=&LU’,IST093I=-REFORM,*ERROR=-FAIL,+
IST105I=-FAIL,*ENDWAIT=-GOIN
-REFORM
* REFORMAT MESSAGE IST093I (SUCCESSFUL) AND WRITE TO THE SCREEN
* &1 IN THE FOLLOWING LINE IS NOT THE ORIGINAL &1
&ACTIV = &1
&WRITE VTAM MESSAGE IST093I WAS RECEIVED
-REFORM
&WRITE &ACTIV IS NOW ACTIVE
&GOTO -ENDALL
-FAIL
* REFORMAT MESSAGE IST105I (UNSUCCESSFUL) AND WRITE TO THE SCREEN
&WRITE &LU COULD NOT BE ACTIVATED
&GOTO -ENDALL
-GOIN
* IF "GO" ISSUED, INDICATE THAT MESSAGES HAVE NOT BEEN RECEIVED
&WRITE "GO" INPUT COMMAND LIST ACTONE -- &LU IS NOT ACTIVE NOW
&GOTO -ENDALL
-BADIN
&WRITE RE-CALL COMMAND LIST ACTONE WITH PARAMETER OF LU TO BE ACTIVATED
-ENDALL
&WRITE COMMAND LIST ACTONE COMPLETE
&EXIT
Figure 48. Command List Issuing &WAIT for One Message
The ACTONE command list waits for one of the following messages:
IST093I modename ACTIVE
IST105I modename NODE NOW INACTIVE

Activate the command list by entering ACTONE and operand NODE1. The
operand is the name of the logical unit to be activated. This operand supplies the
value for parameter variable &1. Receipt of a message indicating success (IST093I)
or failure (IST105I) causes the wait to end because ENDWAIT was specified.
Processing continues at the specified label (-REFORM for IST093I, -FAIL for
IST105I). The awaited messages are not displayed because SUPPRESS was
specified, but any other messages are displayed.
Upon successful activation of NODE1, the message text shown in Figure 49 is

displayed on the operator’s terminal:
ACTONE NODE1
IST097I VARY ACCEPTED
VTAM MESSAGE IST093I WAS RECEIVED
NODE1 IS NOW ACTIVE
COMMAND LIST ACTONE COMPLETE
Figure 49. ACTONE NODE1 Message Text

Appendix C. NetView Command List Language Global
Variables
This chapter describes the use of global variables in the NetView command list
language. Global variables enable values to be defined, referenced, and updated by
different operators. Values are passed to a command list for updates, and the
updated values can then be referenced by other command lists. For example,
command list CLISTA can assign a value to a task global variable, &VAR1, and
then activate its nested command list, CLISTB. The nested command list, CLISTB,
can check the value assigned to &VAR1 by CLISTA, update the value, and return
control to CLISTA. The original command list, CLISTA, now has access to the
value assigned to &VAR1 by CLISTB.
The two types of global variables are task and common.
Task global variables can be defined, referenced, and updated by any command list
running under a particular task. Task global variables can only be referenced by
command lists running under the task in which the variable was defined.
Common global variables enable definition of user variables that can be referenced
by command lists running under any NetView task that supports command list
processing.
The NetView program provides two methods to access global variables:

v You can use &TGLOBAL, &CGLOBAL, and GLOBALV DEF to provide direct
reference to global variables.
v You can use the GLOBALV GET and PUT commands to copy and replace global
variable values.
Refer to the NetView online help for more information about the GLOBALV
command.
Notes:
1. Use caution when mixing &TGLOBAL, &CGLOBAL, or GLOBALV DEF with
the GLOBALV GET or PUT command. Using both methods to access global
variables of the same name within a single NetView command list language
command list is not recommended.
A direct set affects how subsequent copying and replacing are performed.
GLOBALV GETs and PUTs copy the value from one dictionary to the other.
&TGLOBAL and &CGLOBAL and GLOBALV DEFT or DEFC let you reference
the global variable and set it directly from that statement forward in the
command list. While both commands provide function, it is recommended that
you use one or the other within a single NetView command list.
2. When you create global variables, the variable can be 1 to 11 characters in
length. A-Z, 0–9, #, @, and $ are the only valid characters.
3. The value of the global variable can be 255 characters long. The maximum
number of double-byte characters between the shift-out (X'0E') and shift-in
(X'0F') control characters is 126.
4. You can give global variables a numerical value between -2147483647 and
2147483647. Numeric values outside these limits are treated as character strings.

NetView Command List Language Global Variables
Using &TGLOBAL and &CGLOBAL

You can specify more than one global variable using the &TGLOBAL and
&CGLOBAL control statements. The variable names must be delimited by a
comma or blank.
On the definition statement, do not code an & with the global variable name
except where you want variable substitution performed. Substitution occurs for
any variable with an ampersand (&). Whenever you use the global variables
(except when defining them), you must append an & to the variable name, just as
you would for user variables.
You need two &s when referencing a global variable indirectly. See “Using
Parameter Variables in a Command List” on page 97 and “Variable Substitution
Order” on page 95 for more information about indirect referencing of variables.
&TGLOBAL
A task global variable can be referenced only by command lists that run under the
same task.
Use the &TGLOBAL control statement to define any variable as a task global
variable. The syntax of the &TGLOBAL control statement follows:
&TGLOBAL
&TGLOBAL variable
This statement defines the listed variables as task global variables. The value of
any variable defined by this statement is whatever was most recently assigned to it
by another command list running under the same task. If no value was assigned,
the value is undefined or null, and any attempt to retrieve the value causes a null
value to be returned. If you do not use the &TGLOBAL statement in each
command list before a variable is referenced, that variable defaults to a local user
variable.
An example using the &TGLOBAL control statement is as follows:
&NAME = JOHN
&TGLOBAL ABC,&NAME
The first line consists of a local user variable set to the value JOHN. The second
line defines two task global variables as follows:
v ABC becomes task global variable &ABC. The value of &ABC is null because a
value was not defined.
v The value of &JOHN is null because a value has not been defined. This is an
example of indirect referencing of variables.
See “Extent of Variables When Using &TGLOBAL and &CGLOBAL” on page 145
for information about the interaction of task global variables with user variables
and common global variables.

If you specify more than one variable name on the &TGLOBAL statement, the
variable names must be delimited by commas or blanks.
The following are suggestions for using task global variables:

v The PROFILE IC can set task global variables to indicate a message suppression
level or message compression that is different for different types of operators.
Command lists driven by various messages can test these variables to determine
what information a particular operator needs.
v Any command list can set up and initialize any number of parameters for
another command list running under the same operator task. This improves
nested command list communication because task global variables can return
information from a nested command list.
&CGLOBAL
Use the &CGLOBAL control statement to define any variable as a common global
variable. The syntax of the &CGLOBAL control statement follows:
&CGLOBAL
&CGLOBAL variable
This statement defines the listed variables as common global variables. The value
of any variable defined by this statement is whatever was most recently assigned
to it by any other command list. If no value was assigned, the value is undefined
or null, and any attempt to retrieve the value causes a null value to be returned. If
you do not use the &CGLOBAL statement in each command list before a variable
is referenced, that variable defaults to a local user variable.
An example using the &CGLOBAL control statement follows:
&NAME = JOHN
&CGLOBAL ABC,&NAME
The first line consists of a local user variable set to the value JOHN. The second
line defines two common global variables:
v ABC becomes common global variable &ABC. The value of &ABC is null
because a value is not defined.
v &NAME becomes common global variable &JOHN. Because &NAME has a
value of JOHN, the &NAME on this line gets substituted as JOHN. This defines
the common global variable &JOHN. The value of &JOHN is null because a
value is not defined.
Note: If you have more than one command list running under different tasks
accessing the same global variable, the last value that the variable is set to is
the value that is set by any command list changing the variable.
For example, a command list accesses a common global variable and then
before that command list updates the variable, another command list
running under a different task accesses the variable. If both command lists
update the variable, the variable assumes the value given to it by the
command list that updates it last.
Appendix C. NetView Command List Language Global Variables 143

To prevent a common global variable from being updated by different

command lists at the same time, you can have all command lists that update
the variable run under the same task.
See “Extent of Variables When Using &TGLOBAL and &CGLOBAL” on

page 145 for information about the interaction of common global variables
with user variables and task global variables.
If you specify more than one variable name on the &CGLOBAL statement, the
variable names must be delimited by commas or blanks.
You can use the NetView-supplied command lists UPDCGLOB and SETCGLOB to
update and set common global variables. Refer to the NetView online help for
information.
You can use common global variables to maintain accurate information about the
network regardless of operators logging on and off.
You can use common global variables to keep cumulative information from
unsolicited access method messages. For example, you can use notification of a
failing resource to recover the resource. With a global variable, you can maintain a
count of the number of retries to prevent a loop.
Updating Task Global Variables Using &TGLOBAL

The following are two examples of command lists. The first command list, CLIST1,
calls the nested command list UPDT1. The CLIST1 and UPDT1 command lists
show how to define, reference, and update a task global variable.
* THIS STATEMENT DEFINES SYSVAR1 AS A TASK GLOBAL VARIABLE.

&TGLOBAL SYSVAR1
* THIS ASSIGNMENT STATEMENT GIVES THE TASK GLOBAL
* VARIABLE, "SYSVAR1", A VALUE OF 5.
&SYSVAR1 = 5
* THIS STATEMENT CALLS A NESTED COMMAND LIST NAMED UPDT1.
* SYSVAR1 IS A PARAMETER THAT IS PASSED TO COMMAND LIST UPDT1.
UPDT1 SYSVAR1
* THIS STATEMENT WILL WRITE VALUE OF SYSVAR1.
&WRITE SYSVAR1 = &SYSVAR1
&EXIT
Figure 50. CLIST1 Command List to Define, Update, and Reference Task Global Variables
CLIST1 in Figure 50 defines a task global variable, SYSVAR1. The value of the task
global variable SYSVAR1 returns a null value until a value is assigned using the
assignment statement, &SYSVAR1 = 5. CLIST1 activates a nested command list
named UPDT1.

* THIS STATEMENT DEFINES &1 AS A TASK GLOBAL VARIABLE.

* &1 IS SET TO THE VALUE OF THE POSITIONAL PARAMETER
* SYSVAR1, WHICH ON THE FIRST PASS IN THIS CASE IS 5.
&TGLOBAL &1
* THIS STATEMENT TESTS FOR A NULL VALUE AND INITIALIZES
* THE TASK GLOBAL VARIABLE PASSED AS &1 TO A VALUE OF
* 0 IF THE VALUE RETURNED WAS NULL.
* THE TASK GLOBAL VARIABLE PASSED AS &1 IS REFERENCED
* AS &&1. THE VALUE OF &&1 IS EQUAL TO THE VALUE OF SYSVAR1,
* WHICH WAS PASSED TO COMMAND LIST UPDATE FROM CLIST1.
&IF &&1 EQ '' &THEN &&1 = 0
* THIS STATEMENT UPDATES THE TASK GLOBAL VARIABLE, &&1,
* BY AN INCREMENT OF 1.
* THIS UPDATED VALUE OF &&1 PASSED BACK TO CLIST1
* AS TASK VARIABLE &SYSVAR1.
&&1 = &&1 + 1
&EXIT
Figure 51. UPDT1 Command List to Update Task Global Variables
UPDT1 in Figure 51 on page 145 redefines the value stored in task global variable
&1. Task global variable &1 gets its original value from SYSVAR1, which was the
first (and only) variable passed to UPDT1 when it was called by CLIST1. Because
the NetView program scans variables from right to left, the &1 part of &&1 is
evaluated first, and the value of &1 is equal to the value of SYSVAR1. The value of
the task global variable is referenced as &SYSVAR1. The initial value of &SYSVAR1
is 5, and then &SYSVAR1 is incremented by 1 using the &&1 = &&1 + 1 statement.
(&SYSVAR1 = &SYSVAR1 + 1 after it is evaluated by the NetView program.)
The updated value is available as a task global variable &SYSVAR1 in CLIST1. The
&WRITE SYSVAR1 = &SYSVAR1 statement displays the updated value of the
&SYSVAR1 task global variable.
Extent of Variables When Using &TGLOBAL and &CGLOBAL

If you define a global variable with the same name as a local variable, the value of
the local variable is lost. The global variable does not receive the value of the local
variable. The value of the global variable is null until a value is assigned.
If a command list defines a common global variable after the task global variable is
defined and has the same name as a task global variable, the value of the task
global variable remains unchanged. However, this command list can no longer
access the value of the task global variable unless you redefine the variable using
&TGLOBAL.
If a command list defines a task global variable after the common global variable is
defined with the same name as a common global variable, the value of the
common global variable remains unchanged. However, this command list can no
longer access the value of the common global variable unless you redefine the
variable using &CGLOBAL.
GLOBVAR1, Figure 52 on page 146, illustrates the extent of user variables, task
global variables, and common global variables within individual command lists
and command lists running under different tasks. This command list gives you
examples of the following variable manipulations:
v Assigning values to user variables
v Defining task global variables
v Defining common global variables
v Setting values for common global variables

v Changing common global to task global variables.
The following is an example of a command list containing global variables. In the

example, the values of the variables are shown in parentheses.
&CONTROL ERR
*** CLIST NAME: GLOBVAR1
*** ASSIGN VALUES TO SEVERAL USER VARIABLES AND PRINT THEIR VALUES
******************************************************************
&OPER = OPER1
&VTLV = VT33
&DOM1 = CNM01002
CLEAR
&BEGWRITE SUB -ENDLOCAL
FROM GLOBVAR1: AFTER LOCAL VARIABLES ASSIGNED
VARIABLE VARIABLE VARIABLE
TYPE NAME VALUE
======== ======== ========
LOCAL OPER &OPER (OPER1)
LOCAL VTLV &VTLV (VT33)
LOCAL DOM1 &DOM1 (CNM01002)
-ENDLOCAL
*
*** DEFINE TASK GLOBAL VARIABLES
********************************
&TGLOBAL OPER VTLV CNT
&BEGWRITE SUB -ENDTG1
FROM GLOBVAR1: AFTER TGLOBAL VARIABLES DEFINED
TYPE NAME VALUE
======== ======== ========
TASK OPER &OPER (NULL)
TASK VTLV &VTLV (NULL)
TASK CNT &CNT (NULL)
NOTE THAT THE VALUES ASSIGNED TO OPER AND VTLV

HAVE BEEN LOST AS THEY ARE NO LONGER LOCAL
VARIABLES AND THE TASK GLOBAL VARIABLES HAVE NOT
BEEN ASSIGNED YET.
-ENDTG1
Figure 52. GLOBVAR1 Example Showing Extent of Global Variables (Part 1 of 3)

*
*** ASSIGN VALUES TO THE TASK GLOBAL VARIABLES
**********************************************
&OPER = OPER2
&VTLV = VT33
&CNT = 3
FROM GLOBVAR1: AFTER VALUES ASSIGNED TO TGLOBAL VARIABLES
TYPE NAME VALUE
======== ======== ========
TASK OPER &OPER (OPER2)
TASK VTLV &VTLV (VT33)
TASK CNT &CNT (3)
-ENDTG2
*
*** DEFINE COMMON GLOBAL VARIABLES
**********************************
&CGLOBAL OPER VTLV VAL
FROM GLOBVAR1: AFTER CGLOBAL VARIABLES DEFINED
TYPE NAME VALUE
======== ======== ========
TASK CNT &CNT (3)
COMMON OPER &OPER (NULL)
COMMON VTLV &VTLV (NULL)
COMMON VAL &VAL (NULL)
NOTE THAT THE VALUES ASSIGNED TO TASK GLOBAL

VARIABLES OPER AND VTLV HAVE BEEN REPLACED BY
COMMON GLOBAL VARIABLES OPER AND VTLV. THESE ARE
NULL AS NO VALUE HAS BEEN ASSIGNED TO THEM YET.
-ENDTG3

*
*** ASSIGN VALUES TO COMMON GLOBAL VARIABLES
********************************************
&OPER = OPER3
&VTLV = VT32
&VAL = HEX
FROM GLOBVAR1: AFTER CGLOBAL VARIABLES ASSIGNED
TYPE NAME VALUE
======== ======== ========
TASK CNT &CNT (3)
COMMON OPER &OPER (OPER3)
COMMON VTLV &VTLV (VT32)
COMMON VAL &VAL (HEX)
-ENDTG3
*** CHANGE ONE COMMON GLOBAL VARIABLE BACK TO A TASK GLOBAL VARIABLE
********************************************************************
&TGLOBAL OPER
FROM GLOBVAR1: AFTER FINAL TGLOBAL STATEMENT
TYPE NAME VALUE
======== ======== ========
TASK CNT &CNT (3)
TASK OPER &OPER (OPER2)
COMMON VTLV &VTLV (VT32)
COMMON VAL &VAL (HEX)
NOTE THAT THE OPER NOW HAS THE VALUE OF THE TASK
GLOBAL VARIABLE OPER AGAIN AS THE MOST RECENT
DECLARATION STATEMENT DEFINED IT AS TASK GLOBAL.
-ENDTG5
GLOBALV Command
The GLOBALV command enables you to define, put, and get global variables in
NetView command list language command lists. The GLOBALV command also
enables you to save global variables in a VSAM database. You can restore saved
global variables if the NetView program is stopped and restarted, or erase (purge)
saved global variables from external storage. Global variables enable multiple
command procedures, regardless of their language, to share a common set of
values.
Refer to the NetView online help for more information on the GLOBALV
command.

Appendix D. Common Operations Services Commands
This chapter describes how to use the common operations services (COS)
commands.
Common Operations Services

The common operations services is a set of commands that supports and enhances
NetView control of common operations, for example, NetView/PC. A COS
application manages nonsystem network architecture devices, such as front-end
line switches and multiplexers. You can send commands to the COS application to
do problem determination for these devices.
For detailed information on the vector formats used by COS, refer to NetView/PC:
Application Programming.
Four NetView COS commands are used with NetView/PC for problem
determination:
LINKTEST
Requests that the COS test a given link or link segment
LINKDATA
Requests that the COS return device data for a given link or link segment
LINKPD
Requests problem determination analysis from the COS on a given link or
link segment
RUNCMD
Sends COS application commands to the COS applications from the
NetView program
Refer to the NetView online help for the syntax of the LINKTEST, LINKDATA,
LINKPD, and RUNCMD commands.
The COS commands are long-running commands that suspend the command list
when they are processed. The command list resumes when the COS command is
complete. While the command list is suspended, no other commands waiting on
the low-priority queue of the task running the command list are processed until
the command list completes. This ensures that commands on the low-priority
queue can be processed in order.
You cannot use the NetView command list language &WAIT control statement or
the REXX TRAP and WAIT functions with the COS commands. Use automation
table-driven command lists to trap messages generated from the COS commands,
with the exception of:
v LINKPD messages DSI533I, DSI534I, DSI535I, DSI536I, and DSI582I. These five
messages are set to values you can use in the form of control and parameter
variables. See “LINKPD Results” on page 151 for more information about
LINKPD results.
v Responses to RUNCMD with the CLISTVAR keyword. CLISTVAR causes the
responses to be stored in variables. See “RUNCMD Results” on page 152 for
more information about RUNCMD results.

Advanced Topics
Common Operations Services Return Codes

After the command is completed, the RC for command lists written in REXX, or
&RETCODE for command lists written in the NetView command list language,
contains one of the following values:
Code Description
0 The command succeeded.
4 The command failed, CLISTVAR was specified with RUNCMD but no
response was returned, or the task is not authorized to issue the command.
16 The command was canceled by the CANCMD.
24 Some command list data was truncated.
28 The COS application returned more than 132 responses for the RUNCMD
with the CLISTVAR keyword.
32 The COS application did not respond within the amount of time specified
by the COS command timeout value in the NetView constants module.
LINKDATA and LINKTEST Results

You can use LINKDATA and LINKTEST in command lists to manage COS, for
example, NetView/PC. Refer to the NetView online help for the formats of these
commands.
Use the variable name without the ampersand for REXX command lists and the
variable name with the ampersand for NetView command list language command
lists.
Note: The path number is 01 for LINKTEST and LINKDATA.
LINKDATA and LINKTEST Variables

You can use the following LINKDATA and LINKTEST variable names in command
lists:
DSIPATHCNT or &DSIPATHCNT
Specifies the number of paths returned. It is always 01 for LINK
commands. The path count is the origin of the value of pp in the following
variable names.
DSIppRC or &DSIppRC
Specifies the number of resources for path pp. The resource count is the
origin of the value of rr in the following variable names.
DSIpprrEC or &DSIpprrEC
Specifies the number of entries for resource rr on path pp. The entry count
is the origin of the value of ee in the following variable names.
DSIpprrRN or &DSIpprrRN
Specifies the name of the resource rr on path pp.
DSIpprrRT or &DSIpprrRT
Specifies the type of the resource rr on path pp.
DSIpprreeDN or &DSIpprreeDN
Specifies the name of the data item ee for resource rr on path pp.

Advanced Topics
DSIpprreeDT or &DSIpprreeDT
Specifies the type of data item ee for resource rr on path pp. Possible values
are:
v BIT STRING
v CHARACTER
v DECIMAL
v HEXADECIMAL
DSIpprreeDV or &DSIpprreeDV
Specifies the value of data item ee for resource rr on path pp.
The italicized letters in the variable names are replaced with the following values:
pp Path number (01)
rr Resource number (01-99)
ee Entry number (01-99)
LINKTEST Additional Variables

In addition, LINKTEST uses the following variables:
DSIREQUEST or &DSIREQUEST
Specifies the number of tests requested.
DSIACTUAL or &DSIACTUAL
Specifies the actual number of tests processed.
DSITESTTYPE or &DSITESTTYPE
Indicates the type of test data reported. Possible values are:
v BACKGROUND
v REQUESTED
DSIRESULT or &DSIRESULT
Indication of the overall results of the test processing. Possible values are:
v PASSED
v FAILED
v INDETERMINATE
LINKPD Results
Results from the LINKPD command are returned in messages that you can use in
a command list to automate the recovery of resources controlled by a COS, for
example, NetView/PC.
LINK results can be accessed by the MSGCNT(), MSGID(), MSGORIGN(),

MSGSTR(), MSGTYP(), and MSGVAR(1) through MSGVAR(31) functions.
For more information about the REXX functions MSGORIGN(), MSGID(),

MSGCNT(), MSGSTR(), and MSGTYP(), see “Message Processing Information
Functions” on page 48. For more information about MSGVAR(1) through
MSGVAR(31), see “Functions Set by MSGREAD” on page 35.
LINKPD results can be accessed by the &MSGCNT, &MSGID, &MSGORIGIN,

&MSGSTR, &MSGTYP control variables, and the parameter variables &1-&31.
For more information about the NetView command list language control variables
&MSGCNT, &MSGID, &MSGORIGIN, &MSGSTR, and &MSGTYP see “Message
Processing Information Functions” on page 48. For more information about
parameter variables used in command lists written in the NetView command list
language, see “Parameter Variables” on page 96.
Appendix D. Common Operations Services Commands 151

Advanced Topics
RUNCMD Results
If you use RUNCMD without the CLISTVAR keyword, responses from the COS
application that performed the RUNCMD are sent to the network operator’s
terminal, and a return code is set. See “Common Operations Services Return
Codes” on page 150 for a description of the return codes.
In REXX, the return code is returned in the RC variable.
In NetView command list language, the return code is returned in the &RETCODE
variable.
If you use RUNCMD with the CLISTVAR keyword, the command results in the
following:
v A return code is set (RC or &RETCODE); see “Common Operations Services
Return Codes” on page 150 for a description of the return codes.
v If the command completes with a return code of 0, 24, or 28, the following
variables are set.
Note: Use the variable name without the ampersand for REXX command lists.
Use the variable name with the ampersand for NetView command list
language command lists.
DSIRUNCNT or &DSIRUNCNT
Contains the number of responses returned from the COS application.
The variable has a value in the range of 001–998.
DSIRUNxxx or &DSIRUNxxx
Contains the different responses from the COS application. The
responses are numbered from 001–998.
Note: The responses from the COS must be character data and cannot
be longer than 255 characters.
If you use RUNCMD with CLISTVAR=YES in a PIPE command, you receive

message BNH074I. This occurs even if the PIPE command is issued from a
NetView command list. You must use CLISTVAR=NO (the default) in the PIPE
command.
Using RUNCMD in a Pipeline

An alternative to using CLISTVAR=YES is to run your RUNCMDs in a pipeline.
The advantages of using pipelines are:
v You can run multiple calls of RUNCMD in parallel.
v You have direct control over the timeout value.
v You can filter the data in the pipeline before setting any variables.
v You can choose the names of variables. REXX-style stem names can be used.
For example, if you used the following segment of REXX code to set up commands
for service points:
RCMD.1 = ’RUNCMD SP=NT000001,APPL=APPLNAME,QUERY ABC’
RCMD.3
. = ’RUNCMD SP=NT000003,APPL=APPLNAME,QUERY ABC’
.
.
RCMD.0 = 100

Advanced Topics
You can then use the following command to issue all 100 commands as fast as the
requests can be scheduled, without waiting for results. The NetView program then
waits up to 120 seconds (between messages) for results and places the messages in
stem RESULT.
’PIPE STEM RCMD. | NETVIEW | CORRWAIT 120 | STEM RESULT.’
Notice that this command does not wait 120 seconds after the last result (assuming
all 100 commands have completed). The NetView program counts the commands
processed and notes when the last response to each command has arrived. The
results in stem RESULT. are not necessarily in the same order as the commands in
stem RCMD. because some service points will respond faster than others. The
number of lines stored in RESULT. will be found in RESULT.0.
For more information about using NetView pipelines, refer to IBM Tivoli NetView
for z/OS Programming: Pipes.
Appendix D. Common Operations Services Commands 153

Appendix E. Comparison of REXX and NetView Command List
Language
This appendix provides a brief comparison between REXX and the NetView
command list language.
Comparison of REXX Instructions and NetView Command List

Language Control Statements
Table 19 shows each control statement used in the NetView command list language
and provides the equivalent REXX instruction. The table is in alphabetical order
based on the name of the NetView command list language control statement.
The last column of the table indicates whether the corresponding REXX instruction
is a standard instruction provided by REXX or an instruction provided by the
NetView program.
Instructions provided by the NetView program can be used only in conjunction

with NetView. These instructions are not supported by the REXX interpreter and
cannot be used in REXX execs run in a non-NetView environment.
Table 19. Comparison of REXX Instructions and NetView Command List Language Control
Statements
Described NetView Control Described REXX Instruction
REXX Instruction on Statement on Provided By
None N/A &BEGWRITE 107 N/A
CGLOBAL(name) 48 &CGLOBAL 143 NetView
TRACE 30 &CONTROL 104 REXX
EXIT 125 &EXIT 125 REXX
SIGNAL 30 &GOTO 125 REXX
IF 123 &IF 123 REXX
PARSE EXTERNAL 24 &PAUSE 108 REXX
PARSE PULL 24 &PAUSE 108 REXX
TGLOBAL(name) 48 &TGLOBAL 142 NetView
TRAP * &WAIT 127 NetView
WAIT * &WAIT 127 NetView
MSGREAD * &WAIT 127 NetView
FLUSHQ * &WAIT 127 NetView
SAY 25 &WRITE 105 REXX
* Refer to the IBM Tivoli NetView for z/OS Command Reference.

REXX/NetView Command List Language Comparison
Comparison of REXX Functions and NetView Command List Language

Control Variables and Functions
Table 20 shows the various control variables and functions used in the NetView
command list language and the equivalent REXX functions.
If the function is provided by the NetView program, it can be used only in

conjunction with the NetView program and is not supported by SAA® REXX.
Table 20. Comparison of REXX Functions and NetView Command List Language Control
Variables and Functions
REXX Described NetView REXX Function
Function on Control Variable Provided By
ACTIONDL() 49 &ACTIONDL NetView
ACTIONMG() 49 &ACTIONMG NetView
APPLID() 78 &APPLID NetView
AREAID() 55 &AREAID NetView
ASID() 78 &ASID NetView
ATTENDED() 78 &ATTENDED NetView
ATTNID() 49 &ATTNID NetView
AUTCONID() 78 &AUTCONID NetView
AUTHCHK(...) 41 None NetView
AUTHCHKX(...) 43 None NetView
AUTOTASK() 78 &AUTOTASK NetView
AUTOTOKE() 55 &AUTOTOKE NetView
BITAND(...) 111 &BITAND REXX
BITOR(...) 112 &BITOR REXX
BITXOR(...) 113 &BITXOR REXX
CART() 55 &CART NetView
CGI() 78 None NetView
CGLOBAL(name) 48, 143 &CGLOBAL NetView
CMDNAME() 44 None NetView
CODE2TXT(...) 38 None NetView
|| 113 &CONCAT REXX
CURCONID() 78 &CURCONID NetView
CURSYS() 78 &CURSYS NetView
DATE() 83 &DATE REXX
DESC() 55 &DESC NetView
DISC() 79 &DISC NetView
DISTAUTO() 79 &DISTAUTO NetView
DOMAIN() 79 &DOMAIN NetView
DOMAIN(’x’) 79 None NetView
| ECVTPSEQ() 79 &ECVTPSEQ NetView
ENVDATA(’x’) 79 None NetView

Variables and Functions (continued)
EVENT() 49 None NetView
FNDMBR(...) 46 None NetView
HCOPY() 82 &HCOPY NetView
HDRMTYPE() 49 &HDRMTYPE NetView
HIER(n) 63, 114 &HIER NetView
HMASPRID() 63 None NetView
HMBLKACT() 64 None NetView
HMCPLINK() 64 None NetView
HMEPNAU() 65 None NetView
HMEPNET() 65 None NetView
HMEPNETV() 66 None NetView
HMEVTYPE() 66 None NetView
HMFWDED() 67 None NetView
HMFWDSNA() 67 None NetView
HMGENCAU() 68 None NetView
HMONMSU() 68 None NetView
HMORIGIN() 69 None NetView
HMSECREC() 69 None NetView
HMSPECAU() 70 None NetView
HMUSRDAT() 71 None NetView
IFRAUGMT() 49 &IFRAUGMT NetView
IFRAUIND() 50 &IFRAUIND NetView
IFRAUIN3() 50 &IFRAUIN3 NetView
IFRAUI3X() 50 &IFRAUI3X NetView
IFRAUSDR() 50 &IFRAUSDR NetView
IFRAUSRB() 50 &IFRAUSRB NetView
IFRAUSB2() 50 &IFRAUSB2 NetView
IFRAUSRC() 51 &IFRAUSRC NetView
IFRAUSC2() 50 &IFRAUSC2 NetView
IFRAUTA1() 51 &IFRAUTA1 NetView
IFRAUWF1() 51 &IFRAUWF1 NetView
JOBNAME() 55 &JOBNAME NetView
JOBNUM() 55 &JOBNUM NetView
KEY() 55 &KEY NetView
LENGTH(...) 116 &LENGTH REXX
LINETYPE() 51 &LINETYPE NetView
LU() 82 &LU NetView
MCSFLAG() 56 &MCSFLAG NetView
Appendix E. Comparison of REXX and NetView Command List Language 157

MSGASID() 56 &MSGASID NetView
MSGAUTH() 56 &MSGAUTH NetView
MSGCATTR() 56 &MSGCATTR NetView
MSGCMISC() 56 &MSGCMISC NetView
MSGCMLVL() 57 &MSGCMLVL NetView
MSGCMSGT() 57 &MSGCMSGT NetView
MSGCNT() 57 &MSGCNT NetView
MSGCOJBN() 57 &MSGCOJBN NetView
MSGCPROD() 57 &MSGCPROD NetView
MSGCSPLX() 58 &MSGCSPLX NetView
MSGCSYID() 58 &MSGCSYID NetView
MSGDOMFL() 58 &MSGDOMFL NetView
MSGGBGPA() 58 &MSGGBGPA NetView
MSGGDATE() 58 &MSGGDATE NetView
MSGGFGPA() 59 &MSGGFGPA NetView
MSGGMFLG() 59 &MSGGMFLG NetView
MSGGMID() 59 &MSGGMID NetView
MSGGSEQ() 59 &MSGGSEQ NetView
MSGGSYID() 59 &MSGGSYID NetView
MSGGTIME() 59 &MSGGTIME NetView
MSGID() 52 &MSGID NetView
| MSGITEM() 52 None NetView
MSGORIGN() 53 &MSGORIGIN NetView
MSGSRCNM() 60 &MSGSRCNM NetView
MSGSTR() 53 &MSGSTR NetView
MSGTOKEN() 60 &MSGTOKEN NetView
MSGTSTMP() 54 &MSGTSTMP NetView
MSGTYP() 60 &MSGTYP NetView
MSGVAR() 54 None NetView
MSGVAR(number) 54 &1 - &31 NetView
MSUSEG(...) 71, 117 &MSUSEG NetView
MVSLEVEL() 79 &MVSLEVEL NetView
NVCNT() 45 &NCCFCNT NetView
NVDELID() 54 &NVDELID NetView
NVID(n) 46 &NCCFID NetView
NVSTAT(name) 46 &NCCFSTAT NetView
NETID() 79 &NETID NetView
NETVIEW() 79 &NETVIEW NetView

NETVIEW(’x’) 79 None NetView
OPID() 77 &OPID NetView
OPID(’x’) 77 None NetView
OPSYSTEM() 80 &OPSYSTEM NetView
PANEL() 80 None NetView
PARMCNT() 45 &PARMCNT NetView
ARG(1) 45 &PARMSTR REXX
PARTID() 80 &PARTID NetView
PRTY() 60 &PRTY NetView
REPLYID() 54 &REPLYID NetView
RC 45 &RETCODE REXX
ROUTCDE() 61 &ROUTCDE NetView
RXDEFENV() 82 &RXDEFENV NetView
RXDEFSTR() 82 &RXDEFSTR NetView
RXNUMENV() 82 &RXNUMENV NetView
RXOVRENV() 82 &RXOVRENV NetView
RXOVRSTR() 82 &RXOVRSTR NetView
SESSID() 54 &SESSID NetView
SMSGID() 61 &SMSGID NetView
STCKGMT() 80 &STCKGMT NetView
SUBSTR(...) 120 &SUBSTR REXX
SUBSYM(...) 40 None NetView
SUPPCHAR() 80 &SUPPCHAR NetView
SYSCONID() 61 &SYSCONID NetView
SYSID() 61 &SYSID NetView
SYSPLEX() 80 &SYSPLEX NetView
TASK() 80 &TASK NetView
TGLOBAL(name) 48, 142 &TGLOBAL NetView
TIME() 83 &TIME REXX
TOWER(...) 81 None NetView
TYPE() 81 None NetView
VTAM() 81 &VTAM NetView
VTCOMPID() 81 &VTCOMPID NetView
WEEKDAYN() 81 &WEEKDAYN NetView
WTOREPLY 61 &WTOREPLY NetView
Appendix E. Comparison of REXX and NetView Command List Language 159

Command List Commands
Commands Used in Command Lists

The following is a list of NetView commands in the IBM Tivoli NetView for
z/OS Command Reference that are for use in command lists. With the exception of
FLUSHQ, MSGREAD, TRAP, and WAIT, you can use these commands in
command lists written in REXX or in the NetView command list language.
v DOM
v FLUSHQ
v GETMPRES
v GETMSIZE
v GETMTFLG
v GETMTYPE
v GLOBALV
v MSGREAD
v MSGROUTE
v PARSEL2R
v SDOMAIN (with QUIET option)
v TRAP
v WAIT
v WTO
v WTOR
Note: FLUSHQ, MSGREAD, TRAP, and WAIT can be used only in REXX
command lists.
When using the commands in a REXX command list, enclose in single quotation
marks the parts of the command on which you do not want variable substitution
to take place.

Appendix F. Command List Examples Index
This appendix contains reference tables for the REXX and NetView command list
examples contained in this book. Entries in the tables are listed in alphabetical
order.
The tables show the name of the command list example, a brief description of its
function, and where to find the example in this book.
REXX Command List Examples

Table 21 lists the REXX command list examples shown in this book.
Table 21. REXX Command List Examples Reference
Command List
Example Description Location
ACTAPPLS This command list displays active applications. Figure 53 on
page 163
ACTLU This command list activates a VTAM node. Figure 54 on
page 165
CHKOPNUM This command list shows how basic REXX functions and NetView-specific Figure 55 on
functions can be used in command lists. CHKOPNUM illustrates the use of such page 166
things as the REXX PARSE instruction, and the NetView MSGTRAP, WAIT,
MSGREAD, and GLOBALV commands.
CHKRSTAT This command list shows how more complex REXX functions and Figure 56 on
NetView-specific functions can be used in command lists. CHKRSTAT illustrates page 168
the use of the REXX INTERPRET instruction, and the NetView WAIT and
GETMLINE commands.
DSPRSTAT This command list can be used by an operator station task (OST) operator to Figure 57 on
display the results of several executions of the CHKRSTAT command list for a page 170
specific resource. Use DSPRSTAT as an aid when you need to determine how
often a resource is active, based on the intervals in which it was checked by the
CHKRSTAT command list.
GETCG The GETCG command list gets the value of a common global variable and Figure 58 on
displays it to the requesting task. page 171
GREETING This command list shows an example of waiting and trapping using the DATE Figure 59 on
command. page 171
LISTVAR Refer to the NetView online help for a functional description of this command Figure 60 on
list. page 172
PRINT This command list prints members of a data set to a system print file. Figure 61 on
page 173
TYPE This command list displays members of a data set one line at a time at the Figure 62 on
invoking user’s terminal. page 174
TYPEIT This command list displays members of a data set one line at a time at the Figure 63 on
invoking user’s terminal. page 175
NetView Command List Language Examples

Table 22 on page 162 lists the NetView command list language command list
examples shown in this book.

NetView Command List Language Examples Index
Table 22. NetView Command List Examples Reference

Command List
Example Description Location
ACTONE This command list issues a VTAM command to activate a logical unit (LU). The Figure 48 on
ACTONE command list shows the use of &WAIT to wait for one message. page 138
CLIST1 The CLIST1 command list contains the nested command list UPDT1. CLIST1 and Figure 50 on
UPDT1 show how to define, reference, and update a task global variable. page 144
GLOBVAR1 The GLOBVAR1 command list illustrates the scope of user variables, task global Figure 52 on
variables, and common global variables within individual command lists. page 146
PATH This command list uses the &WRITE control statement and a VTAM command. “&WRITE
Control
Statement” on
page 105
UPDT1 The CLIST1 command list contains the nested command list UPDT1. CLIST1 and Figure 51 on
UPDT1 show how to define, reference, and update a task global variable. page 145

Appendix G. Examples of REXX Command Lists for NetView
This section contains examples of REXX command lists written for the NetView
program. These examples show how you can use the instructions and functions
provided by NetView and the standard REXX instructions and functions together
in REXX command lists executing in a NetView environment.
ACTAPPLS Example
/* *******************************************************************/
/* */
/* ACTAPPLS - REXX VERSION */
/* */
/* DISPLAY ONLY THE ACTIVE APPLS */
/* */
/* *******************************************************************/
TRACE E
SAY ’ACTIVE APPLICATIONS:’ /* Write the header */
SAY ’====================’
’TRAP SUPPRESS MESSAGES IST350I IST097I’ /* Wait on the display */
’D NET,APPLS’
’WAIT 60 SECONDS FOR MESSAGES’
DO WHILE EVENT() = ’M’
SELECT /* SELECT on all events */
WHEN EVENT() = ’M’ THEN
DO
’MSGREAD’
SELECT /* SELECT on message */
WHEN MSGID()=’IST350I’ THEN
CALL FIRST
OTHERWISE
CALL ALLELSE
END /* END - SELECT */
’WAIT CONTINUE’
END /* EVENT() = M do loop */
OTHERWISE
DO
’TRAP NO MESSAGES’
’FLUSHQ’
END
END /* END - SELECT */
END /* END - DO WHILE */
/* */
/* ALL NON-INFORMATIONAL MESSAGES GO HERE */
/* */
ALLELSE:
RETURN
/* */
/* THE MULTILINE WTO WITH THE APPL INFORMATION COMES HERE */
/* */
Figure 53. ACTAPPLS Example (Part 1 of 2)

REXX Command Lists
FIRST:
’GETMSIZE NUMLINES’ /* Determine the number of lines */
I = 0 /* Initialize line number counter*/
TOTALACT = 0 /* Initialize total active appls */
DO WHILE NUMLINES ¬= I /* DO for all lines */
NUMACT = 0 /* Number of active appls found

on this line */
I = I + 1 /* Bump the line counter */
’GETMLINE LINE’ VALUE(I) /* How many lines in the MLWTO? */
/* PARSE OUT THE LINE, A1 A2 A3 ARE APPL NAMES, S1 S2 S3 ARE STATUS */
PARSE VAR LINE MSG A.1 S.1 A.2 S.2 A.3 S.3 .
DO CURR = 1 TO 3
IF S.CURR ¬= ’’ THEN /* Do we have a status? */
DO
IF S.CURR = ’ACTIV’ THEN /* Is the current APPL active? */
NUMACT = NUMACT + 1 /* Bump the number active count */
ELSE
DO
S.CURR = ’’ /* APPL not active, so blank out */
A.CURR = ’
END
END
ELSE
A.CURR = ’’ /* Not an APPL */
END /* END - DO CURR */
IF NUMACT ¬= 0 & (A.1 ¬= ’’ | A.2 ¬= ’’ | A.3 ¬= ’’) THEN
SAY STRIP(A.1 A.2 A.3,’L’)
TOTALACT = TOTALACT + NUMACT /* Bump the total active counter */
END /* END - DO WHILE */
SAY ’ ’ /* Blank line */

SAY ’NUMBER OF APPLICATIONS ACTIVE: ’TOTALACT
EXIT
Figure 53. ACTAPPLS Example (Part 2 of 2)

REXX Command Lists
ACTLU Example
/* ACTLU COMMAND LIST - REXX VERSION */

/* FUNCTION : TO ACTIVATE A VTAM NODE. */
/* INPUT : 1 PARAMETER, THE NAME OF THE NODE. */
/**********************************************************************/
IF MSGVAR(1) = ’’ THEN /* NO FIRST PARAMETER ? */
DO /* THEN ISSUE REQUEST */
SAY ’PLEASE ENTER "GO NODENAME"’,/* REQUEST NODENAME FROM USER */
’OR "GO STOP" TO CONTINUE’ /* OR, ALLOW USER TO STOP CLIST */
PARSE PULL NODE /* NODE = NODENAME OR STOP */
END /* THEN ISSUE REQUEST */
ELSE /* FIRST PARAMETER EXISTS */
NODE = MSGVAR(1) /* ASSUME IT IS A NODE NAME */
/* IF NODE=’STOP’ CLIST ENDS */
IF NODE¬=’STOP’ THEN /* DID USER CHOOSE TO STOP ? */
DO /* PROCESS NODENAME */
’TRAP AND SUPPRESS ONLY MESSAGES IST* ’ /* TRAP ALL VTAM MSGS */
’V NET,ACT,ID=’NODE /* ISSUE VTAM ACTIVATE FOR NODE */
IF RC=0 THEN /* VALID NODE NAME ? */
DO /* YES, RETURN CODE = 0 */
’WAIT 30 SECONDS FOR MESSAGES’ /* WAIT FOR 30 SECONDS */
IF EVENT()=’M’ THEN /* OUT OF WAIT - IS THERE A MSG? */
DO /* PROCESS TRAPPED MESSAGE */
’MSGREAD’ /* READ IN 1ST MESSAGE */
DO WHILE (RC=0) /* IF RC¬=0 THEN NO MORE MSGS */
SELECT /* DETERMINE WHICH MESSAGE HIT */
WHEN (MSGID() = ’IST061I’) /* NODE NOT FOUND */
THEN SAY ’==> LU UNKNOWN ’, /* INFORM USER */
’TO YOUR VTAM <==’
WHEN (MSGID() = ’IST093I’) /* NODE NOW ACTIVE */
THEN SAY ’==> TERMINAL ’, /* INFORM USER */
MSGVAR(1)’ NOW ’,
MSGVAR(2) ’<==’
OTHERWISE /* IGNORE THE VTAM MESSAGE */
’WAIT CONTINUE’ /* CONTINUE WAITING */
END /* OF SELECT FOR IST061I/IST093I */
’MSGREAD’ /* READ IN THE NEXT MESSAGE */
END /* DO WHILE RC=0, LOOP BACK */
END /* PROCESS TRAPPED MESSAGE DO */
/* OUT OF DO WHILE, CHECK FOR
ERROR OR TIME-OUT EVENTS */
SELECT /* CHECK RESULT OF THE WAIT */
WHEN (EVENT()=’E’) THEN /* ERROR ENCOUNTERED ? */
SAY ’ERROR PROCESSING ’, /* INFORM USER */
’ACTIVATE COMMAND’
WHEN (EVENT()=’T’) THEN /* WAIT TIME-OUT ENCOUNTERED? */
SAY ’NO RESPONSE TO ’, /* INFORM USER */
’ACTLU CLIST FOR ’NODE
OTHERWISE /* NO-OP */
END /* OF SELECT FOR ERROR/TIME-OUT */
END /* IF RC=0 (VALID NODENAME) */
END /* IF NODE¬=’STOP’ PROCESSING */
EXIT
Figure 54. ACTLU Example
CHKOPNUM Example
Figure 55 on page 166 is an example of a command list that uses the PARSE
instruction.
Appendix G. Examples of REXX Command Lists for NetView 165

REXX Command Lists
/**********************************************************************/
/* */
/* THE FOLLOWING REXX COMMAND LIST IS A FAIRLY SIMPLE EXAMPLE */
/* OF HOW SOME OF THE BASIC REXX FUNCTIONS AND NETVIEW-SPECIFIC */
/* FUNCTIONS CAN BE USED IN A COMMAND LIST. IT ILLUSTRATES THE USAGE*/
/* OF SUCH THINGS AS THE REXX ’PARSE’ INSTRUCTION, AND THE NETVIEW */
/* SUPPLIED ’MSGTRAP’, ’WAIT’, ’MSGREAD’, AND ’GLOBALV’ COMMANDS. */
/* */
/**********************************************************************/
/* */
/* COMMAND LIST NAME: CHKOPNUM */
/* */
/* THIS COMMAND LIST CAN BE USED PERIODICALLY TO CHECK THE */
/* NUMBER OF OPERATORS CURRENTLY LOGGED ON, AND WILL KEEP THE */
/* INFORMATION IN COMMON GLOBAL VARIABLES. THE INFORMATION */
/* COLLECTED CAN LATER BE RETRIEVED BY USING THE ’DISPLAY’ */
/* OPTION. */
/* */
/* INPUT: */
/* ’’ - WILL CHECK THE NUMBER OF OPERATORS LOGGED ON */
/* AND UPDATE APPROPRIATE COMMON GLOBAL VARIABLES */
/* ’DISPLAY’ - WILL ANALYZE THE VALUE IN THE COMMON GLOBAL */
/* VARIABLES AND DISPLAY THE RESULTS */
/* ANY OTHER */
/* INPUT - WILL DEFAULT TO ’’ */
/* */
/* USAGE EXAMPLE: */
/* 1. EXECUTE THE FOLLOWING TO CAUSE THE NUMBER OF */
/* OPERATORS TO BE CHECKED AT A CERTAIN TIME (COULD BE */
/* ANY TIME PERIOD); */
/* -> ’AT 08:00:00,CHKOPNUM’ */
/* 2. AT ANY TIME, EXECUTE THE FOLLOWING COMMAND TO DISPLAY */
/* THE RESULTS OF THE PREVIOUS EXECUTIONS: */
/* -> ’CHKOPNUM DISPLAY’ */
/* RESULTS WILL BE DISPLAYED ON YOUR TERMINAL */
/* */
/* CHANGE CODE DATE DESCRIPTION */
/* ----------- -------- ------------------------------------------ */
/* */
/**********************************************************************/
Figure 55. CHKOPNUM Example (Part 1 of 2)

REXX Command Lists
SIGNAL ON ERROR
PARSE ARG OPTION
’GLOBALV GETC CHKOPTIMES, CHKOPNUM, CHKOPMAX’
IF OPTION = ’DISPLAY’ THEN DO;
IF CHKOPTIMES = ’’ THEN
SAY ’NUMBER OF OPERATORS HAS NEVER BEEN CHECKED’
ELSE DO;
SAY ’NUMBER OF OPERATORS HAS BEEN CHECKED ’CHKOPTIMES’ TIMES’
SAY ’AVERAGE NUMBER OF OPERATORS LOGGED ON
IS: ’CHKOPNUM/CHKOPTIMES
SAY ’MAXIMUM NUMBER OF OPERATORS LOGGED ON IS: ’CHKOPMAX
END;
EXIT 0;
END;
CUROPNUM = 0
’TRAP AND SUPPRESS MESSAGES OPERATOR:,END’
’LIST STATUS=OPS’
DO UNTIL MSGID()=’END’
’WAIT FOR MESSAGES’
’MSGREAD’
IF MSGID() = ’OPERATOR:’ THEN CUROPNUM = CUROPNUM +1
ELSE NOP
END
IF CHKOPTIMES = ’’ THEN CHKOPTIMES = 1
ELSE CHKOPTIMES = CHKOPTIMES + 1
IF CHKOPNUM = ’’ THEN CHKOPNUM = CUROPNUM
ELSE CHKOPNUM = CHKOPNUM + CUROPNUM
IF CHKOPMAX = ’’ THEN CHKOPMAX = CUROPNUM
ELSE IF CHKOPMAX < CUROPNUM THEN CHKOPMAX = CUROPNUM
’GLOBALV PUTC CHKOPTIMES, CHKOPNUM, CHKOPMAX’
EXIT 0;
ERROR: SAY ’ERROR OCCURRED. RETURN CODE = ’ RC
EXIT -1;
Figure 55. CHKOPNUM Example (Part 2 of 2)
CHKRSTAT Example
Figure 56 on page 168 is an example of a command list that uses the INTERPRET
instruction.

REXX Command Lists
/**********************************************************************/
/* */
/* THE FOLLOWING REXX COMMAND LIST IS MORE COMPLEX THAN CHKOPNUM. */
/* IT ILLUSTRATES USAGE OF SUCH THINGS AS THE REXX ’INTERPRET’ */
/* INSTRUCTION, AND THE NETVIEW ’WAIT’ (FOR MESSAGES AND TIME), */
/* AND THE ’GETMLINE’ COMMAND (FOR MULTILINE MESSAGES) */
/* */
/**********************************************************************/
/* */
/* COMMAND LIST NAME: CHKRSTAT */
/* */
/* THIS COMMAND LIST CHECKS WHETHER A SPECIFIED RESOURCE */
/* IS ACTIVE, AND INCREMENTS A COMMON GLOBAL VARIABLE THAT */
/* REFLECTS THE NUMBER OF TIMES IT WAS IN THAT STATE. THIS */
/* COMMAND LIST SHOULD BE SCHEDULED TO RUN UNDER AN AUTOTASK */
/* AT REGULAR INTERVALS. */
/* */
/* INPUT PARAMETERS: */
/* RESNAME - NAME OF RESOURCE TO CHECK STATUS OF */
/* */
/* ----------- -------- ------------------------------------------ */
/* */
/**********************************************************************/
SIGNAL ON ERROR /* SIGNAL IF ERROR OCCURS */
PARSE UPPER ARG RESNAME /* GET INPUT, IF ANY */
/* IF NO RESOURCE NAME GIVEN, DISPLAY ERROR MESSAGE AND EXIT */

IF RESNAME = ’’ THEN DO;
SAY ’RESOURCE NAME MUST BE PROVIDED’
EXIT 99
END
/* SET UP TRAP FOR POSSIBLE RESPONSES TO ’D NET,ID=’ COMMAND, ISSUE */
/* COMMAND, AND WAIT FOR MESSAGE TO ARRIVE */
’TRAP AND SUPPRESS MESSAGES IST097I IST075I IST453I’
’D NET,ID=’RESNAME
’WAIT 60 SECONDS FOR MESSAGES’
/* IF MESSAGE DID NOT ARRIVE, THEN GIVE ERROR MESSAGE AND EXIT */
IF EVENT() ¬= ’M’ THEN DO
SAY ’ NO RESPONSE FROM VTAM - RESOURCE COUNT NOT UPDATED ’
EXIT 99
END
/* READ MESSAGE. IF IT IS IST097I, ISSUE WAIT AGAIN, AND THE NEXT */
/* MESSAGE READ SHOULD BE IST075I, WHICH HAS THE STATUS INFO */
Figure 56. CHKRSTAT Example (Part 1 of 2)

REXX Command Lists
’MSGREAD’
IF MSGID() = ’IST097I’ THEN DO;
’WAIT CONTINUE’
’MSGREAD’
/* IF THE MESSAGE IS NOT IST075I, DO NOTHING, AND THE STATUS WILL */
/* DEFAULT TO INACTIVE. IF IT IS IST075I, GET THE 2ND LINE OF THE */
/* MULTI-LINE MESSAGE AND GET THE CURRENT STATE FROM THAT LINE */
IF MSGID() = ’IST075I’ THEN DO
’GETMLINE STATLINE ’ 2
/* IF STRING CONTAINS IST486I THEN PARSE OUT RESOURCE STATUS */
IF INDEX(STATLINE,’IST486I’) >0 THEN
PARSE VALUE STATLINE WITH MSGTXT1 ’STATUS=’ RESSTATE .
END
END
/* IF THE CURRENT STATE IS ACTIVE OR ACTIVE W/SESSION, THEN GET */

/* INCREMENT AND UPDATE THE COMMON GLOBAL VARIABLE WITH THE NAME */
/* ’RESOURCE NAME’ CONCATENATED WITH ’@A’. NOTE THAT SINCE THE */
/* GLOBALV COMMAND REQUIRES THE VARIABLE NAME, A VARIABLE HAS */
/* TO BE SET TO THE VARIABLE NAME, SINCE IT IS DYNAMICALLY */
/* CONSTRUCTED. THE REXX INTERPRET INSTRUCTION MUST ALSO BE USED */
/* TO PERFORM OPERATIONS ON THE DYNAMICALLY CONSTRUCTED VARIABLE */
IF RESSTATE = ’ACTIV’ | RESSTATE = ’ACT/S’ THEN DO
VARNAME = RESNAME\’@A’
’GLOBALV GETC ’VARNAME
INTERPRET ’ACT# =’VARNAME
IF DATATYPE(ACT#) ¬= ’NUM’ THEN
ACT# = 1 /* IF NONNUMERIC */
ELSE
ACT# = ACT# + 1
INTERPRET VARNAME’=ACT#’
’GLOBALV PUTC ’VARNAME
END
/* IF THE CURRENT STATE IS NOT ACTIVE OR ACTIVE W/SESSION, THEN GET */
/* INCREMENT AND UPDATE THE COMMON GLOBAL VARIABLE WITH THE NAME */
/* ’RESOURCE NAME’ CONCATENATED WITH ’@NA’. NOTE THAT SINCE THE */
/* GLOBALV COMMAND REQUIRES THE VARIABLE NAME, A VARIABLE HAS */
/* TO BE SET TO THE VARIABLE NAME, SINCE IT IS DYNAMICALLY */
/* CONSTRUCTED. THE REXX INTERPRET INSTRUCTION MUST ALSO BE USED */
/* TO PERFORM OPERATIONS ON THE DYNAMICALLY CONSTRUCTED VARIABLE */
ELSE DO
VARNAME = RESNAME\’@NA’
’GLOBALV GETC ’VARNAME
INTERPRET ’NACT# =’VARNAME
IF DATATYPE(NACT#) ¬= ’NUM’ THEN
NACT# = 1 /* IF NONNUMERIC */
ELSE
NACT# = NACT# + 1
INTERPRET VARNAME’=NACT#’
’GLOBALV PUTC ’VARNAME
END
EXIT 0;
ERROR: SAY ’ERROR OCCURRED. RETURN CODE IS ’ RC
EXIT -1; /* END COMMAND LIST FOR ERROR */
Figure 56. CHKRSTAT Example (Part 2 of 2)
DSPRSTAT Example
Figure 57 on page 170 is an example of a command list that uses the same type of
function as Figure 56 on page 168.

REXX Command Lists
/**********************************************************************/
/* */
/* THE FOLLOWING REXX COMMAND LIST GOES ALONG WITH THE PREVIOUS */
/* EXAMPLE (CHKRSTAT), AND SHOWS MANY OF THE SAME TYPE OF FUNCTIONS */
/* AS THE PREVIOUS EXAMPLE. */
/* */
/* THIS COMMAND LIST COULD BE USED BY ANY OST OPERATOR TO DISPLAY */
/* THE RESULTS OF SEVERAL EXECUTIONS OF THE CHKRSTAT COMMAND LIST */
/* FOR A SPECIFIC RESOURCE. IT COULD BE USED AS AN AID IN */
/* DETERMINING HOW OFTEN A RESOURCE IS ACTIVE, BASED ON THE INTERVALS*/
/* IN WHICH IT WAS CHECKED BY THE CHKRSTAT COMMAND LIST */
/* */
/**********************************************************************/
/* */
/* COMMAND LIST NAME: DSPRSTAT */
/* */
/* THIS COMMAND LIST CAN BE USED TO DISPLAY HOW OFTEN A RESOURCE */
/* WAS ACTIVE VS. NOT ACTIVE, AS RECORDED BY THE CHKRSTAT COMMAND */
/* LIST */
/* */
/* INPUT PARAMETERS: NONE */
/* */
/* ----------- -------- ------------------------------------------ */
/* */
/**********************************************************************/
PARSE UPPER ARG RESNAME /* GET INPUT, IF ANY */
/* IF NO RESOURCE NAME GIVEN, DISPLAY ERROR MESSAGE AND EXIT */

IF RESNAME = ’’ THEN DO;
SAY ’RESOURCE NAME MUST BE PROVIDED’
EXIT 99
END
VARNAMEA = RESNAME\’@A’ /* SET THE VAR NAME ACT */
VARNAMENA = RESNAME\’@NA’ /* SET THE VAR NAME NACT */
’GLOBALV GETC ’VARNAMEA /* GET THE ACTIVE INFO */
’GLOBALV GETC ’VARNAMENA /* GET THE INACTIVE INFO */
INTERPRET ’RACT = ’VARNAMEA /* PUT ACTIVE # IN VAR */
INTERPRET ’RINACT = ’VARNAMENA /* PUT INACTIVE # IN VAR */
/* DISPLAY THE STATISTICS FOF THE RESOURCE SPECIFIED */

IF RACT = ’’ & RINACT = ’’ THEN
SAY ’NO STATISTICS HAVE BEEN COLLECTED FOR RESOURCE: ’RESNAME
/* DISPLAY THE STATISTICS FOR THE RESOURCE SPECIFIED */

ELSE DO
IF DATATYPE(RACT) ¬= ’NUM’ THEN RACT = 0 /* IF NOT NUMERIC */
IF DATATYPE(RINACT) ¬= ’NUM’ THEN RINACT = 0 /* IF NOT NUMERIC*/
SAY ’RESOURCE ’RESNAME’ STATISTICS:’
SAY ’ NUMBER OF TIMES RESOURCE WAS ACTIVE : ’RACT
SAY ’ NUMBER OF TIMES RESOURCE WAS INACTIVE: ’RINACT
PERCENTACT = RACT/(RACT+RINACT)*100\’%’ /* DETERMINE PERCENT */
SAY ’ PERCENTAGE OF TIMES RESOURCE WAS ACTIVE: ’PERCENTACT
END
EXIT 0
Figure 57. DSPRSTAT Example
GETCG Example

REXX Command Lists
/****************************************************************/
/* GETCG COMMAND LIST - REXX VERSION */
/* */
/* GETCG COMMAND LIST GETS THE VALUE OF A COMMON GLOBAL */
/* VARIABLE AND DISPLAYS IT TO THE REQUESTING TASK */
/****************************************************************/
TRACE E
’GLOBALV GETC’ MSGVAR(1)
’MESSAGE 309I GETCG COMMON GLOBAL VARIABLE’ MSGVAR(1) ,
’HAS VALUE ’ VALUE(MSGVAR(1))
EXIT
Figure 58. GETCG Example
GREETING Example
/**********************************************************************/
/* */
/* GREETING - SHOW SIMPLE EXAMPLE OF WAITING AND TRAPPING */
/* USING THE DATE COMMAND */
/* */
/* NOTE: WHEN DATE IS ENTERED, THE FOLLOWING IS RETURNED: */
/* */
/* CNM359I DATE : TIME = HH:MM DATE = MM/DD/YY */
/**********************************************************************/
’TRAP AND SUPPRESS ONLY MESSAGES CNM359I ’ /* TRAP DATE MESSAGE */
’DATE’ /* ISSUE COMMAND */
’WAIT 10 SECONDS FOR MESSAGES’ /* WAIT FOR ANSWER */
SELECT /* RESULT IS BACK, PROCESS IT... */
WHEN (EVENT()=’M’) THEN /* DID WE GET A MESSAGE? */
DO /* YES... */
’MSGREAD’ /* ... READ IT IN */
HOUR=SUBSTR(MSGVAR(5),1,2) /* ... PARSE OUT THE HOUR */
SELECT /* GIVE APPROPRIATE GREETING... */
WHEN (HOUR<12) THEN /* ...BEFORE NOON? */
SAY ’GOOD MORNING’
WHEN (HOUR<18) THEN /* ...BEFORE SIX? */
SAY ’GOOD AFTERNOON’
OTHERWISE /* ...MUST BE NIGHT */
SAY ’GOOD EVENING’
END /* OF SELECT */
END /* OF DO */
WHEN (EVENT()=’E’) THEN /* DID WE GET AN ERROR? */
SAY ’ERROR OCCURRED WAITING FOR DATE COMMAND RESPONSE’
WHEN (EVENT()=’T’) THEN /* DID WE GET A TIME-OUT? */
SAY ’NO MESSAGE RETURNED FROM DATE COMMAND’
OTHERWISE
END /* OF SELECT */
EXIT
Figure 59. GREETING Example

REXX Command Lists
LISTVAR Example
/**********************************************************************/
/* */
/* THE LISTVAR COMMAND LIST WRITTEN IN REXX */
/* */
/**********************************************************************/
SELECT
WHEN MSGVAR(1)=’?’ THEN /* HELP REQUESTED ? */
’HELP LISTVAR’ /* GO GET HELP */
WHEN MSGVAR(1)¬=’’ THEN /* ANY PARMS SPECIFIED ? */
’MESSAGE 306E,LISTVAR’ MSGVAR(1) /* NO PARMS ALLOWED */
OTHERWISE /* ALL OK, LIST OUT VARIABLES*/
DO
MYSYS = SUBSTR(OPSYSTEM(),1,3)
SAY "CNM353I LISTVAR : ’OPSYSTEM’ = "OPSYSTEM()
IF MYSYS = ’VSE’ THEN
SAY "CNM353I LISTVAR : ’CURPART’ = "CURPART()
IF MYSYS = ’MVS’ THEN
SAY "CNM353I LISTVAR : ’MVSLEVEL’ = "MVSLEVEL()
SAY "CNM353I LISTVAR : ’CURSYS’ = "CURSYS()
SAY "CNM353I LISTVAR : ’VTAMLVL’ = "VTAM()
SAY "CNM353I LISTVAR : ’VTCOMPID’ = "VTCOMPID()
TEMP = NETVIEW()
IF TEMP = ’NV33’ THEN TEMP = ’Tivoli V1R3’
SAY "CNM353I LISTVAR : ’NETVIEW’ = "TEMP
SAY "CNM353I LISTVAR : ’NETVIEW’ = "NETVIEW()
SAY "CNM353I LISTVAR : ’NETID’ = "NETID()
SAY "CNM353I LISTVAR : ’DOMAIN’ = "DOMAIN()
SAY "CNM353I LISTVAR : ’APPLID’ = "APPLID()
SAY "CNM353I LISTVAR : ’OPID’ = "OPID()
SAY "CNM353I LISTVAR : ’LU’ = "LU()
SAY "CNM353I LISTVAR : ’TASK’ = "TASK()
SAY "CNM353I LISTVAR : ’NVCNT’ = "NVCNT()
SAY "CNM353I LISTVAR : ’HCOPY’ = "HCOPY()
SAY "CNM353I LISTVAR : ’CURCONID’ = "CURCONID()
IF MYSYS = ’MVS’ &AUTOTASK() = ’1’ THEN
SAY "CNM353I LISTVAR : ’AUTCONID’ = "AUTCONID()
IF VTAM() = ’’ THEN /* IS VTAM ACTIVE ? */
SAY ’CNM386I LISTVAR : VTAM IS NOT ACTIVE AT THIS TIME’
END /* OF THE LIST VARIABLES */
END /* OF SELECT */
RETURN /* RETURN TO CALLER */
EXIT
Figure 60. LISTVAR Example
PRINT Example
Figure 61 on page 173 is an example of a command list used for printing a data
set.

REXX Command Lists
/**********************************************************************/
/* PRINT COMMAND LIST */
/* ------------------ */
/* */
/* FUNCTION: THIS COMMAND LIST PRINTS MEMBERS OF A DATA SET TO A */
/* SYSTEM PRINT FILE. */
/* */
/* INPUT PARMS: DATASETNAME = FULLY QUALIFIED DATA SET NAME */
/* (INCLUDING MEMBER NAME) TO DISPLAY AT THE TERMINAL. */
/* */
/* OUTPUT: A SYSTEM PRINT FILE. */
/**********************************************************************/
SIGNAL ON ERROR /* SIGNAL IF ERROR OCCURS*/
ARG DATASETNAME /* PARSE CLIST INPUT */
IF DATASETNAME=’’ | PARMCNT() > 1 THEN /* NO CLIST INPUT ? */
DO /* NAME NOT SPECIFIED */
SAY ’INCORRECT SYNTAX USED.’ /* ISSUE ERROR MSG */
SAY ’CORRECT SYNTAX IS : ’ /* ISSUE HELP MSG */
SAY ’ PRINT DATASET.NAME(MEMBER) ’ /* ISSUE HELP MSG */
RC=24 /* SET RETURN CODE */
END /* NAME NOT SPECIFIED */
ELSE /* CORRECT NAME/SYNTAX */
DO /* NAME WAS SPECIFIED */
’TRAP DISPLAY ONLY MESSAGES *’ /* TRAP/SUPPRESS MSGS */
’ALLOCATE SYSOUT(A) FREE RECFM(FB) ’, /* ALLOC/CONNECT SYSTEM */
’LRECL(80) BLKSIZE(4000)’ /* ... PRINTER FOR USAGE */
’WAIT FOR MESSAGES’ /* WAIT FOR RESULTS */
’MSGREAD’ /* READ A MESSAGE IN */
IF (MSGID()¬=’CNM272I’) THEN /* IS MSG CNM272I ? */
DO /* ¬ CNM272I MSG */
SAY MSGID() MSGSTR() /* DISPLAY MESSAGE */
END /* ¬ CNM272I MSG */
ELSE /* MSG IS CNM272I */
DO /* PROCESS 1ST CNM272I */
DDNAMEO = MSGVAR(1) /* SAVE OUTPUT DDNAME */
’TRAP AND DISPLAY ONLY MESSAGES *’ /* TRAP/SUPPRESS MSGS */
’ALLOCATE DA(’DATASETNAME’) SHR FREE’/* ALLOC/CONNECT FILE */
’WAIT FOR MESSAGES’ /* WAIT FOR MESSAGES */
’TRAP NO MESSAGES’ /* DISABLE TRAP MSGS */
DO /* ¬ CNM272I MSG*/
END /* ¬ CNM272I MSG*/
DO /* PROCESS 2ND CNM272I */
DDNAMEI = MSGVAR(1) /* SAVE INPUT DDNAME */
ADDRESS MVS ’EXECIO 1 DISKR ’DDNAMEI /* READ 1ST LINE */
DO WHILE RC=0 /* WHILE RC = 0 */
ADDRESS MVS ’EXECIO 1 DISKW ’DDNAMEO /* WRITE LINE OUT */
ADDRESS MVS ’EXECIO 1 DISKR ’DDNAMEI /* READ NEXT LINE */
END /* WHILE RC = 0 */
/* PUT OUT COMPLETE MSG */
’MESSAGE 309I PRINT CLIST IS NOW FINISHED’
END /* PROCESS 2ND CNM272I */
END /* PROCESS 1ST CNM272I */
END /* NAME WAS SPECIFIED */
RETURN /* RETURN TO CALLER/EXIT */

EXIT -1; /* END COMMAND LIST FOR ERROR*/
Figure 61. PRINT Example

REXX Command Lists
TYPE Example
Figure 62 is an example of a command list used to display the members of a data
set.
/**********************************************************************/
/* TYPE COMMAND LIST */
/* ----------------- */
/* */
/* FUNCTION: THIS COMMAND LIST DISPLAYS MEMBERS OF A DATA SET AT THE */
/* (INVOKING) USER’S NETVIEW TERMINAL ONE LINE AT A TIME. */
/* */
/* */
/* OUTPUT: LINE = EACH LINE WITHIN THE MEMBER SPECIFIED BY THE USER. */
/**********************************************************************/
SIGNAL ON ERROR /* SIGNAL IF ERROR OCCURS*/
ARG DATASETNAME /* PARSE CLIST INPUT */
IF DATASETNAME=’’ | PARMCNT() > 1 THEN /* NO CLIST INPUT ? */
DO /* NAME NOT SPECIFIED */
SAY ’INCORRECT SYNTAX USED.’ /* ISSUE ERROR MSG */
SAY ’CORRECT SYNTAX IS : ’ /* ISSUE HELP MSG */
SAY ’ TYPE DATASET.NAME(MEMBER) ’ /* ISSUE HELP MSG */
RC=24 /* SET RETURN CODE */
END /* NAME NOT SPECIFIED */
ELSE /* CORRECT NAME/SYNTAX */
DO /* NAME WAS SPECIFIED */
’TRAP AND SUPPRESS ONLY MESSAGES *’ /* TRAP/SUPPRESS MSGS */
’ALLOCATE DA(’DATASETNAME’) SHR FREE’ /* ALLOC/CONNECT FILE */
’WAIT FOR MESSAGES’ /* WAIT FOR MESSAGES */
’TRAP NO MESSAGES’ /* DISABLE TRAP MSGS */
DO /* ¬ CNM272I MSG */
END /* ¬ CNM272I MSG */
DO /* PROCESS CNM272I MSG */
DDNAME = MSGVAR(1) /* SAVE DYNAMIC DDNAME */
ADDRESS MVS ’EXECIO 1 DISKR ’DDNAME /* PUT 1ST LINE ON STACK */
DO WHILE RC=0 /* WHILE RC = 0 */
PULL RECORD /* PULL LINE FROM STACK */
SAY SUBSTR(RECORD,1,68) /* DISPLAY LINE TO USER */
/* PUT NEXT LINE ON STACK*/
ADDRESS MVS ’EXECIO 1 DISKR ’DDNAME
END /* WHILE RC = 0 */
/* PUT OUT COMPLETE MSG */
’MESSAGE 309I TYPE CLIST IS NOW FINISHED’
END /* PROCESS CNM272I MSG */
END /* NAME WAS SPECIFIED */
RETURN /* RETURN TO CALLER/EXIT */
EXIT -1; /* END COMMAND LIST FOR ERROR*/
Figure 62. TYPE Example
TYPEIT Example
Figure 63 on page 175 is an example of a command list that does essentially the
same thing as the example in Figure 62, but closes the data set in case of error.

/**********************************************************************/
/* TYPE COMMAND LIST */
/* ----------------- */
/* */
/* FUNCTION: THIS COMMAND LIST DISPLAYS MEMBERS OF A DATA SET AT THE */
/* (INVOKING) USER’S NETVIEW TERMINAL ONE LINE AT A TIME. */
/* */
/* */
/* OUTPUT: LINE = EACH LINE WITHIN THE MEMBER SPECIFIED BY THE USER. */
/**********************************************************************/
signal on error
rc = 0
parse arg datasetname ’(’ member ’)’ extra
if datasetname = ’’ | parmcnt() > 1 | member = ’’ | extra ¬= ’’ then
do
say ’Incorrect syntax used.’
say ’Correct syntax is : ’
say ’ TYPE dataset.name(member) ’
rc = 24
end
else
do
’trap and suppress only messages CNM272I’
signal on halt
’allocate da(’datasetname’(’member’)) shr’
’wait 5 seconds for messages’
’msgread’
if msgid() = ’CNM272I’ then
do
ddname = msgvar(1)
if fndmbr(ddname,member) ¬= 0 then
do
say ’Member’ member ’does not exist.’
rc = 4
end
else
do
address mvs ’execio * diskr’ ddname ’(finis’
do while queued() ¬= 0
pull record
say substr(record,1,68)
end
signal off halt
’free file(’ddname’)’
’trap no messages’
’message 309I ’’TYPEIT’’,’’clist is now finished.’’’
end
end
end
return rc
halt:
’free file(’ddname’)’
’trap no messages’
return -5
error: say ’Error occurred. Return code is’ rc
return -1
Figure 63. TYPEIT Example

Support information
If you have a problem with your IBM software, you want to resolve it quickly. This
section describes the following options for obtaining support for IBM software
products:
v “Searching knowledge bases”
v “Obtaining fixes” on page 178
v “Receiving weekly support updates” on page 178
v “Contacting IBM Software Support” on page 179
Additional support for the NetView for z/OS product is available at the following
locations:
v At the NetView for z/OS Web site at
http://www.ibm.com/software/tivoli/products/netview-zos/. Under Related
links, click Other online sources. The page displayed contains a list of
newsgroups, forums, and bulletin boards.
v 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.
Searching knowledge bases

You can search the available knowledge bases to determine whether your problem
was already encountered and is already documented.
Searching the information center

IBM provides extensive documentation that can be installed on your local
computer or on an intranet server.
An index is provided for searching the Tivoli NetView for z/OS library. If you
have Adobe Acrobat on your system, you can use the Search command to locate
specific text in the library. For more information about using the index to search
the library, see the online help for Acrobat.
Searching the Internet

If you cannot find an answer to your question in the information center, search the
Internet for the latest, most complete information that might help you resolve your
problem.
To search multiple Internet resources for your product, use the Web search topic in
your information center. In the navigation frame, click Troubleshooting and
support Searching knowledge bases and select Web search. From this topic, you
can search a variety of resources, including the following:
v IBM technotes
v IBM downloads
v IBM Redbooks™

v IBM developerWorks®
v Forums and newsgroups
v Google
Obtaining fixes
A product fix might be available to resolve your problem. To determine what fixes
are available for your IBM software product, follow these steps:
1. Go to the IBM Software Support Web site at
http://www.ibm.com/software/support
2. Under Product support pages A to Z, click I. This opens a software product
list.
3. In the software product list, click IBM Tivoli NetView for z/OS. This opens the
IBM Tivoli NetView for z/OS support site.
4. Under Self help, under Solve a problem, click APARs to go to a list of fixes,
fix packs, and other service updates for Tivoli NetView for z/OS.
5. Click the name of a fix to read the description and optionally download the fix.
You can also search for a specific fix; for tips on refining your search, click
Search tips.
For more information about the types of fixes that are available, see the IBM
Software Support Handbook at
http://techsupport.services.ibm.com/guides/handbook.html.
Receiving weekly support updates

To receive weekly e-mail notifications about fixes and other software support news,
follow these steps:
1. Go to the IBM Software Support Web site at
http://www.ibm.com/software/support.
2. Click My support in the upper right corner of the page.
3. If you have already registered for My support, sign in and skip to the next
step. If you have not registered, click register now. Complete the registration
form using your e-mail address as your IBM ID and click Submit.
4. Click Edit profile.
5. In the Products list, select Software. A second list is displayed.
6. In the second list, select a product segment, for example, Systems
Management. A third list is displayed.
7. In the third list, select a product sub-segment, for example, Network
Management & Performance. A list of applicable products is displayed.
8. Select one or more products for which you want to receive updates, for
example, IBM Tivoli NetView for z/OS.
9. Click Add products.
10. After selecting all products that are of interest to you, click Subscribe to email
on the Edit profile tab.
11. In the Documents list, select Software.
12. Select Please send these documents by weekly email.
13. Update your e-mail address as needed.
14. Select the types of documents that you want to receive information about.
15. Click Update.

If you experience problems with the My support feature, you can obtain help in
one of the following ways:
Online
Send an e-mail message to erchelp@ca.ibm.com, describing your problem.
By phone
Call 1-800-IBM-4You (1-800-426-4968).
Contacting IBM Software Support

IBM Software Support provides assistance with product defects.
Before contacting IBM Software Support, your company must have an active IBM
software maintenance contract, and you must be authorized to submit problems to
IBM. The type of software maintenance contract that you need depends on the
type of product you have:
v For IBM distributed software products (including, but not limited to, Tivoli,
Lotus®, and Rational® products, as well as DB2® and WebSphere® products that
run on Windows or UNIX operating systems), enroll in Passport Advantage® in
one of the following ways:
Online
Go to the Passport Advantage Web site at
http://www.lotus.com/services/passport.nsf/
WebDocs/Passport_Advantage_Home and click How to Enroll.
By phone
For the phone number to call in your country, go to the IBM Software
Support Web site at
http://techsupport.services.ibm.com/guides/contacts.html and click the
name of your geographic region.
v For customers with Subscription and Support (S & S) contracts, go to the
Software Service Request Web site at
https://techsupport.services.ibm.com/ssr/login.
v For customers with IBMLink™, CATIA, Linux, System/390®, iSeries™, pSeries®,
zSeries®, and other support agreements, go to the IBM Support Line Web site at
http://www.ibm.com/services/us/index.wss/so/its/a1000030/dt006.
v For IBM eServer™ software products (including, but not limited to, DB2 and
WebSphere products that run in zSeries, pSeries, and iSeries environments), you
can purchase a software maintenance agreement by working directly with an
IBM sales representative or an IBM Business Partner. For more information
about support for eServer software products, go to the IBM Technical Support
Advantage Web site at http://www.ibm.com/servers/eserver/techsupport.html.
If you are not sure what type of software maintenance contract you need, call
1-800-IBMSERV (1-800-426-7378) in the United States. From other countries, go to
the contacts page of the IBM Software Support Handbook on the Web at
http://techsupport.services.ibm.com/guides/contacts.html and click the name of
your geographic region for phone numbers of people who provide support for
your location.
Contacting IBM Software Support involves these steps:

1. “Determining the business impact” on page 180
2. “Describing problems and gathering information” on page 180
3. “Submitting problems” on page 180
Support information 179

Determining the business impact
When you report a problem to IBM, you are asked to supply a severity level.
Therefore, you need to understand and assess the business impact of the problem
you are reporting. Use the following criteria:
Severity 1
The problem has a critical business impact. You are unable to use the
program, resulting in a critical impact on operations. This condition
requires an immediate solution.
Severity 2
The problem has a significant business impact. The program is usable, but
it is severely limited.
Severity 3
The problem has some business impact. The program is usable, but less
significant features (not critical to operations) are unavailable.
Severity 4
The problem has minimal business impact. The problem causes little impact
on operations, or a reasonable circumvention to the problem was
implemented.
Describing problems and gathering information

When describing a problem to IBM, be as specific as possible. Include all relevant
background information so that IBM Software Support specialists can help you
solve the problem efficiently. To save time, know the answers to these questions:
v What software versions were you running when the problem occurred?
v Do you have logs, traces, and messages that are related to the problem
symptoms? IBM Software Support is likely to ask for this information.
v Can you re-create the problem? If so, what steps were performed to re-create the
problem?
v Did you make any changes to the system? For example, did you make changes
to the hardware, operating system, networking software, and so on.
v Are you currently using a workaround for the problem? If so, be prepared to
explain the workaround when you report the problem.
Submitting problems
You can submit your problem to IBM Software Support in one of two ways:
Online
Click Submit and track problems on the IBM Software Support site at
http://www.ibm.com/software/support/probsub.html. Type your
information into the appropriate problem submission form.
By phone
For the phone number to call in your country, go to the contacts page of
the IBM Software Support Handbook at
http://techsupport.services.ibm.com/guides/contacts.html and click the
name of your geographic region.
If the problem you submit is for a software defect or for missing or inaccurate
documentation, IBM Software Support creates an Authorized Program Analysis
Report (APAR). The APAR describes the problem in detail. Whenever possible,
IBM Software Support provides a workaround for you to implement until the
APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the

IBM product support Web pages daily, so that other users who experience the
same problem can benefit from the same resolution.
Support information 181

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:
IBM World Trade Asia Corporation

Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, 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
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.
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.
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.
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, Advanced Peer-to-Peer Networking, AIX, BookManager, Candle
Management Server, CandleNet Portal, CICS, DB2, developerWorks, eServer,
IBMLink, IMS, iSeries, Lotus, MVS, MVS/DFP, MVS/ESA, MVS/XA, NetView,
Passport Advantage, pSeries, RACF, Rational, Redbooks, S/390, SAA, System/390,
Tivoli, Tivoli Enterprise, Tivoli Enterprise Console, VM/ESA, VSE/ESA, VTAM,
WebSphere, z/OS, z/VM, and zSeries are trademarks or registered trademarks of
International Business Machines Corporation in the United States, other countries,
or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
Intel and the Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino
logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or
registered trademarks of Intel Corporation or its subsidiaries in the United States
and other countries.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Linux is a trademark of Linus Torvalds in the United States, other countries, or

both.
Other company, product, and service names may be trademarks or service marks
of others.
Notices 185
Index
Special characters &MSGCSPLX control variable 58
&MSGCSYID control variable 58
/*%DATA directive 20 &MSGDOMFL control variable 58
/*%LOGIC directive 20 &MSGGBGPA control variable 58
&1 - &31 parameter variables 134 &MSGGDATE control variable 58
&ACTIONDL control variable 49 &MSGGFGPA control variable 59
&ACTIONMG control variable 49 &MSGGMFLG control variable 59
&APPLID control variable 78 &MSGGMID control variable 59
&AREAID control variable 55 &MSGGSEQ control variable 59
&ASID control variable 78 &MSGGSYID control variable 59
&ATTENDED control variable 78 &MSGGTIME control variable 59
&ATTNID control variable 49 &MSGID control variable 52
&AUTCONID control variable 78 &MSGITEM control variable 52
&AUTOTASK control variable 78 &MSGORIGIN control variable 53
&AUTOTOKE control variable 55 &MSGSRCNM control variable 60
&BEGWRITE control statement 107 &MSGSTR control variable 53
&BITAND built-in function 111 &MSGTOKEN control variable 60
&BITOR built-in function 112 &MSGTSTMP control variable 54
&BITXOR built-in function 113 &MSGTYP control variable 60
&CART control variable 55 &MSUSEG built-in function 117
&CGLOBAL control statement 143 &MVSLEVEL control variable 79
&CONCAT built-in function 113 &MVSRTAIN variable 54
&CONTROL control statement 104 &NCCFCNT control variable 45
&CURCONID control variable 78 &NCCFID built-in function 46, 118
&CURSYS control variable 78 &NCCFSTAT built-in function 46, 119
&DATE control variable 83 &NETVIEW control variable 79
&DESC control variable 55 &NVDELID control variable 54
&DISC control variable 79 &OPID control variable 77
&DISTAUTO control variable 79 &OPSYSTEM control variable 80
&DOMAIN control variable 79 &PARMCNT control variable 45
&EXIT control statement 125 &PARMSTR control variable 45
&GOTO control statement 125 &PARTID control variable 80
&HCOPY control variable 82 &PAUSE control statement 108
&HDRMTYPE control variable 49 &PRTY control variable 60
&IF control statement 123 &REPLYID control variable 54
&IFRAUGMT control variable 49 &RETCODE control variable 45
&IFRAUI3X control variable 50 &RXDEFENV control variable 82
&IFRAUIN3 control variable 50 &RXDEFSTR control variable 82
&IFRAUIND control variable 50 &RXNUMENV control variable 82
&IFRAUSB2 control variable 50 &RXOVRENV control variable 82
&IFRAUSC2 control variable 50 &RXOVRSTR control variable 82
&IFRAUSDR control variable 50 &SESSID control variable 54
&IFRAUSRB control variable 50 &SMSGID control variable 61
&IFRAUSRC control variable 51 &STCKGMT control variable 80
&IFRAUTA1 control variable 51 &SUBSTR built-in function 120
&IFRAUWF1 control variable 51 &SUPPCHAR control variable 80
&JOBNAME control variable 55 &SYSCONID control variable 61
&JOBNUM control variable 55 &SYSID control variable 61
&KEY control variable 55 &SYSPLEX control variable 80
&LENGTH built-in function 116 &TASK control variable 80
&LINETYPE control variable 51 &TGLOBAL control statement 142
&LU control variable 82 &THEN clause, &IF control statement 124
&MCSFLAG control variable 56 &TIME control variable 83
&MSGASID control variable 56 &VTAM control variable 81
&MSGAUTH control variable 56 &VTCOMPID control variable 81
&MSGCATTR control variable 56 &WAIT control statement 127
&MSGCMISC control variable 56 &WEEKDAYN control variable 81
&MSGCMLVL control variable 57 &WRITE control statement 105
&MSGCMSGT control variable 57 &WTOREPLY control variable 61
&MSGCNT control variable 57
&MSGCOJBN control variable 57
&MSGCPROD control variable 57

A B
accessibility xi BEGWRITE control statement 107
Acrobat Search command (for library search) ix, 177 blanks stripping 83
ACTAPPLS example books
REXX 163 see publications vii, x
ACTIONDL built-in function
NetView command list language control variable 49 NetView command list language
REXX function 49 assignment statement 103
ACTIONMG built-in function, &HIER 114
NetView command list language control variable 49 built-in functions
REXX function 49 NetView command list language
activating command lists 2 &BITAND 111
ACTLU example &BITOR 112
REXX 165 &BITXOR 113
ADDRESS instruction 26 &CONCAT 113
AFTER command, scheduling command lists 7 &HIER 114
ALL, &CONTROL operand 105 &LENGTH 116
ALLOCATE, NetView command 28 &MSUSEG 117
allocating data sets, NetView 28 &NCCFID 46, 118
APPLID &NCCFSTAT 46, 119
NetView command list language control variable 78 &SUBSTR 120
REXX function 78 definition 111
AREAID REXX 15
NetView command list language control variable 55
REXX function 55
WTO command 55
arithmetic operations, assignment statements 103
C
C command procedures, nesting REXX command lists 29
ASID
CALL instruction, using 25
calling another command list 7
REXX function 78
CART
Assembler command processors, nesting REXX command
lists 29
REXX function 55
assignment
WTO, WTOR commands 55
clauses, REXX 15
CGI
statements, NetView command list language 102
REXX function 78
AT command, scheduling command lists 7
CGLOBAL
ATTENDED
control statement 143
REXX function 48
REXX function 78
CHKOPNUM, example command list 165
ATTNID
CHKRSTAT, example command list 167
CHRON command, scheduling command lists 7
REXX function 49
clauses, REXX 15
AUTBYPAS
CLEAR command 106
REXX function 40
CMD
AUTCONID
&CONTROL operand 105
command 11
REXX function 78
CMDNAME
AUTHCHK
REXX function 44
REXX function 41
CMDSYN statement 2
AUTHCHKX
code points, translating 38
REXX function 43
coding conventions
AUTODROP command, REXX 5
NetView command list language
automation task 13
continuation statements 92
automation, message 85
double-byte character text 93
AUTOTASK
suppression character conventions 93
syntax 91
OST restrictions 13
REXX
REXX function 78
coding non-REXX commands, REXX command list 21
AUTOTBL command 85
record size 21
AUTOTOKE
suppressing display, non-REXX command 23
syntax 21
REXX function 55
command list information
AUTOWRAP setting 12
NetView command list language control variables 40
REXX functions 40
command list language, NetView 1

command lists common global variables
activating 2 NetView command list language 143
commands used in 160 common operations services (COS) commands 149
compiling command lists 16 comparing NetView command list language, REXX 155
creating 2 CONCAT built-in function 113
creating data sets, MVS 3 constants, assignment statements 102
definition 1 continuation statements 92
display, controlling during processing 13 CONTINUE, &WAIT operand 135
loading, main storage 4 CONTROL control statement 104
long-running commands, using 10 control statements, NetView command list language
message driven 85 &BEGWRITE 107
naming 3 &CGLOBAL 143
nested 7 &CONTROL 104
network commands, using 10 &EXIT 125
Network Control Program, activating 2 &GOTO 125
overview 1 &IF 123
restrictions under PPT 12 &PAUSE 108
routing messages 85 &TGLOBAL 142
running 5 &WAIT 127
startup, examples 2 &WRITE 105
system commands, using 10 comparison, REXX instructions 155
updating 2 definition 104
using 1 control variables, NetView command list language
commands &1 – &31 134
AFTER 7 &ACTIONDL 49
ALLOCATE 28 &ACTIONMG 49
AT 7 &APPLID 78
AUTODROP 5 &AREAID 55
AUTOTBL 85 &ASID 78
CHRON 7 &ATTENDED 78
CMD 11 &ATTNID 49
common operations services &AUTCONID 78
LINKDATA 150 &AUTOTASK 78
LINKPD 151 &AUTOTOKE 55
LINKTEST 150 &CART 55
RUNCMD 152 &CURCONID 78
DEFAULTS 6 &CURSYS 78
EVERY 7 &DATE 83
EXECIO 27 &DESC 55
FREE 28 &DISC 79
full-screen 12 &DISTAUTO 79
GO 133 &DOMAIN 79
hardware monitor, using command lists 10 &HCOPY 82
MSGROUTE 85 &HDRMTYPE 49
network 10 &IFRAUGMT 49
operator &IFRAUI3X 50
AFTER 7 &IFRAUIN3 50
AT 7 &IFRAUIND 50
CHRON 7 &IFRAUSB2 50
EVERY 7 &IFRAUSC2 50
running command lists 7 &IFRAUSDR 50
OVERRIDE 6 &IFRAUSRB 50
RESET 133 &IFRAUSRC 51
RETURN 10 &IFRAUTA1 51
session monitor, using command lists 10 &IFRAUWF1 51
STACK 133 &JOBNAME 55
status monitor, using command lists 10 &JOBNUM 55
system 10 &KEY 55
TRACE END (TE) 30 &LINETYPE 51
TRACE START (TS) 30 &LU 82
UNSTACK 133 &MCSFLAG 56
VIEW 11 &MSGASID 56
VTAM 10 &MSGAUTH 56
comments &MSGCATTR 56
NetView command list language 101 &MSGCMISC 56
REXX 15 &MSGCMLVL 57
&MSGCMSGT 57
Index 189
control variables, NetView command list language (continued) CURSYS
&MSGCNT 57 NetView command list language control variable 78
&MSGCOJBN 57 REXX function 78
&MSGCPROD 57 customer support 179
&MSGCSPLX 58
&MSGCSYID 58
&MSGDOMFL 58
&MSGGBGPA 58
D
DATA (%DATA) directive 20
&MSGGDATE 58
Data REXX 16
&MSGGFGPA 59
/*%DATA directive 20
&MSGGMFLG 59
/*%LOGIC directive 20
&MSGGMID 59
host command environment 27
&MSGGSEQ 59
processing 20
&MSGGSYID 59
data set information functions 46
&MSGGTIME 59
data set, information functions 46
&MSGID 52
data set, MVS 3
&MSGORIGIN 53
DATE control variable 83
&MSGSRCNM 60
DBCS 93
&MSGSTR 53
deallocating data sets, NetView 28
&MSGTOKEN 60
DEFAULTS command 6
&MSGTSTMP 54
DESC
&MSGTYP 60
&MVSLEVEL 79
REXX function 55
&MVSRTAIN 54
WTO, WTOR commands 55
&NCCFCNT 45
developerWorks, searching for problem resolution in IBM 177
&NETID 79
directory names, notation xiii
&NETVIEW 79
DISC
&NVDELID 54
&OPID 77
REXX function 79
&OPSYSTEM 80
DISPLAY
&PARMCNT 45
&WAIT operand 135
&PARMSTR 45
display, controlling 13
&PARTID 80
displaying panels 11
&PRTY 60
DISTAUTO
&REPLYID 54
&RETCODE 45
REXX function 79
&RXDEFENV 82
DOMAIN
&RXDEFSTR 82
&RXNUMENV 82
REXX function 79
&RXOVRENV 82
domain information, REXX functions 45
&RXOVRSTR 82
double-byte character set characters (DBCS)
&SESSID 54
&CONCAT, using 113
&SMSGID 61
&SUBSTR, using 121
&STCKGMT 80
coding conventions, NetView command list language 93
&SUPPCHAR 80
PPT, command list 13
&SYSCONID 61
DOUBLESUPP character 94
&SYSID 61
DROPCL 5
&SYSPLEX 80
DSPRSTAT, example command list 169
&TASK 80
&TIME 83
&VTAM 81
&VTCOMPID 81 E
&WAIT, using 133 ECVTPSEQ
&WEEKDAYN 81 REXX function 79
&WTOREPLY 61 editing facilities, updating command lists 2
comparing REXX functions 156 education
definition 100 see Tivoli technical training xi
MSGITEM(n) 52 ENDWAIT, &WAIT operand 132, 135
CONTWAIT, &WAIT operand 135 ENVDATA
conventions REXX function 79
typeface xiii environment addressed by REXX, changing 26
COS return codes 150 environment variables, notation xiii
creating command lists 2 ERR, &CONTROL operand 105
CURCONID ERROR, &WAIT operand 131
NetView command list language control variable 78 errors, handling
REXX function 78 NetView command list language 132
REXX 31

EVENT functions (continued)
REXX function 49 REXX (continued)
event=-label pairs, &WAIT control statement 128, 132 comparison, NetView command list language control
EVERY command, scheduling command lists 7 variables 156
examples CURCONID() 78
ACTAPPLS CURSYS() 78
REXX 163 DESC() 55
ACTLU DISC() 79
REXX 165 DISTAUTO() 79
command list using DOMAIN() 79
&WAIT 138 ECVTPSEQ() 79
command lists ENVDATA() 79
reference, define, update task global variables 144 EVENT() 49
GETCG FNDMBR() 46
REXX 170 HCOPY() 82
GLOBVAR1 148 HDRMTYPE() 49
GREETING HIER(n) 63
REXX 171 HMEPNAU 65
LISTVAR HMEPNET 65
REXX 172 HMEPNETV 66
MSUSEG 76 HMFWDSNA 67
NPDABA 77 IFRAUGMT() 49
REXX command lists, NetView IFRAUI3X() 50
CHKOPNUM 165 IFRAUIN3() 50
CHKRSTAT 167 IFRAUIND() 50
DSPRSTAT 169 IFRAUSB2() 50
PRINT 172 IFRAUSC2() 50
TYPE 174 IFRAUSDR() 50
TYPEIT 174 IFRAUSRB() 50
startup command lists 2 IFRAUSRC() 51
EXECIO command, REXX command list 27 IFRAUTA1() 51
EXIT control statement 125 IFRAUWF1() 51
expressions JOBNAME() 55
NetView command list language 102 JOBNUM() 55
REXX 15 KEY() 55
LINESIZE() 25
LINETYPE() 51
F LU() 82
MCSFLAG() 56
fixes, obtaining 178
MSGASID() 56
FNDMBR, REXX function 46
MSGAUTH() 56
FREE, NetView command 28
MSGCATTR() 56
full-screen commands, using 12
MSGCMISC() 56
function packages, REXX, writing 26
MSGCMLVL() 57
functions
MSGCMSGT() 57
built-in
MSGCNT() 57
NetView command list language 111
MSGCOJBN() 57
REXX 15
MSGCPROD() 57
REXX
MSGCSPLX() 58
ACTIONDL() 49
MSGCSYID() 58
ACTIONMG() 49
MSGDOMFL() 58
APPLID() 78
MSGGBGPA() 58
AREAID() 55
MSGGDATE() 58
ASID() 78
MSGGFGPA() 59
ATTENDED() 78
MSGGMFLG() 59
ATTNID() 49
MSGGMID() 59
AUTBYPAS 40
MSGGSEQ() 59
AUTCONID() 78
MSGGSYID() 59
AUTHCHK() 41
MSGGTIME() 59
AUTHCHKX() 43
MSGID() 52
AUTOTASK() 78
MSGITEM(n) 52
AUTOTOKE() 55
MSGORIGN() 53
CART() 55
MSGREAD 35
CGI() 78
MSGSRCNM() 60
CGLOBAL() 48
MSGSTR() 53
CMDNAME() 44
MSGTOKEN() 60
CODE2TXT() 38
MSGTSTMP() 54
Index 191
functions (continued)
REXX (continued)
H
MSGTYP() 60 hardware monitor commands, using 10
MSGVAR(n) 54 HCOPY
MSUSEG() 71 NetView command list language control variable 82
MVSLEVEL 79 REXX function 82
MVSRTAIN() 54 HDRMTYPE
NETID() 79 NetView command list language control variable 49
NETVIEW() 79 REXX function 49
NPDABA() 71 hexadecimal notation (NetView command list language) 101
NVCNT() 45 HIER function
NVDELID() 54 NetView command list language 114
NVID(n) 46 REXX 63
NVSTAT() 46 HMEPNAU function 65
OPID() 77 HMEPNET function 65
OPSYSTEM() 80 HMEPNETV function 66
PANEL() 80 HMFWDSNA function 67
PARMCNT() 45
PARTID() 80
PRTY() 60 I
REPLYID() 54 IBM developerWorks, searching for problem resolution in 177
restrictions 25 IBM Redbooks, searching for problem resolution in 177
ROUTCDE() 61 IBM technotes, searching for problem resolution in 177
RXDEFENV() 82 IF control statement 123
RXDEFSTR() 82 IFRAUGMT
RXNUMENV() 82 NetView command list language control variable 49
RXOVRENV() 82 REXX function 49
RXOVRSTR() 82 IFRAUI3X
SESSID() 54 NetView command list language control variable 50
SMSGID() 61 REXX function 50
STCKGMT() 80 IFRAUIN3
STORAGE() 25 NetView command list language control variable 50
SUBSYM() 40 REXX function 50
SUPPCHAR() 80 IFRAUIND
SYSCONID() 61 NetView command list language control variable 50
SYSID() 61 REXX function 50
SYSPLEX() 80 IFRAUSB2
TASK() 80 NetView command list language control variable 50
TGLOBAL() 48 REXX function 50
TOWER() 81 IFRAUSC2
TYPE() 81 NetView command list language control variable 50
VTAM() 81 REXX function 50
VTCOMPID() 81 IFRAUSDR
WEEKDAYN() 81 NetView command list language control variable 50
WTOREPLY 61 REXX function 50
functions, data set information 46 IFRAUSRB
REXX function 50
G IFRAUSRC
GETCG example NetView command list language control variable 51
REXX 170 REXX function 51
global variable information functions 48 IFRAUTA1
global variables NetView command list language control variable 51
common REXX function 51
NetView command list language 143 IFRAUWF1
task NetView command list language control variable 51
NetView command list language 142 REXX function 51
GLOBALV index for searching the library ix, 177
instruction information centers, searching for problem resolution 177
NetView command list language 148 information function, MSU 62
GLOBVAR1 example 148 initialization, running command lists 6
GO command 133 instructions, REXX
GOTO control statement 125 ADDRESS 26
GREETING example CALL 25
REXX 171 comparison, NetView command list language control
statements 155
definition 15

instructions, REXX (continued) manuals
PARSE 24 see publications vii, x
restrictions 24 MAPCL 5
SAY 22, 25 MCSFLAG
SIGNAL 31 NetView command list language control variable 56
TRACE END 30 REXX function 56
TRACE START 30 MEMSTORE 4
Internet MEMSTOUT 4
searching for problem resolution 177 message
=-label pairs, coding 128, 132
automating responses 85
J multiline, working 130
processing information
JOBNAME
REXX functions 48
routing, command list 85
REXX function 55
sending, operators 105
JOBNUM
waiting, command lists
REXX function 55
message automation
command lists
defining 85
K error handling 88
KEY running 6
NetView command list language control variable 55 testing 86
REXX function 55 implementing 85
knowledge bases, searching for problem resolution 177 message retrieval tool, LookAt x
midnight 82
MSGASID
L NetView command list language control variable 56
REXX function 56
labels
MSGAUTH
REXX 15
REXX function 56
LENGTH built-in function 116
MSGCATTR
library search (Acrobat Search command) ix, 177
LINESIZE function 25
REXX function 56
LINETYPE
MSGCMISC
REXX function 51
REXX function 56
LINKDATA command 150
MSGCMLVL
LINKPD command 151
LINKTEST command 150
REXX function 57
LISTVAR example
MSGCMSGT
REXX 172
LOADCL 5
REXX function 57
loading command lists, storage 4
MSGCNT
LOGIC (%LOGIC) directive 20
NetView command list language control statement 52, 57
logon, operator, automatically running command lists 6
REXX function 57
long-running commands 10
MSGCOJBN
queuing 11
LookAt message retrieval tool x
REXX function 57
LU
MSGCPROD
REXX function 82
REXX function 57
MSGCSPLX
M REXX function 58
management services unit (MSU) functions MSGCSYID
&HIER 114 NetView command list language control variable 58
&MSUSEG 117 REXX function 58
HIER() 63 MSGDOMFL
MSUSEG() 71 NetView command list language control variable 58
NetView command list language 111, 114, 117 REXX function 58
NPDABA() 71 MSGGBGPA
REXX 114, 117 NetView command list language control variable 58
management services units information function 62 REXX function 58
Index 193
MSGGDATE
N
REXX function 58 NCCFCNT NetView command list language control
MSGGFGPA variable 45
NetView command list language control variable 59 NCCFID
REXX function 59 built-in function 46, 118
MSGGMFLG NCCFSTAT built-in function 46, 119
NetView command list language control variable 59 nested command lists
REXX function 59 definition 7
MSGGMID NetView command list language, using &WAIT 134
NetView command list language control variable 59 REXX
REXX function 59 Assembler, C, PL/I command procedures 29
MSGGSEQ using MSGREAD 35
NetView command list language control variable 59 using TRAP 34
REXX function 59 using WAIT 34
MSGGSYID testing 8
NetView command list language control variable 59 NETVIEW
REXX function 59 NetView command list language control variable 79
MSGGTIME REXX function 79
NetView command list language control variable 59 NetView command list language
REXX function 59 coding conventions 91
MSGID comments 101
REXX function 52 comparison, REXX 155
MSGITEM, NetView command list language control features 91
variable 52 functions, built-in 103
MSGITEM, REXX function 52 labels 94
MSGORIGIN, NetView command list language control null statements 102
variable 53 variables 95
MSGORIGN, REXX function 53 NetView commands
MSGREAD using &PAUSE 109
setting functions 35 using &WAIT 132
MSGROUTE command 85 network commands, using 10
MSGSRCNM network control program, activating, command lists 2
NetView command list language control variable 60 newsgroups xii
REXX function 60 NOINPUT, &PAUSE operand 109
MSGSTR NOSUB, &BEGWRITE operand 107
NetView command list language control variable 53 notation
REXX function 53 environment variables xiii
MSGTOKEN path names xiii
NetView command list language control variable 60 typeface xiii
REXX function 60 NPDABA function 71
MSGTSTMP REXX usage examples 76
NetView command list language control variable 54 null statements 102
REXX function 54 nulls stripping 83
MSGTYP NVCNT function 45
NetView command list language control variable 60 NVDELID
MSGVAR, REXX function 54 REXX function 54
MSU (management services unit) functions NVID function 46
NetView command list language (built-in functions) 111 NVSTAT function 46
REXX 114
MSU information function 62
MSUSEG function 71, 117 O
REXX usage examples 74 online publications
multiline messages, using 130 accessing x
MVS operands
command 10 ALL, &CONTROL control statement 105
creating data sets 3 CMD, &CONTROL control statement 105
message processing information 55 CONTINUE, &WAIT control statement 135
MVSLEVEL CONTWAIT, &WAIT control statement 135
NetView command list language control variable 79 DISPLAY
REXX function 79 &WAIT control statement 135
MVSRTAIN ENDWAIT, &WAIT control statement 132, 135
NetView command list language control variable 54 ERR, &CONTROL control statement 105
REXX function 54 ERROR, &WAIT control statement 131
NOINPUT, &PAUSE control statement 109
NOSUB, &BEGWRITE control statement 107

operands (continued)
STRING, &PAUSE control statement 109
Q
SUB, &BEGWRITE control statement 108 queuing long-running commands 11
SUPPCHAR 80 quotation marks, REXX command lists or Data REXX files 21
SUPPRESS
&WAIT control statement 135
VARS, &PAUSE control statement 109 R
operator record size
command, running command lists 7 NetView command list language 92
information REXX 21
NetView command list language control variables 77 Redbooks, searching for problem resolution in IBM 177
REXX functions 77 REPLYID
input, REXX command list 24 NetView command list language control variable 54
logon, command list 6 REXX function 54
sending messages 105 RESET command 133
OPID Restructured Extended Executor (REXX) language
NetView command list language control variable 77 command lists
REXX function 77 coding non-REXX commands 23
OPSYSTEM compiling 15
NetView command list language control variable 80 environment functions 82
REXX function 80 environment, changing 26
ordering publications xi errors, recovering 31
OST, autotask, restrictions 13 examples 163
OVERRIDE command 6 EXECIO command, using 27
nesting assembler, C, PL/I command procedures 29
operator input, pausing 24
P parsing 29
PANEL restrictions 24
REXX function 80 SAY instruction, using 22
panels, displaying 11 suppressing non-REXX commands 23
parameter variables, NetView command list language tracing 30
&WAIT, using 133 TSO/E environments 28
characteristics 96 command lists and data REXX files
nested command lists, using 98 SAY instruction, using 25
null 99 command lists and Data REXX files
passing, command list 97 coding conventions 21
quoted strings, using 99 return codes 30
special characters, using 99 command lists or Data REXX files
PARMCNT CALL instruction, using 25
NetView command list language control variable 45 LINESIZE function, using 25
REXX function 45 record size 21
PARMSTR control variable 45 restrictions 25
PARSE instruction 24 STORAGE function, using 25
parsing trailing blanks 21
REXX command lists 29 comparison, NetView command list language 155
PARTID function packages, writing 26
NetView command list language control variable 80 introduction 15
REXX function 80 RETCODE control variable 45
path names, notation xiii return codes
PAUSE control statement, using NetView commands 108, 109 COS 150
pausing, REXX command list 24 NetView command list language 45
PL/I command procedures, nesting REXX commands 29 REXX 30
PPT restrictions 12 RETURN command, REXX restrictions 10
PRINT, example command list 172 ROUTCDE
problem determination NetView command list language control variable 61
describing problems 180 REXX function 61
determining business impact 180 RUNCMD command 152
submitting problems 180 running command lists
PROFILE statement 6 another command list 7
PRTY NetView is started 6
NetView command list language control variable 60 NetView receives messages 6
REXX function 60 operator command 7
publications vii operator logon 6
accessing online x specified time 7
ordering xi user-written command procedure 9
RXDEFENV
Index 195
RXDEFENV (continued) SYSID
RXDEFSTR REXX function 61
NetView command list language control variable 82 SYSPLEX
RXNUMENV REXX function 80
NetView command list language control variable 82 system commands, using 10
REXX function 82
RXOVRENV
NetView command list
REXX function 82
language control variable 82 T
TAF
RXOVRSTR
session example 2
TASK
REXX function 82
REXX function 80
task global variables
S command list examples, reference, define, update 144
SAY instruction, using 22, 25 NetView command list language 142
scope checking TE command 30
variables, NetView command list language 145 technotes, searching for problem resolution in IBM 177
search command, Acrobat (for library search) ix, 177 terminal information
SECURITY NetView command list language control variables 82
controlling access, command lists 4 REXX functions 82
running command lists when NetView is started 6 TGLOBAL
using network commands in command lists 10 control statement 142
SESSID REXX function 48
NetView command list language control variable 54 THEN clause, &IF control statement 124
REXX function 54 TIME control variable 83
session time intervals, running command lists 7
information Tivoli software information center x
NetView command list language control variables 77 Tivoli technical training xi
REXX functions 77 tokens, message
monitor commands, command list 10 NetView command list language 129
TAF example 2 TOWER
SIGNAL instruction 31 REXX function 81
SMSGID TRACE END command 30
NetView command list language control variable 61 TRACE START command 30
REXX function 61 tracing, REXX command lists 30
Software Support training, Tivoli technical xi
contacting 179 translating code points 38
describing problems 180 translation functions
determining business impact 180 code-to-text function (CODE2TXT) 38
receiving weekly updates 178 translation tables, code-to-text 38
submitting problems 180 TRAP
STACK command 133 REXX command list 34
status monitor commands, command list 10 TS command 30
STCKGMT TSO/E environment 28
NetView command list language control variable 80 TSO/E EXECIO command 27
REXX function 80 TYPE
STORAGE function 25 REXX function 81
STRING, &PAUSE operand 109 TYPE, command list example 174
stripping, nulls and blanks 83 typeface conventions xiii
SUB, &BEGWRITE operand 108 TYPEIT, command list example 174
SUBSTR built-in function 120
SUBSYM, REXX function 40
SUPPCHAR 80, 93
SUPPCHAR control variable 80
U
UNSTACK command 133
SUPPRESS
user group on Yahoo, NetView 177
&WAIT operand 135
user variables 100
suppressing
user-written command procedure, activating command lists 9
messages 85
non-REXX commands, REXX command lists 23
suppression characters 93
SYSCONID V
NetView command list language control variable 61 variables
REXX function 61 command list information

variables (continued)
command list information (continued)
REXX 40
operator information
REXX 77
session information
REXX 77
substitution order 95
terminal information
REXX 82
user 100
variables, notation for xiii
VARS, &PAUSE operand 109
VIEW command 11
VTAM
commands 10
REXX function 81
VTCOMPID
REXX function 81
W
WAIT
NetView command list language control statement
coding suggestions 137
control and parameter variables 133
customizing 135
ending 132, 137
general 127
nested command lists, using 134
NetView commands, using 132
sample using 138
REXX instruction
nested REXX command lists, using 34
Web site, NetView 177
WEEKDAYN
REXX function 81
WRITE control statement 105
WTOREPLY 61
Index 197

File Number: S370/4300/30XX-50

Program Number: 5697–ENV
Printed in USA
SC31-8862-01

Rexx PDF

Uploaded by

Copyright:

Available Formats

Rexx PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Rexx PDF

Uploaded by

Copyright:

Available Formats

Tivoli IBM Tivoli NetView for z/OS

Programming: REXX and the NetView Command List Language

Programming: REXX and the NetView Command List Language

Second Edition (October 2005)

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

Chapter 2. REXX Language Overview . . . . . . . . . . . . . . . . . . . . . . 15

© Copyright IBM Corp. 1997, 2005 iii

Chapter 3. REXX Instructions for Command Lists Run in a NetView Environment . . . 33

Chapter 5. Automation Resource Management . . . . . . . . . . . . . . . . . . 85

iv Programming: REXX and the NetView Command List Language

Appendix B. NetView Command List Language Branching . . . . . . . . . . . . . 123

Appendix C. NetView Command List Language Global Variables . . . . . . . . . . 141

Appendix D. Common Operations Services Commands . . . . . . . . . . . . . . 149

Appendix E. Comparison of REXX and NetView Command List Language . . . . . . 155

Appendix F. Command List Examples Index . . . . . . . . . . . . . . . . . . . 161

Appendix G. Examples of REXX Command Lists for NetView . . . . . . . . . . . . 163

Support information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

vi Programming: REXX and the NetView Command List Language

Note: This document does not provide descriptions of NetView operator

Who should read this guide

IBM Tivoli NetView for z/OS library

© Copyright IBM Corp. 1997, 2005 vii

viii Programming: REXX and the NetView Command List Language

Accessing terminology online

About this guide ix

When a reference is made about using a personal computer or workstation, any

Using LookAt to look up message explanations

Accessing publications online

x Programming: REXX and the NetView Command List Language

You can also order by telephone by calling one of these numbers:

In other countries, contact your software account representative to order Tivoli

Tivoli technical training

About this guide xi

IBM Tivoli NetView for z/OS:

Newsgroups for related products:

IBM Tivoli Business Systems Manager:

IBM Tivoli Enterprise Console®:

These applications can help with the following tasks:

Conventions used in this guide

xii Programming: REXX and the NetView Command List Language

Operating system-dependent variables and paths

Position and Appearance of Syntax Elements

About this guide xiii

Required Syntax Elements

Figure 1. Required Syntax Elements

Optional Syntax Elements

Figure 2. Optional Syntax Elements

Default Keywords and Values

xiv Programming: REXX and the NetView Command List Language

Figure 3. Default Keywords and Values

PURGE BEFORE date

Figure 4. Syntax Fragments

About this guide xv

If a command requires positional commas to separate keywords and variables, the

xvi Programming: REXX and the NetView Command List Language

| Note: The use of REXX is recommended, as it has many functions and

This chapter describes how to:

The Benefits of Using Command Lists

© Copyright IBM Corp. 1997, 2005 1