IBM Tivoli NetView for z/OS Version 6 Release 1 Programming: REXX and the NetView Command List Language SC27-2861-01 IBM Tivoli NetView for z/OS Version 6 Release 1 Programming: REXX and the NetView Command List Language SC27-2861-01 Note Before using this information and the product it supports, read the information in “Notices” on page 203. This edition applies to version 6, release 1 of IBM Tivoli NetView for z/OS (product number 5697-NV6) and to all subsequent versions, releases, and modifications until otherwise indicated in new editions. This edition replaces SC27-2861-00. © Copyright IBM Corporation 1997, 2011. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Figures ...................................vii About this publication .............................ix Intended audience .................................ix Publications ...................................ix IBM Tivoli NetView for z/OS library ..........................ix Related publications ...............................xi Accessing terminology online ............................xi Using NetView for z/OS online help ..........................xii Using LookAt to look up message explanations ......................xii Accessing publications online ............................xiii Ordering publications...............................xiii Accessibility ...................................xiii Tivoli technical training ...............................xiv Tivoli user groups .................................xiv Downloads ...................................xiv Support information ................................xiv Conventions used in this publication ...........................xv Typeface conventions ...............................xv Operating system-dependent variables and paths......................xv Syntax diagrams ................................xvi 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 ...............................6 Running Command Lists When NetView Is Started .....................6 Running Command Lists When Logging On........................6 Running Command Lists after Receiving a Message or MSU ..................7 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 ....................8 Running Command Lists from a User-Written Command Processor ...............10 Using Network Commands in Command Lists .......................10 Using System Commands in Command Lists .......................10 Using Long-Running Commands in Command Lists.....................10 Using Tivoli NetView for z/OS Pipelines ........................11 Using the VIEW Command .............................12 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 ......................17 Introduction to the REXX Language ...........................17 Compiling and Running REXX Command Lists .......................17 Using %INCLUDE with Interpreted REXX .........................18 Using Data REXX .................................18 Processing Data REXX Files .............................20 Additional Information ..............................21 © Copyright IBM Corp. 1997, 2011 iii Data REXX Directives ...............................22 /*%DATA ...................................22 /*%LOGIC ..................................23 Coding Conventions for REXX Command Lists and Data REXX Files ................23 Record Size ..................................23 Using Quotation Marks ..............................24 Suppressing Display of Non-REXX Commands ......................26 Tivoli NetView for z/OS Restrictions on REXX Instructions ...................26 Pausing for Operator Input .............................26 Using the SAY Instruction .............................27 Using the CALL Instruction .............................27 NetView Restrictions on REXX Functions .........................28 Writing REXX Function Packages ............................28 Changing the Environment Addressed by REXX Command Lists .................28 Data REXX Host Command Environment .........................29 Using the EXECIO Command .............................29 Using MVS and VTAM Commands ...........................30 Using the NetView ALLOCATE and FREE Commands .....................30 Using REXX Command Lists .............................30 Nesting REXX Command Lists from Assembler, C, or PL/I ...................31 Parsing in REXX Command Lists ............................32 Tracing REXX Command Lists .............................32 Return Codes in REXX Command Lists ..........................33 Recovering from Errors in REXX Command Lists.......................33 Chapter 3. REXX Instructions for Command Lists Run in a NetView Environment . 35 Using TRAP in Nested REXX Command Lists ........................36 Using WAIT in Nested Command Lists ..........................36 Using MSGREAD in Nested Command Lists ........................37 Functions Set by MSGREAD..............................37 Chapter 4. REXX Instructions for NetView REXX Command Lists and Data REXX Files 39 Translation Functions ................................40 IP Address Processing ................................43 Command List Information ..............................44 Cross-Domain Information Functions ...........................49 Data Set Information Functions .............................50 Global Variable Information Functions ..........................52 Message Processing Information Functions .........................52 Message Processing Information ...........................53 ROUTCDE Examples ...............................65 Command Processing Information Functions ........................65 REXX Management Services Unit Information Functions ....................67 Hardware Monitor (HMxxxxxx) Examples ........................76 MSUSEG Syntax and Examples............................79 Probable Cause Syntax and Examples .........................81 Operator Information Functions ............................82 Session Information Functions .............................83 REXX Environment Information Functions .........................87 Terminal Information Functions ............................87 Time and Date Variables ...............................88 Nulls and Blanks Stripping ..............................88 Chapter 5. Automation Resource Management ..................91 Defining NetView Automation Table Command Lists .....................91 Routing Messages from Automation-Table-Driven Command Lists .................91 Implementing NetView Automation ...........................91 Suppressing Messages ...............................92 Determining the Environment for a Command List .....................92 Testing Automation Command Lists ..........................92 iv Programming: REXX and the NetView Command List Language Looping and Automation ..............................93 Considering Operator Interaction ...........................94 Common Automation Problems ...........................94 Appendix A. Writing Simple Command Lists in the NetView Command List Language 97 What the NetView Command List Language Includes .....................97 Coding Conventions for NetView Command List Language Statements ...............97 Conventions for General Coding ...........................98 Conventions for Continuing a Statement.........................98 Conventions for Double-Byte Character Set Text ......................99 Conventions for Suppression Characters .........................99 Labels .....................................100 Variables ....................................101 Variable Substitution Order.............................101 Parameter Variables ...............................102 Passing Parameter Variable Information to a Command List..................103 Using Parameter Variables in a Command List ......................103 Passing Parameter Variables to a Nested Command List ...................104 Using Quoted Strings or Special Characters in Parameter Variables ...............105 Null Parameter Values ..............................105 Control Variables ................................106 User Variables .................................106 Hexadecimal Notation ...............................107 Comments ...................................107 Null Statements .................................108 Assignment Statements ...............................108 Control Statements ................................110 &CONTROL Statement ..............................110 Writing to the Operator ..............................111 Using NetView Commands with &PAUSE........................115 An Example Using &PAUSE ............................116 NetView Built-in Functions ..............................117 &BITAND