IBM TSO/E REXX User manual

z/OS
TSO/E
REXX User’s Guide
SA22-7791-00


z/OS
TSO/E
REXX User’s Guide
SA22-7791-00


Note
Before using this information and the product it supports, be sure to read the general information under “Appendix D.
Notices” on page 205.
First Edition, March 2001
This edition applies to Version 1 Release 1 of z/OS (5694-A01) and to all subsequent releases and modifications
until otherwise indicated in new editions.
Order publications through your IBM representative or the IBM branch office serving your locality. Publications are
not stocked at the address below.
IBM welcomes your comments. A form for readers’ comments may be provided at the back of this publication, or you
may address your comments to the following address:
International Business Machines Corporation
Department 55JA, Mail Station P384
2455 South Road
Poughkeepsie, NY 12601-5400
United States of America
FAX (United States & Canada): 1+845+432-9405
FAX (Other Countries):
Your International Access Code +1+845+432-9405
IBMLink (United States customers only): IBMUSM10(MHVRCFS)
Internet e-mail: [email protected]
World Wide Web: http://www.ibm.com/servers/eserver/zseries/zos/webqs.html
If you would like a reply, be sure to include your name, address, telephone number, or FAX number.
Make sure to include the following in your comment or note:
vTitle and order number of this book
vPage number or topic related to your comment
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1988, 2001. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
Figures............................ix
Tables ............................xi
About This Book .......................xiii
Who Should Use This Book ....................xiii
How This Book Is Organized....................xiii
Terminology .........................xiii
Purpose of Each Chapter ....................xiv
Examples ..........................xiv
Exercises ..........................xiv
Where to Find More Information ..................xiv
Accessing Licensed Books on the Web ...............xiv
Using LookAt to Look Up Message Explanations ...........xv
Part 1. Learning the REXX Language......................1
Chapter 1. Introduction ......................3
What is REXX? .........................3
Features of REXX ........................3
Ease of use .........................3
Free format .........................3
Convenient built-in functions ...................4
Debugging capabilities .....................4
Interpreted language ......................4
Extensive parsing capabilities ...................4
Components of REXX.......................4
The SAA Solution ........................4
Benefits of Using a Compiler ....................5
Improved Performance .....................5
Reduced System Load .....................5
Protection for Source Code and Programs ..............6
Improved Productivity and Quality .................6
Portability of Compiled Programs..................6
SAA Compliance Checking ....................6
Chapter 2. Writing and Running a REXX Exec .............7
Before You Begin ........................7
What is a REXX Exec? ......................8
Syntax of REXX Instructions ....................9
The Character Type of REXX Instructions ..............9
The Format of REXX Instructions .................10
Types of REXX Instructions ...................12
Execs Using Double-Byte Character Set Names ............14
Running an Exec ........................16
Running an Exec Explicitly ...................16
Running an Exec Implicitly ...................17
Interpreting Error Messages ....................19
Preventing Translation to Uppercase .................20
From Within an Exec......................20
As Input to an Exec ......................20
Passing Information to an Exec ...................21
Using Terminal Interaction ....................21
© Copyright IBM Corp. 1988, 2001 iii

Specifying Values when Invoking an Exec ..............22
Preventing Translation of Input to Uppercase .............23
Passing Arguments ......................24
Chapter 3. Using Variables and Expressions .............25
Using Variables.........................25
Variable Names .......................26
Variable Values ........................27
Exercises - Identifying Valid Variable Names .............27
Using Expressions .......................28
Arithmetic Operators ......................28
Comparison Operators .....................30
Logical (Boolean) Operators ...................32
Concatenation Operators ....................34
Priority of Operators ......................35
Tracing Expressions with the TRACE Instruction ............37
Tracing Operations ......................37
Tracing Results........................38
Chapter 4. Controlling the Flow Within an Exec............41
Using Conditional Instructions ...................42
IF/THEN/ELSE Instructions ...................42
Nested IF/THEN/ELSE Instructions ................43
SELECT/WHEN/OTHERWISE/END Instruction ............44
Using Looping Instructions ....................47
Repetitive Loops .......................47
Conditional Loops .......................52
Combining Types of Loops ...................55
Nested DO Loops .......................55
Using Interrupt Instructions ....................56
EXIT Instruction .......................57
CALL/RETURN Instructions ...................57
SIGNAL Instruction ......................58
Chapter 5. Using Functions ...................61
What is a Function? .......................61
Example of a Function .....................62
Built-In Functions ........................63
Arithmetic Functions ......................63
Comparison Functions .....................63
Conversion Functions .....................64
Formatting Functions......................64
String Manipulating Functions ..................64
Miscellaneous Functions ....................65
Testing Input with Built-In Functions ................66
Chapter 6. Writing Subroutines and Functions ............69
What are Subroutines and Functions? ................69
When to Write Subroutines vs. Functions ...............70
Writing a Subroutine .......................70
Passing Information to a Subroutine ................72
Receiving Information from a Subroutine ..............75
Writing a Function........................77
Passing Information to a Function .................79
Receiving Information from a Function ...............83
Summary of Subroutines and Functions................83
iv z/OS V1R1.0 TSO/E REXX User’s Guide

Chapter 7. Manipulating Data ...................85
Using Compound Variables and Stems ................85
What is a Compound Variable? ..................85
Using Stems .........................86
Parsing Data..........................87
Instructions that Parse .....................88
Ways of Parsing .......................89
Parsing Multiple Strings as Arguments ...............92
Part 2. Using REXX .............................95
Chapter 8. Entering Commands from an Exec ............97
Types of Commands .......................97
Issuing TSO/E Commands from an Exec ...............98
Using Quotations Marks in Commands ...............98
Using Variables in Commands ..................99
Causing Interactive Commands to Prompt the User ..........100
Invoking Another Exec as a Command...............100
Issuing Other Types of Commands from an Exec ............101
What is a Host Command Environment? ..............101
Changing the Host Command Environment .............106
Chapter 9. Diagnosing Problems Within an Exec ...........111
Debugging Execs .......................111
Tracing Commands with the TRACE Instruction ...........111
Using REXX Special Variables RC and SIGL ............112
Tracing with the Interactive Debug Facility .............113
Chapter 10. Using TSO/E External Functions ............119
TSO/E External Functions ....................119
Using the GETMSG Function ..................120
Using the LISTDSI Function ..................120
Using the MSG Function ....................122
Using the MVSVAR Function ..................123
Using the OUTTRAP Function ..................123
Using the PROMPT Function ..................124
Using the SETLANG Function ..................125
Using the STORAGE Function..................126
Using the SYSCPUS Function ..................126
Using the SYSDSN Function ..................126
Using the SYSVAR Function ..................127
Additional Examples ......................130
Function Packages .......................133
Search Order for Functions ...................134
Chapter 11. Storing Information in the Data Stack ..........135
What is a Data Stack? .....................135
Manipulating the Data Stack ...................136
Adding Elements to the Data Stack ................136
Removing Elements from the Stack ................137
Determining the Number of Elements on the Stack ..........137
Processing of the Data Stack ...................139
Using the Data Stack ......................140
Passing Information Between a Routine and the Main Exec .......140
Passing Information to Interactive Commands ............142
Issuing Subcommands of TSO/E Commands ............142
Contents v

Creating a Buffer on the Data Stack.................142
Creating a Buffer with the MAKEBUF Command ...........143
Dropping a Buffer with the DROPBUF Command ...........144
Finding the Number of Buffers with the QBUF Command ........144
Finding the Number of Elements In a Buffer.............145
Protecting Elements in the Data Stack ................147
Creating a New Data Stack with the NEWSTACK Command ......148
Deleting a Private Stack with the DELSTACK Command ........149
Finding the Number of Stacks ..................149
Chapter 12. Processing Data and Input/Output Processing .......153
Types of Processing ......................153
Dynamic Modification of a Single REXX Expression ...........153
Using the INTERPRET Instruction ................153
Using EXECIO to Process Information to and from Data Sets .......154
When to Use the EXECIO Command ...............154
Using the EXECIO Command ..................154
Return Codes from EXECIO ..................159
When to Use the EXECIO Command ...............159
Chapter 13. Using REXX in TSO/E and Other MVS Address Spaces ...171
Services Available to REXX Execs .................171
Running Execs in a TSO/E Address Space ..............173
Running an Exec in the Foreground................173
Running an Exec in the Background ...............176
Running Execs in a Non-TSO/E Address Space ............177
Using an Exec Processing Routine to Invoke an Exec from a Program 177
Using IRXJCL to Run an Exec in MVS Batch ............178
Using the Data Stack in TSO/E Background and MVS Batch ......180
Summary of TSO/E Background and MVS Batch ............180
CAPABILITIES .......................180
REQUIREMENTS ......................181
Defining Language Processor Environments .............181
What is a Language Processor Environment? ............181
Customizing a Language Processor Environment ...........182
Part 3. Appendixes .............................183
Appendix A. Allocating Data Sets .................185
What is Allocation? .......................185
Where to Begin ........................186
Preliminary Checklist ......................186
Checklist #1: Creating and Editing a Data Set Using ISPF/PDF ......187
Checklist #2: Creating a Data Set with the ALLOCATE Command......190
Checklist #3: Writing an Exec that Sets up Allocation to SYSEXEC .....191
Checklist #4: Writing an Exec that Sets up Allocation to SYSPROC .....192
Appendix B. Specifying Alternate Libraries with the ALTLIB Command 195
Specifying Alternative Exec Libraries with the ALTLIB Command ......195
Using the ALTLIB Command ..................195
Stacking ALTLIB Requests ...................196
Using ALTLIB with ISPF ....................196
Examples of the ALTLIB Command .................196
Appendix C. Comparisons Between CLIST and REXX .........197
Accessing System Information ...................198
vi z/OS V1R1.0 TSO/E REXX User’s Guide

Controlling Program Flow ....................199
Debugging ..........................200
Execution ..........................200
Interactive Communication ....................201
Passing Information.......................201
Performing File I/O .......................202
Syntax ...........................202
Using Functions ........................203
Using Variables ........................203
Appendix D. Notices ......................205
Programming Interface Information .................207
Trademarks..........................207
Bibliography .........................209
TSO/E Publications .......................209
Related Publications ......................209
Index ............................211
Contents vii

viii z/OS V1R1.0 TSO/E REXX User’s Guide