REXX

V10.
cover
IBM Training Front cover

Student Notebook
z/OS REXX Programming Workshop

Course code ES52G ERC 5.0
Student Notebook
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide.
The following are trademarks of International Business Machines Corporation, registered in many
jurisdictions worldwide:
Approach® CICS® DB2®
IMS™ MVS™ NetView®
QMF™ RACF® System z®
Systems Application Tivoli® VTAM®
Architecture®
WebSphere® z/Architecture® z/OS®
z/VM® 400®
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other
countries, or both.
Java™ and all Java-based trademarks and logos are trademarks or registered trademarks of
Oracle and/or its affiliates.
UNIX is a registered trademark of The Open Group in the United States and other countries.
VMware and the VMware "boxes" logo and design, Virtual SMP and VMotion are registered
trademarks or trademarks (the "Marks") of VMware, Inc. in the United States and/or other
jurisdictions.
Other product and service names might be trademarks of IBM or other companies.
June 2016 edition

The information contained in this document has not been submitted to any formal IBM test and is distributed on an “as is” basis without
any warranty either express or implied. The use of this information or the implementation of any of these techniques is a customer
responsibility and depends on the customer’s ability to evaluate and integrate them into the customer’s operational environment. While
each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will
result elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk.
© Copyright International Business Machines Corporation 1999, 2016.

This document may not be reproduced in whole or in part without the prior written permission of IBM.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
V10.1
Student Notebook
TOC Contents
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Course description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Agenda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Unit 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Origins and history of REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Concepts of REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Features of REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Uses for REXX on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Interpreted versus compiled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Learning REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Simple REXX program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Unit 2. Getting started with REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
REXX under TSO/E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Foreground REXX execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
ALTLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Continuation and indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
More on variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Literal strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Hexadecimal and binary literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Can REXX do arithmetic? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Arithmetic precedence rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
The Say instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Concatenating string expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
The Parse instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
Reading from the keyboard (Parse Pull) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
Receiving arguments from the command line (Parse Arg) . . . . . . . . . . . . . . . . . . . . . . . . . 2-20
Parsing placeholder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Parsing templates: The period as a placeholder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
The Trace instruction (introduction) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24
How does REXXTRY work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25
Checkpoint (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26
Checkpoint (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
Checkpoint (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29
© Copyright IBM Corp. 1999, 2016 Contents iii

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook
Unit 3. Programming in REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
REXX terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
Instruction order of precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4
No reserved words: Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5
Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6
String comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7
Strict comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-8
Numeric comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-9
Comparison operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10
If-Then-Else instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-11
The Do-End group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-12
Logical operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13
Logical expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-15
Nested If-Then-Else (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-16
Nested If-Then-Else (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-17
The Select structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18
Select-When-Then-Otherwise instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-19
End example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20
Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-21
Do While loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-22
Coding the Do While loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23
Do Until loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-24
Coding the Do Until loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-25
Controlled repetitive loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-26
Other loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-27
Avoiding the dreaded GO TO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-28
Leave and Iterate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-29
How do we know which loop? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-30
Checkpoint (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-31
Checkpoint (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-32
Checkpoint (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-33
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-34
Unit 4. Functions and subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-2
Subroutines and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-3
What is a function? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-4
Types of functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-5
Writing a subroutine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-6
Writing a function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-7
Built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-9
String manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-10
String manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-11
Substr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-12
Comparison functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13
Formatting functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-14
Conversion functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-15
Other functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16
Informational functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-17
Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-18
iv z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016

V10.1
Student Notebook
TOC Why should we code functions/subroutines? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19

Coding internal subprocedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
Internal subprocedure example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
Procedure instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
Coding external subprocedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
Returning values from subprocedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
Passing arguments to subprocedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25
Passing arguments: Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26
Passing arguments: Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27
Checkpoint (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28
Checkpoint (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-30
Unit 5. Debugging and error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Professionalism aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Ease of maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Signal instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
Signal On Novalue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Return codes from host commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Return code conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Recovery and integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Diagnostic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
Coding for error recovery (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Coding for error recovery (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Trace instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14
Interactive debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Other debug aids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21
Unit 6. Executing host commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Issuing host commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
REXX external environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
Host command environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
TSO/E REXX command SUBCOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Switching environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Coding host commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Change the host command environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Host command environments in z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
TSO host command environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14
ISPEXEC host command environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
Address ISPEXEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16
ISREDIT host command environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Address ISREDIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18
ISPF edit macro language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19
REXX edit macros statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20
Sample edit macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23
Other ISPF interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25
© Copyright IBM Corp. 1999, 2016 Contents v

Student Notebook
CONSOLE host command environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-26

Address CONSOLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-27
MVS host command environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-28
LINK and ATTACH environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-29
Address LINK, LINKMVS, LINKPGM, ATTACH,ATTCHMVS, ATTCHPGM . . . . . . . . . . .6-30
Passing parameters to programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-31
REXX TSO/E extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-32
DB2 (DSNREXX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-33
Communication Server (FTPAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-35
DFSMS (IGGCSI00) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-36
TCP/IP and REXX Programming with REXX/SOCKETS . . . . . . . . . . . . . . . . . . . . . . . . . .6-38
REXX/SOCKETS client sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-40
SDSF (ISFEXEC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-41
Address SDSF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-43
Address SYSCALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-44
UNIX commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-46
Other external environments (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-48
Other external environments (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-49
Checkpoint (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-50
Checkpoint (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-51
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-52
Unit 7. Compound variables and the data stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2
Compound variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-3
First special property: The stem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-4
Stem exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-5
Compound variable example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-6
Second special property: The tail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-7
Compound variables in loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-8
Uses of compound variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-9
The Symbol() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-10
Another compound variable example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-11
Using tails as indexes to data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-12
The OUTTRAP() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-13
How to use OUTTRAP() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-14
Variables created by OUTTRAP() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-15
When does OUTTRAP() work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-16
What is the data stack? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-17
Data stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-18
Using the data stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-20
What happens when the stack is empty? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-22
What if you want to request information from the user while using the data stack? . . . . . .7-23
What if you exit the exec with elements in the data stack? . . . . . . . . . . . . . . . . . . . . . . . . .7-24
TSO/E REXX stack commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-25
NEWSTACK command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-26
DELSTACK command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-27
QSTACK command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-28
MAKEBUF command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-29
QBUF command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-30
QELEM command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-31
vi z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016

V10.1
Student Notebook
TOC DROPBUF command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-32

Uses of the data stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-33
Stack advantages and disadvantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-34
Compound variables advantages and disadvantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-35
Checkpoint (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-36
Checkpoint (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-37
Checkpoint (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-38
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-39
Unit 8. Reading and writing data sets in REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
EXECIO command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
EXECIO command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
EXECIO optional read and write parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5
EXECIO command examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
Using EXECIO in REXX (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Using EXECIO in REXX (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
REXX stream I/O function package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9
Why stream I/O? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
The stream I/O concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Naming streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
The Stream() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13
Values returned by Stream() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14
Stream() examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15
The Charin() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16
Charin() examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17
The Charout() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
Charout() examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19
The Chars() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20
The Linein() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Linein() examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22
The Lineout() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23
Lineout() examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24
The Lines() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-25
Example REXX I/O functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Submit a Job to JES2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
BPXWDYN, interface to dynamic allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
Checkpoint (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-30
Checkpoint (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-32
Unit 9. The parse instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
The parse instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
Sources of input: Pull and external . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Sources of input: Arg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
Sources of input: Version and numeric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Sources of input: Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Sources of input: Var and value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8
Parsing templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Parsing templates: Word by word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10
© Copyright IBM Corp. 1999, 2016 Contents vii

Student Notebook
Period place holder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-11

Parsing templates: Matching literal pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-12
Another literal pattern example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-13
Parsing templates: Absolute column number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-14
Another absolute column example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-15
Another useful example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-16
Parsing templates: Relative column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-17
Another relative column example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-18
Parsing templates: Matching variable value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-19
Another matching variable example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-20
One special exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-21
Checkpoint (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-22
Checkpoint (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-23
Checkpoint (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-24
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-25
Unit 10. Using REXX: REXX compiler, REXX in batch, MVS console commands . . . . . . .10-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3
The REXX products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-4
REXX interpreter and libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-5
Primary and Alternate libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-6
REXX compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-7
Compiler Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-8
Compiler output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-10
Cross reference listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-11
Compiler listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-12
Methods of compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-13
Source to executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-14
Compiler options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-15
Compiler NOCONDENSE option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-16
Compiler CONDENSE option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-17
Compiler control directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-18
Control directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-19
%COPYRIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-20
The REXX Compiler - %STUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-21
Compiler versus interpreter differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-22
How to tell interpreted versus compiled REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-23
Performance: String Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-24
Performance: Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-25
Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-26
Live example (dataset allocation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-27
Live example (JCL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-28
Live example (JCL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-29
Live example (JCL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-30
Live example (JCL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-31
Live example (REXX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-32
Background REXX execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-33
Running REXX in batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-34
REXX in batch using IRXJCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-35
REXX in batch using TSO/E: an example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-36
REXX in batch using IRXJCL: An example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-37
viii z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016
V10.1
Student Notebook
TOC Console session security requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38

The CONSPROF command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-39
The CONSOLE command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-40
The GETMSG() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-41
The CART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-42
How it is done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-43
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-44
Checkpoint (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-45
Checkpoint (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-46
Checkpoint (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-47
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-48
Unit 11. System REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3
System REXX overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
System REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
SYSREXX logical overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6
REXX server versus TSO server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-8
Migration and Coexistence considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10
Implementation and customization: Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-12
TSO/E command support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-13
Usage and invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-14
AXRCMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15
AXRWTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17
AXRMLWTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-19
AXRMLWTO: An example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-21
Other SYSREXX functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-22
Invoke System REXX execs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-23
Console interface for REXX execs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-25
Console interface for REXX execs: Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-27
TSO/E command support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-28
Usage: REXX API‘s example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-30
Usage: REXX API‘s example USS? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-31
Usage: AXREXX service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
System REXX: A simple example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-33
Exploiting SYSREXX: AXREXX macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-35
Exploiting SYSREXX: An example with AXREXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-36
Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-40
SYSREXX ST command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-41
SYSREXX ST Detail command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-43
REXX enhancements in z/OS V2.1 and later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-44
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-45
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-46
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-47
Appendix A. Checkpoint solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Appendix B. REXX taxonomy and REXX built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . B-1
© Copyright IBM Corp. 1999, 2016 Contents ix

Student Notebook
x z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016

V10.1
Student Notebook
TMK
Trademarks
The reader should recognize that the following terms, which appear in the content of this training
document, are official trademarks of IBM or other companies:
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide.
The following are trademarks of International Business Machines Corporation, registered in many
jurisdictions worldwide:
Approach® CICS® DB2®
IMS™ MVS™ NetView®
QMF™ RACF® System z®
Systems Application Tivoli® VTAM®
Architecture®
WebSphere® z/Architecture® z/OS®
z/VM® 400®
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other
countries, or both.
Java™ and all Java-based trademarks and logos are trademarks or registered trademarks of
Oracle and/or its affiliates.
UNIX is a registered trademark of The Open Group in the United States and other countries.
VMware and the VMware "boxes" logo and design, Virtual SMP and VMotion are registered
trademarks or trademarks (the "Marks") of VMware, Inc. in the United States and/or other
jurisdictions.
Other product and service names might be trademarks of IBM or other companies.
© Copyright IBM Corp. 1999, 2016 Trademarks xi

Student Notebook
xii z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016
V10.1
Student Notebook
pref
Course description
z/OS REXX Programming Workshop
Duration: 4.5 days
Purpose
This course is designed to teach you the basic skills required to write
programs using the REXX language in z/OS. The course covers the TSO
extensions to REXX and interaction with other environments such as the
MVS console, System REXX, running REXX in batch jobs, and compiling
REXX.
Audience
People who need to write and maintain REXX programs in the z/OS system
environment.
Prerequisites
Before taking this course, you should be able to:
• Code basic Job Control Language statements
• Code in a programming language
• Create, alter, and delete data sets using TSO
These skills can be developed by taking:
• Fundamental System Skills of z/OS (ES10G)
• A programming language course
Objectives
After completing this course students will be able to:
• Write programs using the REXX language
• Use various data parsing techniques
• Use built-in REXX functions
• Create user-defined internal and external functions and subroutines
• Issue host commands from within REXX execs
• Code programs that read and write data sets
• Use instructions and commands that manipulate the data stack
• Use REXX debugging tools
• Use and invoke System REXX
• Write error-handling routines
© Copyright IBM Corp. 1999, 2016 Course description xiii

Student Notebook
xiv z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016
V10.1
Student Notebook
pref
Agenda
Day 1
Unit 1 - Introduction
Unit 2 - Getting started with REXX
Exercise 1 - Preparation of the TSO environment
Exercise 2 - REXX basics
Unit 3 - Programming in REXX
Day 2
Exercise 3 - REXX programming concepts
Exercise 4 - REXX loops
Unit 4 - Functions and subroutines
Exercise 5 - REXX functions (part 1)
Exercise 6 - REXX functions (part 2)
Day 3
Unit 5 - Debugging and error handling
Exercise 7 - REXX functions or subroutines
Unit 6 - Executing host commands
Exercise 8 - Coding error recovery routines
Unit 7 - Compound variables and the data stack
Day 4
Exercise 9 - Compound variables, data stack, and executing host commands
Unit 8 - Reading and writing data sets in REXX
Exercise 10 - REXX I/O
Unit 9 - The parse instruction
Unit 10 - Using REXX: REXX compiler, REXX in batch, MVS console
commands
Day 5
Exercise 11 - REXX complier, REXX in batch, and MVS console commands
Unit 11 - System REXX
Exercise 12 - System REXX and external environments
Exercise 13 - Parsing data (optional)
© Copyright IBM Corp. 1999, 2016 Agenda xv

Student Notebook
xvi z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016
V10.1
Student Notebook
Uempty
Unit 1. Introduction
What this unit is about

This unit introduces the REXX language, explaining the need that created it,
its history, and its environments.
What you should be able to do

After completing this unit, you should be able to:
• Describe where REXX came from
• Understand some of the common uses of REXX
• List the platforms on which REXX is supported
• Discuss the features and basic concepts of REXX
• Understand the methodology of this course
How you will check your progress

Accountability:
• Checkpoint questions
References
SA32-0972 z/OS TSO/E REXX Reference
SA32-0982 z/OS TSO/E REXX User's Guide
SA32-0978 z/OS TSO/E CLISTs
SA32-0975 z/OS TSO/E Command Reference
SA32-0970 z/OS TSO/E Messages
SA32-0971 z/OS TSO/E User's Guide
© Copyright IBM Corp. 1999, 2016 Unit 1. Introduction 1-1

Student Notebook
Unit objectives
© Copyright IBM Corporation 1999, 2016
Figure 1-1. Unit objectives ES52G5.0
Notes:
1-2 z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016
V10.1
Student Notebook
Uempty
Origins and history of REXX

• Designed by Mike Cowlishaw
– 1979-1982, IBM Hursley labs, UK
– Using feedback from over 300 users on VNET
• Designed to make the act of programming easier
• Intended uses
– Personal programming
– Tailoring user commands
– Macros
– Prototyping
– Applications
• Now runs on many different platforms
Figure 1-2. Origins and history of REXX ES52G5.0
Notes:
You can read “A Brief History of ‘Classic’ REXX” by Mike Cowlishaw on the web at
http://www-01.ibm.com/software/awdtools/rexx/library/rexxhist.html or
http://www.rexxla.org/rexxlang/mfc/rexxhist.html.

Student Notebook
Platforms
• All of IBM's platforms:
– VM - where REXX first appeared (1983)
– OS/2
– AIX
– VSE
– OS/390 (now z/OS) TSO/E (1988)
• Chosen as SAA procedural language in 1987
• Also available on many non-IBM platforms:
– Tandem, VAX, Amiga
– Several UNIX versions
– Regina for Linux
– Windows (Open Object REXX from RexxLA.org)
– NetRexx
Figure 1-3. Platforms ES52G5.0
Notes:
REXX first appeared under VM/SP Release 3 in 1983. REXX was chosen as the SAA Procedural
Language in 1987, which meant that it had to be ported to all of IBM’s other platforms. REXX first
appeared under TSO/E in 1988.
REXX is also available on many non-IBM platforms, as noted above.
V10.1
Student Notebook
Uempty
Concepts of REXX
• Readability
• Natural data typing
• Emphasis on symbolic manipulation
• Dealing with reality
• Nothing to declare
• System independence
Figure 1-4. Concepts of REXX ES52G5.0
Notes:
The list of concepts of REXX has been taken from Mike Cowlishaw’s book The REXX Language: A
Practical Approach to Programming, Second Edition published by Prentice Hall, ISBN
0-13-780651-5. This book should be part of every REXX programmer’s desk set.
Shown above is only a partial list. The rest of the concepts are:
• Dynamic scoping
• Limited span syntactic units
• Be adaptable
• Keep the language small
• No defined size or shape limits

Student Notebook
Features of REXX
• Easy to learn and use
• Essentially free syntactical format
• Either interpreted or compiled
• Rich set of built-in functions
• Typeless variables
• Very strong parsing
• Good debugging tools
• Interfaces with other languages
• Extendable
Figure 1-5. Features of REXX ES52G5.0
Notes:
The grammar and syntax of REXX is very much like natural languages, so it is relatively easy to
learn and use, especially when compared to other programming languages, like C. A REXX exec
may be interpreted, which means that you execute the source code directly, or it may be compiled,
just as programs in other languages are.
The REXX language is small: There are only twenty-three instructions. But REXX does include a
rich set of built-in functions that perform a wide variety of tasks. There is no such thing as
data-typing in REXX: All data is character data, therefore there is no need to declare variables at
the beginning of the program, and indeed REXX provides no mechanism for doing this.
REXX has very strong data parsing capabilities. Input data can be accepted from a variety of
sources, and can be broken up and assigned to variables in many different ways. There are also a
number of debugging tools available in REXX. Various routines are available to interface REXX
execs with programs written in other languages.
REXX is an easily extendable language, so many vendors have adapted REXX as the driving
language for their program products.
V10.1
Student Notebook
Uempty
Uses for REXX on z/OS

• Command procedures
• Personal programming
• Application initiation
• Application prototyping
• Application programming
• Common macro language for varied applications
– ISPF Edit macros, ISPF dialogs, NetView
– IMS, DB2, QMF
– Other vendor products
Figure 1-6. Uses for REXX on z/OS ES52G5.0
Notes:
Command procedures: This was the first, and continues to be the main area for use of REXX,
binding together system commands and logic to create new functions.
Personal programming: Programmers often find they need to write their own personal code to
assist them in performing their jobs. REXX is the language of choice, as you can get your code
working quickly, and develop it progressively as it is used.
Application initiation: REXX is used to initiate applications under ISPF and other environments,
and is also used by some job control systems.
Application prototyping: Programmers must often verify algorithms or test ideas, and REXX is
well suited to this type of activity. Often programs start as prototypes, but are never rewritten. Even
when prototyping, you should follow the standards described later in this course.
Application programming: While REXX can be used for application development, prototyping,
and design, it can also be used as the language for the application itself. Again, its use here
requires that you follow the sort of programming standards described later.
Common macro language: REXX has been adopted by many IBM labs and third party products to
drive their own software platforms.

Student Notebook
Interpreted versus compiled

• Interpreter:
– Translates and executes each program statement as it runs
• Compiler:
– Translates the entire program once into machine language
– Can create object code or CEXEC
– Object code could then be link-edited into a load module
– Then the user runs the program
Interpreter Compiler
Figure 1-7. Interpreted versus compiled ES52G5.0
Notes:
It is generally easier to develop and debug a program using an interpreter as opposed to a
compiler. REXX was specifically designed to be interpreted, but that does not preclude the
development of compilers for REXX, and indeed such compilers do exist.
In this course, you will be using the REXX interpreter which comes with the TSO/E program product
and is part of z/OS. The compiler will be introduced later in the course.
Compiled programs provide better performance, security, and change control.
V10.1
Student Notebook
Uempty
Learning REXX
• Lectures
• Checkpoint exercises
• Labs - write programs and ask questions
• Public domain program REXXTRY
• Samples and interactive exercises
• Manuals
Figure 1-8. Learning REXX ES52G5.0
Notes:
The public domain program REXXTRY is provided in order to interactively test REXX instructions
on the system. Some of the exercises will have you use REXXTRY to reinforce various concepts
discussed during lecture, and you are encouraged to use it to test your own instructions when
writing other REXX execs.
REXX is a very big subject, and this course will not cover all of the details. The primary reference
text for this course is z/OS TSO/E REXX Reference (SA22-7790).

Student Notebook
Simple REXX program
/* Rexx exec to introduce Rexx */

Say "Hello! My name is REXX. What's yours?"
Parse Pull name
If name = '' Then
Say "You're not very friendly."
Else
Say name "is a nice name."
Exit 0
Figure 1-9. Simple REXX program ES52G5.0
Notes:
What is the purpose of each of the statements in the program above?
1.
2.
3.
4.
5.
V10.1
Student Notebook
Uempty
Checkpoint
1. True or False: REXX is available on all of IBM’s platforms.
2. True or False: The REXX interpreter supports indentation,

but the REXX compiler does not.
3. True or False: REXX programs must be compiled, just like

other languages.
4. A REXX exec is sometimes called a REXX (blank).
5. True or False: Mike Cowlishaw named REXX after his dog.
Figure 1-10. Checkpoint ES52G5.0
Notes:
Write your answers here:

Student Notebook
Unit summary
Having completed this unit, you should be able to:
Figure 1-11. Unit summary ES52G5.0
Notes:
V10.1
Student Notebook
Uempty
Unit 2. Getting started with REXX

This unit describes how REXX execs are executed under TSO and covers
some of the basic elements and instructions of the REXX language.

• Execute REXX execs under TSO/E
• Discuss REXX variables and constants
• Understand how REXX performs arithmetic
• Describe the REXX concatenation operators
• Use basic REXX instructions
• Use basic REXX data parsing techniques

Accountability:
• Exercises
References
© Copyright IBM Corp. 1999, 2016 Unit 2. Getting started with REXX 2-1
Student Notebook
Unit objectives
Notes:
V10.1
Student Notebook
Uempty
REXX under TSO/E

• REXX exec can be a sequential data set or a PDS member
• TSO/E EXEC command to invoke a REXX program or a CLIST
• Three ways to use the EXEC command:
– Explicit execution:
EXEC dataset(member) 'parameters' operands
– Implicit execution:
membername parameters
READY
– Extended implicit execution: %myrexx 24 72 my.data
%membername parameters
• Search includes:
//SYSEXEC DD concatenation
then //SYSPROC DD concatenation
for the membername on the command line
Figure 2-2. REXX under TSO/E ES52G5.0
Notes:
REXX execs can exist as sequential data sets or as members of partitioned data sets. The
command to execute both REXX execs and CLISTS is the TSO EXEC command. There are three
ways to use the EXEC command. They are called “explicit execution,” “implicit execution,” and
“extended implicit execution.”
With explicit execution, you type the command EXEC, followed by the data set name (and member
name, if the exec is a PDS member), any parameters to be passed to the exec or CLIST (in single
quotes), and any operands for the EXEC command.
With implicit execution, you do not type the command name EXEC. You simply type the member
name and parameters. The command name EXEC is therefore implied. In order to use implicit
execution, the data set containing the exec must be part of either the //SYSPROC DD or
//SYSEXEC DD data set concatenation. The system will search //SYSEXEC first, then //SYSPROC.
Extended implicit execution is used when the data set member name is preceded by a percent (%)
sign. This causes the system to bypass the rest of the command search order and go straight to the
//SYSEXEC and //SYSPROC data set concatenations.
Student Notebook
Foreground REXX execution

• Interactive execs and ones written that involve user applications are
generally run in the foreground. You can invoke an exec in the
foreground:
– Explicitly with the EXEC command.
– Implicitly by member name if the PDS containing the exec was previously
allocated to SYSPROC or SYSEXEC.
• REXX routines may be executed implicitly if the data set containing the exec is
allocated to a system file (SYSPROC or SYSEXEC).
• You may also specify alternate libraries for implicit execution with the ALTLIB
command.
• To implicitly execute your REXX exec you enter the command at the READY
prompt, from the COMMAND option of ISPF, or on the command line of any
ISPF screen as long as the member name is preceded by "TSO %command"
(without the quotes).
– From another exec as an external function or subroutine, as long as both execs
are in the same PDS or the PDSs containing the execs are allocated to a system
file, for example SYSPROC or SYSEXEC.
– From a CLIST or other program.
Figure 2-3. Foreground REXX execution ES52G5.0
Notes:
REXX routines may be executed explicitly by entering EX on the member line in a PDS enhanced
member list (ISPF option 3.4), at the TSO READY prompt, under the ISPF Command Shell (option
6), or by entering EXEC followed by the data set name and member to be executed:
EXEC ‘userid.REXX.EXEC(MYEXEC)' 'arg1 arg2' EXEC
The "EXEC" operand may be omitted as long as the REXX exec begins with a comment line
containing the word REXX, otherwise it will be interpreted as a CLIST.
EXEC ‘userid.REXX.EXEC(MYEXEC)' 'arg1 arg2'
REXX routines may be executed implicitly if the data set containing the exec is allocated to a
system file (SYSPROC or SYSEXEC). When both system files are available, SYSEXEC is
searched before SYSPROC. As with explicit execution, REXX routines in SYSPROC must begin
with a comment line containing the word REXX, otherwise it will be interpreted as a CLIST. REXX
routines in SYSEXEC do not have this restriction, however it is always a good idea to have the
comment line with the word REXX as the first line in an exec.
You may also specify alternate libraries for implicit execution with the ALTLIB command.
V10.1
Student Notebook
Uempty The ALTLIB command gives you more flexibility in specifying exec libraries for implicit execution.
With ALTLIB, you can easily activate and deactivate exec libraries for implicit execution as the
need arises.
To implicitly execute your REXX exec you enter the command at the READY prompt, from the
COMMAND option of ISPF, or on the command line of any ISPF screen as long as the member
name is preceded by “TSO %command” (without the quotes). The percent sign (%) is optional, if
there is not a TSO command with the same name. However, when you use this form, called the
extended implicit form, TSO/E searches only the ALTLIB or SYSPROC libraries for the name, thus
reducing the amount of search time.
TSO %MYEXEC arg1 arg2
Since SYSPROC and SYSEXEC are usually allocated to your session by using the LOGON
PROC, and you may not have update access to those data sets, your best options for executing
your execs is to use the explicit method outlined above or use ALTLIB to define an APPLICATION
data set that contains your execs allowing you to use the implicit execution method. This will also
keep your private execs from interfering with other execs that may have the same name.
Student Notebook
ALTLIB
• The ALTLIB command lets you specify alternative libraries to contain
implicitly executable execs. You can specify alternative libraries on the
user, application, and system levels.
• The ALTLIB command offers several functions, which you specify using
the following operands:
– ACTIVATE: Allows implicit execution of execs in a library or libraries on the
specified levels, in the order specified.
– DEACTIVATE: Excludes the specified level from the search order.
– DISPLAY: Displays the current order in which exec libraries are searched for
implicit execution.
– RESET: Resets searching to the system level only (execs allocated to SYSEXEC
or SYSPROC).
• Here is an example of the ALTLIB command allocating an
APPLICATION exec library:
ALTLIB ACT APPLICATION(EXEC) DSNAME('userid.REXX.EXEC')
Figure 2-4. ALTLIB ES52G5.0
Notes:
You may also specify alternate libraries for implicit execution with the ALTLIB command.
The ALTLIB command gives you more flexibility in specifying exec libraries for implicit execution.
With ALTLIB, you can easily activate and deactivate exec libraries for implicit execution as the
need arises.
Since SYSPROC and SYSEXEC are usually allocated to your session by using the LOGON PROC,
and you may not have update access to those data sets, your best options for executing your execs
is to use the explicit method outlined in the previous chart or use ALTLIB to define an
APPLICATION data set that contains your execs allowing you to use the implicit execution method.
This will also keep your private execs from interfering with other execs that may have the same
name.
The user level includes exec libraries previously allocated to the file SYSUEXEC or SYSUPROC.
During implicit execution, these libraries are searched first.
The application level includes exec libraries specified on the ALTLIB command by data set or file
name. During implicit execution, these libraries are searched after user libraries.
V10.1
Student Notebook
Uempty The system level includes exec libraries previously allocated to file SYSEXEC or SYSPROC.
During implicit execution, these libraries are searched after user or application libraries.
Data sets concatenated to each of the levels can have differing characteristics (logical record length
and record format), but the data sets within the same level must have the same characteristics.
If you are in split-screen mode in ISPF and you issue the ALTLIB command from a one-screen
session, the changes affect only that screen session. The ALTLIB search order is not valid across
split screens.
Student Notebook
Comments
• Comments must begin with /* and must end with */.
• Comments can appear by themselves or on a line with an instruction.
• Comments can appear inside other comments (nested).
• Examples:
1. /* Rexx execs should begin with a comment */
2. Say "Hello!" /* comment may follow instruction */
3. /* comment may precede instruction */ Say "Hello!"
4. /* A comment may be long, and
it may span
multiple lines */
5. /* Comments may /* Comments may be nested */ be
nested */
Figure 2-5. Comments ES52G5.0
Notes:
Comments in REXX execs begin with the character string “slash-asterisk” (/*) and they end with the
string “asterisk-slash” (*/). When REXX encounters the beginning sequence (/*), it scans until it
finds the ending sequence (*/) and essentially ignores what lies between. Comments may appear
almost anywhere within an exec, on lines by themselves as well as on a line with an instruction. The
comment may precede or follow the instruction on the same line, though the latter is much more
common.
Comments may span multiple lines, and may actually be very long. They may also be nested inside
other comments. This makes it easy to disable or “comment out” blocks of code that contain
comments themselves.
V10.1
Student Notebook
Uempty
Continuation and indentation

• Short instructions can be separated with a semicolon (;):
a = 'Cat';b = 'Dog';c = 17
• Long instructions can be continued onto multiple lines by using
a comma (,) as a continuation character:
sentence = "The quick brown fox jumps over",
"the lazy dog."
• Indentation is supported for readability. REXX does not care
about indentation:
If a = b Then
Say "a and b are equal."
Else
Say "a and b are not equal."
Figure 2-6. Continuation and indentation ES52G5.0
Notes:
The semicolon (;) character is the instruction termination character. It is not necessary, nor is it
recommended, to code them after each instruction, because REXX assumes this character at the
end of every line in the exec. It may be used to code multiple instructions on the same line, though,
as noted in the first example above. This is not usually a good idea, as it makes your exec code
harder to read and maintain.
If a REXX instruction will not fit on a single line, it may be continued by using a comma (,) as the
continuation character. When REXX sees the comma at the end of a line, it will not assume a
semicolon. Instead, the next line of code is joined with the previous line, and the comma is replaced
with a single blank. Instructions may span as many lines as you want.
You will notice that indentation is supported by REXX. REXX does not care if you indent instructions
or clauses within an exec or not. Indentation is strictly for readability purposes - to make your code
easier to read, understand, and maintain.
Student Notebook
Variables
• A symbol which represents some value within a program. The value is
substituted in place of the variable name when the program executes.
• A variable's value can be different each time the program runs. The
value can be changed during program execution.
• In REXX, variable names:
– Can be up to 250 characters long
– Can consist of letters, numbers, and some implementation specific special
characters (in TSO/E: @ # $ ! ? _ . ¢)
– Cannot begin with a number or a period
– Are not case sensitive
• Examples:
input_parms tel@num
var1 name.a
a value$
line.1 zdate
Figure 2-7. Variables ES52G5.0
Notes:
Variable names in REXX are not case-sensitive. They can be coded in upper, lower, or mixed case.
The REXX interpreter automatically converts all variable names to uppercase internally, so that it
must only search for a single character string when looking up a variable.
A number of special characters are supported in REXX variable names. Several of these special
characters are platform and/or language dependent. For example, in TSO, in the US English
language, the dollar sign ($) is supported in variable names. One would not expect that character to
be available in other languages, such as French, German, or even UK English. If you stick to the
special characters exclamation point (!), question mark (?), underscore (_), and period (.), you’ll
probably be okay on pretty much any platform and any language. A period in a variable name
creates a special variable called a compound variable. These variables have some special
properties that simple REXX variables do not. Compound variables will be discussed later in the
course.
V10.1
Student Notebook
Uempty
More on variables
• The size of the variable value is platform dependent, often
limited only by the amount of available memory.
• Variables do not have to be declared. REXX variables are
"typeless.“ All data is character data in REXX.
• A variable that has not been assigned a value is called an
"uninitialized variable." Its value is the variable's own name in
uppercase.
• Variables can be assigned in several ways:
– Parse instruction
– Value() built-in function
– Program written in another language
– Variable assignment statement:
variablename = value
Figure 2-8. More on variables ES52G5.0
Notes:
The size of a variable name may be up to 250 characters in most REXX implementations, including
TSO. The value assigned to the variable may be much more than that. In TSO the limit is up to 16
megabytes, minus one byte.
Many languages require you to declare the names of the variables you are going to use at the
beginning of the program. This is not so with REXX. Variable names may be introduced anywhere
in the program. Also, many languages require that you define the type of data that a variable may
hold. In REXX there is really no concept of data type. All data is treated as character data in REXX.
A number is only a number when you try to use it as a number, in other words, when you try to do
arithmetic.
Variables that are not assigned a value will hold a default value equal to the variable name in
uppercase. These are called “uninitialized variables.”
There are many ways to assign values to variables. Most of these will be discussed later in the
course. One common way to assign a value to a variable is by using the REXX “Assignment”
statement. The syntax is shown on the visual. The value on the right side of the equal sign is
assigned to the variable on the left side of the equal sign.
Student Notebook
Literal strings
• A symbol whose value does not change.
• Literals are enclosed within quotation marks.
• Single (') or double (") quotes are equivalent to REXX, though
this does not mean they are the same character!
• Literal strings can be up to 250 characters long.
• Examples:
var1 = 'This is a literal string.'
Say "Hello, World!"
Address TSO 'LISTCAT‘
where = Pos('B',input)
Say "Don't do that."
Say 'Don''t do that.'
Figure 2-9. Literal strings ES52G5.0
Notes:
While variables are symbols whose values change during program execution, literals are symbols
whose values do not change. Literals are always taken at face value. Literals are primarily
distinguished from variables because literals are always enclosed within quotes. You may use
single quotes (‘ ’) or double quotes (“ ”) around literal strings. Both types of quotation marks are
equivalent to REXX, but they are not the same character. If you start a literal with a single quote,
you must end it with a single quote. The same is true for double quotes.
Literal strings may be up to 250 characters long, and may contain absolutely any characters at all,
including quotation marks.
V10.1
Student Notebook
Uempty
Hexadecimal and binary literals

• Hexadecimal literals consist of hex digits enclosed within
quotes (single or double) and followed by X (upper or
lowercase):
"28 f4 Ab 1C094710"X
'C13487FFA3D'x
• Binary literals consist of binary digits enclosed within quotes
(single or double) and followed by B (upper or lowercase):
'10010010110111'b
"1100 0001 0111 1011"B
• Spaces may be added for readability. They must appear on
byte boundaries in hex literals, and on byte or nibble
boundaries in binary literals.
Figure 2-10. Hexadecimal and binary literals ES52G5.0
Notes:
While not used very often in REXX, it is sometimes useful to be able to define hexadecimal or
binary numbers in REXX. There are some REXX functions that use these values, and it also gives
you a mechanism to enter a character that may not appear on your keyboard, as REXX will store
these values in exactly the same way as any other data (remember, REXX is “typeless”).
Student Notebook
Can REXX do arithmetic?

• REXX can do decimal arithmetic, using the following symbols:
** exponentiation 2 ** 3
2 ** 3 ** 2
* multiplication 7 * 3
/ division 7 / 3
8 / 3
% integer division 7 % 3
// remainder division 7 // 3
+ addition 7 + 3
- subtraction 7 - 3
• REXX can do arithmetic to arbitrary precision
– Controlled by the Numeric instruction
Figure 2-11. Can REXX do arithmetic? ES52G5.0
Notes:
REXX can perform all the usual decimal arithmetic calculations of a general purpose programming
language, but with some differences. One of the principles on which REXX was designed was
“system independence.”
To achieve this, arithmetic expressions are defined in the same way as is conventionally taught in
schools and colleges, and arithmetic is performed by the REXX language processor, not by the
hardware or operating system of the computer on which it runs.
From this you get identical results on all platforms, as well as indefinite precision. The only
disadvantage is a substantial performance penalty on a numerically intensive application.
The precision (number of digits) of the result of an arithmetic expression is controlled by the REXX
Numeric instruction.
V10.1
Student Notebook
Uempty
Arithmetic precedence rules

• REXX follows the usual rules of precedence:
– () Parentheses
– +,- Prefix operator
– ** Exponentiation
– *,/,%,// Multiplication and division
– +,- Addition and subtraction
• Examples:
Say 7 * 3 + 4 Say 2 ** 3 ** 2
Say 7 + 3 * 4 Say 2 ** (3 ** 2)
Say 7 - 3 + 4 Say -5 + 6
Say 7 + 3 - 4 Say -5 + 6 * 2
Say 3 ** 2 Say -(5 + 6) * 2
Figure 2-12. Arithmetic precedence rules ES52G5.0
Notes:
These are the precedence rules of REXX arithmetic. They are the same ones you learned in
school, and indeed are the same for almost all other programming languages. For operators of
equal precedence, expressions are evaluated from left to right. Parentheses are used to change the
order of precedence. Portions of the expression that appear in parentheses are evaluated first.
What will be the results of the expressions in the Say instructions on the visual?
Student Notebook
The Say instruction

• Syntax:
Say expression
where expression is any combination of REXX literals, variables,
functions, or other operator characters.
• Each Say instruction displays on a separate line.
• Examples:
Say "Hello, world."
Say 25 * (9 / 3)
Say "The answer is:" num1 + num2
Say
Say ''
Figure 2-13. The Say instruction ES52G5.0
Notes:
The Say instruction is how data is displayed on the terminal screen in REXX. It is basically
equivalent to DISPLAY in COBOL, to PUT LIST in PL/1, to WRITE in CLIST, or to echo in a UNIX
shell script.
The expression following the keyword Say consists of any combination of literals, variables,
functions, or other operator characters. There are four types of operator characters. Arithmetic
operators have already been discussed, the others will be discussed later.
The expression is evaluated, and the result of that evaluation is then displayed on the terminal
screen.
V10.1
Student Notebook
Uempty
Concatenating string expressions

• REXX has very advanced string handling capabilities.
• Three string concatenation operators:
' ' (blank)
|| (double vertical bars)
(no operator character -- abuttal)
• Also many functions can concatenate strings (later).
• Examples:
Say "Join" "these" "words"
Say "Join" "these" "words"
tvar = "these"
Say "Join" tvar "words"
Say "Join" || tvar || "words"
Say "Join"tvar"words"
Figure 2-14. Concatenating string expressions ES52G5.0
Notes:
The “blank” operator means that you place two terms, one after the other, separated by one or more
blanks. REXX does the obvious thing and puts one blank between each pair of terms.
The double vertical bar concatenation operator (||) means that the two terms appearing on either
side of the operator are joined together with no intervening blanks (they are “abutted” together).
If the two terms being concatenated are syntactically distinct, such as a literal and a variable, they
may be abutted together with no operator between them.
What are the results of the examples in the visual?
Student Notebook
The Parse instruction

• "To resolve something into its component parts"
• Syntax:
Parse source variabletemplate
where source is the input source of the data to be parsed,
and variabletemplate are the rules for parsing that data,
and the variables to which the data parts will be assigned.
Figure 2-15. The Parse instruction ES52G5.0
Notes:
The word “parse” means to resolve, or divide, something into its component parts. This is usually
applied in language to a sentence or phrase.
The REXX Parse instruction is used to accept input data from a variety of sources, break that data
up into pieces (component parts), and assign the pieces as the values of variables.
There are several sources of input data, and there are many ways in which the data may be parsed
and assigned to variables.
V10.1
Student Notebook
Uempty
Reading from the keyboard (Parse Pull)

• Syntax:
Parse Upper Pull variabletemplate
-or-
Pull variabletemplate
where variabletemplate is a list of variable names
• Keyword "Upper" converts input data to uppercase
automatically before assigning to variables in template.
• To leave input data in mixed case, drop the keyword "Upper":
Parse Pull variabletemplate
• Example:
/* Rexx sample */
Say "Please enter your name:"
Parse Upper Pull name
Say "Hello" name". Enter two numbers:"
Parse Upper Pull numa numb
Say "You entered these numbers:" numa "and" numb
Figure 2-16. Reading from the keyboard (Parse Pull) ES52G5.0
Notes:
It is often desirable to prompt the user of a program for some input. The Parse instruction accepts
data from a number of different sources. One of those input sources is the terminal keyboard. In
REXX, a Say instruction can be used to prompt the user for input, and the Parse instruction can be
used to read that input.
The Parse instruction keyword that causes Parse to read from the keyboard is Pull. The Parse Pull
instruction will cause the exec to stop executing and wait for the user to type something at the
keyboard. When the user presses the enter key, the data that was typed is intercepted by Parse,
and is assigned to variables according to the rules in the variable template. The keyword Upper
automatically translates the input data into uppercase before assigning it to variables. Coding
simply Pull is a shorthand form of Parse Upper Pull.
To leave the input data in mixed case, you must code Parse Pull, dropping the keyword Upper.
The simplest variable template is just a string of variable names. The words in the input data are
assigned to the variables one by one. The first word of input becomes the value of the first variable,
the second word of input is assigned to the second variable, and so forth.
Student Notebook
Receiving arguments from the command line

(Parse Arg)
• Syntax:
Parse Upper Arg variabletemplate
-or-
Arg variabletemplate
where variabletemplate is a list of variable names
• Keyword "Upper" converts input data to uppercase
automatically before assigning to variables in template.
• To leave input data in mixed case, drop the keyword "Upper":
Parse Arg variabletemplate
• Example:
/* Rexx sample */
Parse Upper Arg inparms
Say inparms
Parse Upper Arg parm1 parm2 parm3 rest
Say parm1
Say parm2
Figure 2-17. Receiving arguments from the command line (Parse Arg) ES52G5.0
Notes:
Many programs accept parameters which are coded on the command line following the program
name. REXX has the capability to accept input arguments from the command line as well, again by
using the Parse instruction.
The Parse instruction keyword that allows Parse to accept command line arguments is Arg. An
argument string passed in to the REXX exec from the command line is placed in a buffer in storage.
The Parse Arg instruction reads that buffer. The buffer remains intact for the life of the exec, so the
Parse Arg instruction can be coded over and over again in the exec, so that you can reparse the
same data as many times and in as many ways as you want.
Once again, the keyword Upper translates the incoming arguments to uppercase before Parse
assigns the data to variables. Just as Pull coded by itself is short for Parse Upper Pull, coding Arg is
shorthand for Parse Upper Arg.
To leave the input data in mixed case, you must code Parse Arg.
V10.1
Student Notebook
Uempty
Parsing placeholder
• To ignore some of the input data, you could code a "dummy"
variable:
Parse Pull var1 var2 dummy var3
Parse Arg var1 var2 dummy var3
• Rather than waste a variable name, code the "parsing
placeholder" in the variable template, a period in place of a
variable name:
Parse Pull var1 var2 . var3
Parse Arg var1 var2 . var3
• The period must be blank delimited.
• Data that would have been assigned to a variable in that
position is ignored.
Figure 2-18. Parsing placeholder ES52G5.0
Notes:
Let’s assume that several words of information are being passed to a Parse Pull or a Parse Arg
statement. Let’s also assume that we simply do not care about one or more of these words. How
can we ignore part of the input data, and parse the rest of the input data?
One thing we could do is to code a dummy variable to accept the word that we are not interested in,
and then we just do not use that variable in the rest of the exec. That method would work, but it
does waste a variable name, and causes REXX to go through some unnecessary overhead.
Instead, we could use the Parsing Placeholder. Coding a blank-delimited period (.) in place of a
variable name in a variable template will cause the Parse instruction to ignore any data that would
have been assigned to a variable in that position.
What would happen if the following instruction were to appear in a REXX exec?
Parse Pull var1 var2 .
Student Notebook
Parsing templates: The period as a placeholder

• A period in a template is a placeholder. It is used instead of a
variable name, but it receives no data. It is useful:
– As a "dummy variable" in a list of variables
– Or to "collect" unwanted information at the end of a string
/* REXX - parse example with periods as placeholders */

parse source . . . . . . . ENV . .
if ENV = 'OMVS' then do /* are we running under UNIX ? */
(instructions)
end
if ENV = 'TSO/E' then do /* are we running under TSO/E? */
(instructions)
end
if ENV = 'ISPF' then do /* are we running under ISPF? */
(instructions)
end
if ENV = 'MVS' then do /* are we running under MVS? */
(instructions)
end
Figure 2-19. Parsing templates: The period as a placeholder ES52G5.0
Notes:
Examples:
V10.1
Student Notebook
Uempty
/* REXX - PARSE using a period in the parse template */
ptst = "AA BB CC DD EE"
SAY "PERIOD AS PLACEHOLDER"
PARSE VAR ptst v1 v2 . . v3
SAY "V1=" v1 /* v1 CONTAINS WORD 1 (AA) */
SAY "V2=" v2 /* v2 CONTAINS WORD 2 (BB) */
SAY "V3=" v3 /* v3 CONTAINS WORD 5 (EE) */
DROP v1
DROP v2
DROP v3
SAY
SAY "PERIOD AS A COLLECTOR OF UNWANTED INFORMATION"
PARSE VAR ptst v1 . v2 .
SAY "V1=" v1 /* v1 CONTAINS WORD 1 (AA) */
SAY "V2=" v2 /* v2 CONTAINS WORD 2 (CC) */
EXIT
When executed the result is:
PERIOD AS PLACEHOLDER
V1= AA
V2= BB
V3= EE
PERIOD AS A COLLECTOR OF UNWANTED INFORMATION

V1= AA
V2= CC
Student Notebook
The Trace instruction (introduction)

• Syntax:
Trace option
– where option is the trace option to put into effect.
• Useful options:
–N Normal (default)
–O Off
–R Results
–I Intermediates
Figure 2-20. The Trace instruction (introduction) ES52G5.0
Notes:
Provides powerful debugging capabilities
- Displays the results of expression evaluations
- Displays the variable values
- Follows the execution path
- Interactively pauses execution and runs REXX statements
Activated by using the TRACE instruction and function
The Trace instruction is typically used to debug a REXX exec. Tracing an exec means that you
want REXX to show you the instructions of the exec on the screen before they are executed, and
perhaps some information about how REXX is executing the program code.
There is a lot more to REXX tracing than the options shown here. This is just a simple introduction
of the most useful features so you can get started using Trace in the lab exercises. The rest of the
features of the Trace instruction will be discussed later.
When coding the Trace instruction in your REXX execs, you can type the entire option name if you
want, but you only need to type the first character of the option. The Trace instruction is often found
at or near the beginning of an exec, but trace options may be set wherever and whenever you want.
V10.1
Student Notebook
Uempty
How does REXXTRY work?
/* interactive REXX instruction execution */

Say "EXEC REXXTRY allows you to interactively execute"
Say "REXX instructions. Each instruction string is"
Say "executed when you press ENTER."
Say "To end, type EXIT."
Do Forever /* the EXIT instruction will terminate loop */
Say "REXXTRY:" /* prompt for the next instruction */
Parse External @line@
Interpret @line@
End /* Do Forever */
Figure 2-21. How does REXXTRY work? ES52G5.0
Notes:
REXXTRY is a public domain exec that allows you to interactively execute REXX instructions. Once
you start REXXTRY, anything you type at the terminal will be executed by the REXX interpreter. It is
an excellent tool for experimenting and for testing and prototyping your code. You will be using
REXXTRY periodically throughout the course.
Student Notebook
Checkpoint (1 of 3)
1. True or False: In order to explicitly execute a REXX exec, it
must be a member of a data set concatenated to the
//SYSPROC DD concatenation.
2. In order to implicitly execute a REXX exec, it must be a

member of a data set concatenated to the (blank) DD or
(blank) DD concatenation.
3. You can place your execs in a CLIST library in the (blank) DD

concatenation.
4. Comments begin with (blank) and end with (blank).
Figure 2-22. Checkpoint (1 of 3) ES52G5.0
Notes:
V10.1
Student Notebook
Uempty
Checkpoint (2 of 3)
5. True or False: Indentation is required by the REXX compiler,
but is not required by the REXX interpreter.
6. True or False: Variable names in REXX are case sensitive

and are of unlimited length.
7. True or False: Unlike languages like C, COBOL, and PL/1,

REXX has no concept of data types.
8. True or False: Literals must be enclosed within single quotes.
Notes:
Student Notebook
Checkpoint (3 of 3)
9. What will the following code fragment produce?
var1 = ‘Mon’
var2 = ‘day’
Say var1var2
10. The Parse Pull instruction reads input data from the (blank).
11. The Parse Arg instruction reads input data from the (blank).
Notes:
V10.1
Student Notebook
Uempty
Unit summary
Notes:
Student Notebook
V10.1
Student Notebook
Uempty
Unit 3. Programming in REXX

This unit describes the decision-making instructions and looping structures in
REXX.

• Describe the components of a REXX exec
• Understand the following features of REXX
- Comparisons
- Logical expressions
- If-Then-Else
- Select-When-Then-Otherwise
- Looping structures

Accountability:
• Exercises
References
© Copyright IBM Corp. 1999, 2016 Unit 3. Programming in REXX 3-1

Student Notebook
Unit objectives
– Comparisons
– Logical expressions
– If-Then-Else
– Select-When-Then-Otherwise
– Looping structures
Notes:
V10.1
Student Notebook
Uempty
REXX terminology
• REXX execs consist of "instructions" or "statements“.
• Each instruction is made up of zero or more "clauses“.
• Clauses are made up of "tokens“.
• Tokens can be:
– Symbols
– Literals
– Comments
– Numbers
– Special characters
– Operator characters
Figure 3-2. REXX terminology ES52G5.0
Notes:
In REXX, the term instruction and statement are interchangeable.
An instruction with zero clauses would be a blank line. Blank lines are valid in REXX. They can be
used to separate blocks of code, to help make your program easier to understand and maintain.
Tokens are the basic building blocks of REXX execs.

Student Notebook
Instruction order of precedence

The REXX interpreter scans each instruction and determines the
instruction type based upon the following order:
1. Null clause
2. Label
3. Assignment instruction
4. REXX keyword instruction
5. Command to host environment
Figure 3-3. Instruction order of precedence ES52G5.0
Notes:
After scanning the statement and evaluating the expressions, REXX determines the type of
instruction to execute. There are five types of instructions, as shown in the visual above.
A null clause is either a blank line or a comment.
A label is a symbol terminated by a colon ( : ).
An assignment statement is used to assign a value to a variable.
A REXX keyword is an instruction name that REXX recognizes, like Say, Parse, or Trace.
A command to the host environment is an instruction that REXX does not recognize, and therefore
passes outside the interpreter for execution.
V10.1
Student Notebook
Uempty
No reserved words: Exercise

• Words are only reserved in context, like Then after If
• What would the following instructions produce?
Say Say _________________
Say = 5
Say Say _________________
abc = 5
abc _________________
abc = ‘LISTCAT’
abc _________________
Figure 3-4. No reserved words: Exercise ES52G5.0
Notes:
There are no reserved words in REXX. Words are only reserved in context, such as the keyword
“Then” following the “If” instruction, or “When” following “Select.”
Since there are no reserved words in REXX, what would appear on the screen as a result of the
instructions in the visual?

Student Notebook
Comparisons
• Comparisons in REXX are sometimes called "Binary
Conditional Expressions" because they always have only two
possible results.
• In human terms, we call these results "True" and "False“.
• In REXX, a "True" condition is represented by the value 1 and
a "False" condition is represented by the value 0.
• There are two types of comparisons in REXX:
– String comparisons
– Numeric comparisons
Figure 3-5. Comparisons ES52G5.0
Notes:
A binary conditional test is one where there are only two possible answers, like true or false, in or
out, up or down, left or right, and so forth.
Comparisons in REXX produce either True or False results. REXX knows these results as the
numbers 1 or 0, respectively.
The two types of comparisons in REXX are string comparisons and numeric comparisons.
V10.1
Student Notebook
Uempty
String comparisons
• Always case sensitive
• Two types of string comparisons:
– Normal: Ignore leading/trailing blanks
– Strict: Each character must match exactly in order for the two terms to
be equal
• Examples:
answer = " YES " /* assign variable */
Say answer = "YES" /* normal comparison */
Say answer = "yes" /* comparisons are */
/* case sensitive */
• Typically, string comparisons are of equality or inequality
Figure 3-6. String comparisons ES52G5.0
Notes:
You must be careful about the case-sensitive nature of REXX string comparisons. The way to
handle this is to always convert the data to be compared to uppercase, and compare to uppercase
literals.
In normal comparisons, leading or trailing blanks in either term being compared are ignored for
comparison purposes.
REXX uses the EBCDIC collating sequence on z/OS and z/VM. Greater than ( > ) and less than ( <
) comparisons use this sequence to determine which term is larger or smaller. For example, “A”
(‘C1’X) is smaller than “B” (‘C2’X).
What would be the results of the comparisons in the examples on the visual?

Student Notebook
Strict comparisons
• Doubling an operator character forces a strict comparison
• Always character comparisons, never numeric
• Just match the bytes, one by one
• Leading and trailing blanks are included
• Example:
answer = " YES " /* assign variable */
Say answer == "YES" /* strict comparison */
Say 5 == 5.0 /* strict comparison */
Figure 3-7. Strict comparisons ES52G5.0
Notes:
Strict comparisons are always character comparisons, even when the two terms being compared
are numbers. They are coded by doubling one of the comparison operator characters.
All of the bytes in both terms are significant, even leading and trailing blanks. Each byte in both
terms must match exactly, otherwise the two terms are not equal.
You probably won’t see or use strict comparisons very often, but it’s certainly a nice feature to have
when you need it.
What are the results of the comparisons in the examples on the visual?
V10.1
Student Notebook
Uempty
Numeric comparisons
• Automatically performed if both terms can be recognized as
numbers, and the comparison type is normal
• Comparison is performed within the "Numeric Fuzz" value
(default is 0)
• Examples:
num1 = 31; num2 = 30 /* assign variables */
Say num1 = num2 /* equal? */
Say num1 \= num2 /* not equal? */
Say num1 > num2 /* greater than? */
Say num1 < num2 /* less than? */
Figure 3-8. Numeric comparisons ES52G5.0
Notes:
If both terms being compared are numeric, and the comparison is not “strict,” then a numeric
comparison is performed.
Numeric Fuzz is a setting for the accuracy of the comparison. It determines how many digits in the
terms being compared are allowed to be ignored for comparison purposes. The default value for
Numeric Fuzz is 0 (zero), which means that all digits in the terms being compared are significant.
What are the results of the comparisons in the examples on the visual?

Student Notebook
Comparison operators
• REXX supports the following comparison operators:
= equal
\= not equal
¬= not equal
<> not equal (less than or greater than)
>< not equal (greater than or less than)
<= less than or equal to
\> less than or equal to (not greater than)
¬> less than or equal to (not greater than)
>= greater than or equal to
\< greater than or equal to (not less than)
¬< greater than or equal to (not less than)
< less than
> greater than
Figure 3-9. Comparison operators ES52G5.0
Notes:
These are the comparison operators. They may be used for both string and numeric comparisons.
You must use the operator characters. The letter equivalents are not supported in REXX. For
example, you must use >, and not GT, or <=, not LE.
To perform strict comparisons, you simply double one of the comparison operators (like ==).
V10.1
Student Notebook
Uempty
If-Then-Else instruction
• Allows program to take different execution paths based upon
comparison results
• Syntax:
If comparison Then instruction1
Else instruction2
• The Else is optional
• Only one instruction is allowed following Then or Else
• Example:
If var1 = var2 Then
Say "The values are equal."
Else
Say "The values are not equal."
Figure 3-10. If-Then-Else instruction ES52G5.0
Notes:
REXX supports both an If-Then and an If-Then-Else structure. In other words, the Else portion is
optional.
If-Then-Else in REXX works in much the same way as it does in almost every other programming
language:
A comparison is performed. If the result of the comparison is true, the path marked by the Then
keyword is followed, and the path marked by Else is skipped, if it exists. If the comparison is false,
the Then path is skipped, and the path marked by the Else keyword is followed, if it exists.
Note that you are only allowed one instruction following a Then or an Else keyword. Thus, in
REXX, there is no “Endif” instruction.

Student Notebook
The Do-End group

• To code more than one instruction following a Then or Else,
bracket them between the Do and End instructions:
If var1 = var2 Then
Do
instruction1
instruction2
etc....
End
• The Do and End are sometimes called "bracketing keywords“.
Figure 3-11. The Do-End group ES52G5.0
Notes:
Quite often we will want to execute more than one instruction after a Then or an Else keyword. In
those cases, we can get around the one instruction restriction by bracketing a group of instructions
between the Do and End instructions. This is called a Do-End Group.
The Do-End Group is logically treated as our one instruction after the Then or Else by REXX, even
though it may contain many instructions which will actually be executed. There is no limit to the
number or type of instructions that may be included between the Do and the End.
V10.1
Student Notebook
Uempty
Logical operators
• Comparison results (0 for false, 1 for true) may be combined
together with these operators.
• These operators act upon "true" or "false" conditions to
produce final "true" or "false" results.
Operator Meaning
& "And"
| "Or"
&& "Exclusive Or"
\ "Not"
• Examples:
var1 = 1;var2 = 0 /* assign variables */
Say var1 & var2 /* Both true? */
Say var1 | var2 /* Either one true? */
Say var1 && var2 /* Only one true? */
Figure 3-12. Logical operators ES52G5.0
Notes:
You can combine the results of several comparisons into one “logical expression” by using these
logical operators. These operators perform “Boolean logic” types of combinations to produce true or
false (1 or 0) results.
The following table defines the Boolean logic operations:
• & (And operator)
0 & 0 yields 0
1 & 0 yields 0
0 & 1 yields 0
1 & 1 yields 1
• | (Or operator)
0 | 0 yields 0
1 | 0 yields 1
0 | 1 yields 1

Student Notebook
1 | 1 yields 1
• && (Exclusive Or operator)
0 && 0 yields 0
1 && 0 yields 1
0 && 1 yields 1
1 && 1 yields 0
Other computer languages have the same types of operations, but they may use different symbols
for the operators.
What are the results of the examples in the visual?
V10.1
Student Notebook
Uempty
Logical expressions
• Consist of combinations of comparisons and boolean logic
• Always have a final resulting value of 1 (true) or 0 (false)
• Examples:
var1 = 41; var2 = 1; var3 = 0
Say var1 > var2 & var3 > var2
Say var1 > var2 | var3 > var2
Say var1 > var2 && var3 < var2
Say var1 > (var2 | var3) > var2
Figure 3-13. Logical expressions ES52G5.0
Notes:
A logical expression is the combination of comparisons and logical operators. The comparisons
give a result of 1 or 0, then the logical operators act on those results.
In an expression the order of evaluation and operator precedence is important. We can make our
intentions obvious, or change the order of operation, with parentheses.
What are the results of the examples in the visual above?

Student Notebook
Nested If-Then-Else (1 of 2)
• There is no restriction on what instruction may follow Then or Else.
• If-Then-Else structures can be embedded (called "nesting").
• Example:
If token1 = "CONCAT" Then
Do
..instructions..
End
Else
If token1 = "BLK" | token1 = "BLOCK" Then
Do
..instructions..
End
Else
If token1 = "DATASET" Then
Do
..instructions..
End
Figure 3-14. Nested If-Then-Else (1 of 2) ES52G5.0
Notes:
There is no restriction on what instruction may follow a Then or an Else; it may be another If
construct. This means that If’s may be embedded, or nested, within each other. You may nest up to
250 If’s deep.
Nested If structures can get very complicated. Note the indentation in the example above, and how
it helps to make the code easier to read. Compare this with the examples on the next page.
V10.1
Student Notebook
Uempty
Nested If-Then-Else (2 of 2)
• Nested If's can sometimes be confusing:
If answer = "YES" Then
If name = "FRED" Then Say "Okay, Fred."
Else Say "Okay."
Else Say "Why not?"
• Use Do-End groups and indentation for clarity:
If name = "FRED" Then
Say "Okay, Fred."
Else
Say "Okay."
Else
Say "Why not?"
Figure 3-15. Nested If-Then-Else (2 of 2) ES52G5.0
Notes:
How do you know which Else matches to which If in a complex series of statements? REXX has a
strict rule: “The Else binds to the nearest If at the same level of execution.” Therefore, in the first
example above, the first Else binds to the second If, and the second Else binds to the first If. This is
much easier to see by using indentation as in the second example.
You could also remove ambiguity by using the Do-End Group structure:
Do
If name = "FRED" Then
Say "Okay, Fred."
Else
Say "Okay."
End
Else
Say "Why not?"

Student Notebook
The Select structure
True instruction 1
Test 1
False
Test 2
True instruction 2
False
Test 3
True instruction 3
False
instruction(s)
Figure 3-16. The Select structure ES52G5.0
Notes:
The Select structure allows you to replace multiple nested If-Then-Else’s with a much more
straightforward construct. Select also uses less overhead than multiple I-T-E’s.
The visual shows the flow of the Select construct. We’ll see how to code Select on the next page.
Some other programming languages call this a “CASE” structure, and the implementation may be
slightly different. In REXX, each of the tests is a logical expression, and they are completely
independent of each other.
V10.1
Student Notebook
Uempty
Select-When-Then-Otherwise instruction
• It is common to have multiple nested If-Then-Else statements.
• The Select structure can replace multiple I-T-E's.
• This is the example from three pages ago, using Select:
Select
When token1 = "CONCAT" Then
Do
..instructions..
End
When token1 = "BLK" | token1= "BLOCK" Then
Do
..instructions..
End
When token1 = "DATASET" Then
Do
..instructions..
End
Otherwise
Say "Error - unrecognized token:" token1
End /* of Select */
Figure 3-17. Select-When-Then-Otherwise instruction ES52G5.0
Notes:
The Select instruction replaces multiple nested If-Then-Else instructions.
A series of logical expressions are evaluated until one returns a value of 1 (true), then the
corresponding REXX statement (or Do-End Group) is executed. Then control passes to the
statement after the End of the Select construct.
The Otherwise enables you to execute a series of statements if none of the When expressions
yields a value of 1 (true).
Selects are easier to indent than multiple I-T-E’s, and they are easier to follow.

Student Notebook
End example
• How often have you seen this in program code?
End
End
End
End
• To easily match an End with its corresponding Do or Select,
code a short comment:
End /* Else Do */
End /* Then Do */
End /* Select */
Figure 3-18. End example ES52G5.0
Notes:
The multiple Ends example above is extremely common. If you’re lucky, the indentation is done
properly. Can you imagine how difficult it would be to debug this program, especially if all those End
statements started in the same column? Also, the corresponding Do or Select instructions can
sometimes be several screens, perhaps hundreds of lines, above the End instructions.
To more easily match an End instruction with its corresponding Do or Select instruction, code a
short comment on the End instruction. It's easy to do, it only takes a second or two, and it will
definitely save you a lot of headaches later.
V10.1
Student Notebook
Uempty
Loops
• A Do instruction followed by nothing indicates a Do-End group.
• A Do instruction followed by other keywords indicates a loop.
• There are five kinds of loops:
– Loop while a logical expression remains true
– Loop until a logical expression becomes true
– Controlled repetitive loop (with control variable)
– Loop a specific number of times
– Loop forever (there are ways out)
Figure 3-19. Loops ES52G5.0
Notes:
We have seen the Do keyword instruction used to identify Do-End Groups that follow Then or Else
keywords. The Do instruction is also used to create looping structures in REXX.
A loop is a set of REXX instructions that can be executed over and over again. There must
obviously be some type of control structure to tell REXX when to stop executing the loop.
The five types of loops are shown on the visual above.

Student Notebook
Do While loop
False
Test
True
Process
Figure 3-20. Do While loop ES52G5.0
Notes:
In this form of loop, a logical expression is evaluated at the start, and is reevaluated for each
iteration of the loop. If the expression returns a value of 1 (True), the loop instructions are
performed. If the expression returns a value of 0 (False), the loop ends and control passes to the
instruction following the End instruction.
Note that because the expression is evaluated before the first time the loop is executed, the loop
may not even run once.
V10.1
Student Notebook
Uempty
Coding the Do While loop

• Syntax:
Do While logical expression
..loop instructions..
End
• Example:
var1 = 12
Do While var1 > 6
Say var1
var1 = var1 - 1
End /* Do While */
Figure 3-21. Coding the Do While loop ES52G5.0
Notes:
The syntax for the Do While loop is shown on the visual above. The logical expression is tested at
the beginning of the loop each time, and if the result is 1 (True), the loop instructions are executed
until you reach the End instruction. Then the logical expression is evaluated again. As long as the
result of the expression is true, the loop will keep executing. When the result of the logical
expression test is false, control is passed to the next instruction following the End instruction.
What will be the result of the example in the visual?

Student Notebook
Do Until loop
Process
False
Test
True
Figure 3-22. Do Until loop ES52G5.0
Notes:
The Do Until loop is the opposite of the Do While loop. Where the Do While performs its test first,
before processing the loop instructions, the Do Until processes the loop instructions first, then
performs its test. This means that the Do Until will always perform its loop instructions at least once.
Also, where the Do While performs the loop instructions if the logical expression result is true, the
Do Until will perform the loop instructions (again) if the logical expression result is false. When the
logical expression result is true, the Do Until loop ends and control is passed to the next instruction
after the end of the loop.
V10.1
Student Notebook
Uempty
Coding the Do Until loop

• Syntax:
Do Until logical expression
..loop instructions..
End
• Example:
var1 = 1
Do Until var1 > 6
Say var1
var1 = var1 + 1
End /* Do Until */
Figure 3-23. Coding the Do Until loop ES52G5.0
Notes:
Even though the Do Until is coded in much the same way as the Do While, it works in the opposite
way. Do Until always executes its loop instructions at least once, and then tests the logical
expression.
What will be the result of the example on the visual?

Student Notebook
Controlled repetitive loop

• Syntax:
Do cntlvar = init To final By incr For maxloops
where:
cntlvar is the loop control variable name
init is the initial value assigned to the control variable
final is the final value the control variable will accept
incr is the amount by which the control variable is incremented
maxloops is the absolute maximum number of times the loop will execute.
• Example:
Do i = 1 To 100
/* these instructions will execute while
the value of the variable i changes
from 1 to 2 to 3 to 4 ... to 100 */
End
Figure 3-24. Controlled repetitive loop ES52G5.0
Notes:
This is the most useful looping construct, but it is the most difficult to code. It is useful because it
gives you a self-incrementing variable that is usable within the loop and after the loop has ended.
This variable may have any name you want, but you will often see the variable name “i” used, as in
the example.
The init value is the initial value to assign to the variable. This value must be a number. The value of
the control variable is compared to the final value each time through the loop. When the value of the
control variable exceeds the final value, the loop ends.
The default increment value is 1, but you may change it to any numeric value you want to use.
As the control variable is just a REXX variable, usable within the loop itself, it can be reset to any
value while the loop executes. This could lead to infinite loops. The maxloops value sets another
loop counter; when the loop has executed this many times the loop will end.
V10.1
Student Notebook
Uempty
Other loops
• Loop a specific number of times:
Do 5
..instructions..
End /* Do 5 */
• Loop forever:
Do Forever
..instructions..
End /* Forever */
Figure 3-25. Other loops ES52G5.0
Notes:
In the first construct, loop a specific number of times, the Do instruction may be followed by any
REXX expression which results in a positive whole number or zero.
The second structure is similar to the Do i = 1 instruction. The difference is that “Do Forever” does
not give you the self-incrementing REXX variable. Once again, though, there must be some type of
control structure inside the loop that will cause its termination.

Student Notebook
Avoiding the dreaded GO TO

• REXX has been designed to remove the need for a “GO TO"
instruction by supplying the following keyword instructions:
– Leave
– Iterate
– Return
– Exit
– Signal
• The Return and Exit instructions will both cause immediate
cessation of the currently executing routine. Control is returned
to the calling environment.
• The Return and Exit instructions are identical except in one
situation (discussed later).
Figure 3-26. Avoiding the dreaded GO TO ES52G5.0
Notes:
Analysis of programming errors long ago revealed that the “GO TO” instruction was used by
programmers who like to create “spaghetti-like” code, and was a source of the worst bugs and
program failures. For that reason, REXX does not have a “GO TO” instruction. Instead, Mike
Cowlishaw identified the main uses of the “GO TO” instruction, and designed specific instructions to
perform those tasks. Those instructions are shown on this page.
There is a difference between Return and Exit. It will be discussed later. For now we’ll just say that
Return and Exit do the same thing: they terminate the currently running routine and return control to
the caller of the routine.
The Signal instruction will also be discussed at a later time. It is included here for completeness.
The Leave instruction and the Iterate instruction are both discussed on the next page.
V10.1
Student Notebook
Uempty
Leave and Iterate

z The Leave instruction will cause REXX to terminate the currently
active loop:
Do Forever
...
... Leave
...
...
End
z The Iterate instruction will cause REXX to bypass the remaining loop
instructions and pass control to the End instruction:
Do Forever
...
... Iterate
...
...
End
Figure 3-27. Leave and Iterate ES52G5.0
Notes:
The Leave instruction allows you to leave a loop, but not the entire exec. When the Leave
instruction is encountered, the rest of the loop instructions are bypassed, and control is passed to
the next instruction following the End instruction.
The Iterate instruction allows you to go to the end of a loop and re-execute the loop control part. It
feels like you go to the start of the loop, but strictly speaking, you go to the End instruction and
perform end-of-loop processing. In other words, the rest of the loop instructions are bypassed, and
control is passed to the End instruction. Variables are incremented if necessary, logical expressions
are tested, and REXX determines whether to execute the next iteration of the loop.

Student Notebook
How do we know which loop?

• Loops can be nested.
• The loop control variable can be used as the name of the loop on the
End, Leave, and Iterate instructions.
• Example:
Do outer = 1
.......
Do inner = 1
.....
If ... Then Iterate inner
If ... Then Iterate outer
If ... Then Leave outer
If ... Then Leave inner
End inner
.......
End outer
.......
Figure 3-28. How do we know which loop? ES52G5.0
Notes:
You may include a loop control variable name (if one exists) on the Leave or Iterate instruction to
control which loop is being affected by those instructions. Without the control variable name, you
will leave or iterate the currently active loop.
In the example on the visual, the logic that controls the loops only occurs inside the loops, not on
the Do instructions. Hence, the While or Until methods of loop control would only lead to more
complex programming, and more potential errors. The use of Leave and Iterate lead to a simpler
program. The use of the loop control variable allows us to explicitly identify to which loop the End,
Leave, and Iterate instructions refer.
V10.1
Student Notebook
Uempty
Checkpoint (1 of 3)
1. What are the four “not equal” comparison operators?
2. What are the five types of loop control?
3. True or False: In REXX, 0 means True, and 1 means False.
4. True or False: In REXX, string comparisons are always strict

comparisons.
Notes:

Student Notebook
Checkpoint (2 of 3)
5. Numeric comparisons are performed when (blank).
6. The comparison operator (blank) means Greater Than or

Equal To.
7. The Do Until loop is always executed (blank).
8. True or False: Logical operators are evaluated after

comparison operators.
Notes:
V10.1
Student Notebook
Uempty
Checkpoint (3 of 3)
9. How many times will the following loop execute?
Do i = 0.1 To 5 By 0.4
Say “Hello”
End i
10. In a Select construct, if no logical expression is found to be

true, what will happen?

Do i = 1
...some instructions...
End i
Notes:

Student Notebook
Unit summary
– Comparisons
– Logical expressions
– If-Then-Else
– Select-When-Then-Otherwise
– Looping structures
Notes:
V10.1
Student Notebook
Uempty
Unit 4. Functions and subroutines

This unit describes the usage and coding of functions and subroutines in
REXX.

• Understand the differences between functions and subroutines
• Discuss REXX built-in functions
• Understand the differences between internal and external routines
• Code internal and external functions
• Code internal and external subroutines

Accountability:
• Exercises
References
© Copyright IBM Corp. 1999, 2016 Unit 4. Functions and subroutines 4-1
Student Notebook
Unit objectives
• Understand the differences between internal and external
routines
• Code internal and external subroutines
Notes:
V10.1
Student Notebook
Uempty
Subroutines and functions

• Subroutines and functions consist of instructions that can
receive data, process data, and return a value.
– To call a subroutine, use the CALL instruction. The subroutine call is
an entire instruction:
• CALL subroutine_name argument1, argument2, argument3,....
– A function call is part of an instruction, for example, an assignment
instruction:
• var1 = function(argument1, argument2, argument3,.....)
• Routines are either:
– Built-in (part of the language definition)
– Internal (within the current exec)
– External (program written in REXX or other language)
• The search order for functions is: internal routines take
precedence, then built-in functions, and finally external
functions. © Copyright IBM Corporation 1999, 2016
Figure 4-2. Subroutines and functions ES52G5.0
Notes:
Calling a subroutine: To call a subroutine, use the CALL instruction. The subroutine call is an entire
instruction:
CALL subroutine_name argument1, argument2, argument3,....
A subroutine does not have to return a value, but when it does, it sends back the value with the
RETURN instruction.
RETURN value
The calling exec receives the value in the REXX special variable named RESULT.
SAY 'The answer is' RESULT
Calling a function: A function call is part of an instruction, for example, and assignment instruction:
var1 = function(argument1, argument2, argument3,.....)
A function must return a value. The value replaces the function call, so that in the previous
example, var1 = value.
SAY 'The answer is' var1
Student Notebook
What is a function?
• A program or routine that returns a value to the calling program
• The returned value is a single string
• The returned value replaces the function call, so functions
almost never stand-alone
• Syntax:
functionname(argument1,argument2,...)
• Example:
parm = "This is the argument."
n = Words(parm)
<words function>
Figure 4-3. What is a function? ES52G5.0
Notes:
A function is a routine that must return a value to the calling program. In REXX, this value is
returned as a single string of data. Control is returned to the same statement that contained the
function call, and the returned value replaces the function call. This is why functions are almost
never found by themselves on a line in a REXX program - when the value is returned, REXX would
then try to execute it, and the value is almost never executable code.
REXX recognizes a function by the left parenthesis “(” which immediately follows the function name.
No spaces are allowed between the function name and the left parenthesis. Arguments that are to
be passed to the function are included within the parentheses. A function may have a variable
number of arguments; some arguments may be required and some may be optional.
Most REXX implementations, including z/OS, limit the total number of arguments to twenty. The
arguments are separated by commas. Each argument is a REXX expression, which is any
combination of literals, variables, functions, or other operator characters. This means that a function
maybe coded as an argument to another function.
V10.1
Student Notebook
Uempty
Types of functions
• Internal (coded as part of your program)
• Built-in (provided by the language implementation)
• External
– TSO/E external
– Your own REXX code
– Programs in other languages
• Search order:
1. Internal
2. REXX built-in
3. TSO/E external
4. Function packages
5. Programs in other languages
6. External execs and CLISTs
Figure 4-4. Types of functions ES52G5.0
Notes:
Internal functions are ones that you write yourself, and include within your own exec.
Built-in functions are provided by the REXX implementation. Many built-in functions are available
cross-platform - they are the same on multiple implementations of REXX.
External functions come from many sources. Some come from TSO/E and are documented in the
same chapter of the manual as the built-in functions. Others you write yourself, in REXX or in other
languages.
The search order is: internal functions, built-in functions, then external functions. As external
functions may be either REXX execs or load modules, there is still some ambiguity as to which is
searched first. The default search order is shown in the visual above.
By default, program (load module) libraries are searched before external exec libraries. There is a
customization flag (called FUNCSOFL) which can be used to reverse this search order. This flag is
a bit setting in a control block, and must be flipped by using a program that you write. There is no
TSO/E command nor REXX instruction to change this search order.
Student Notebook
Writing a subroutine
• Ex 1: Internal subroutine • Ex 2: External subroutine
Figure 4-5. Writing a subroutine ES52G5.0
Notes:
The instruction that invokes the subroutine is the CALL instruction. The CALL instruction may be
used several times in an exec to invoke the same subroutine.
When the subroutine ends, it can return control to the instruction that directly follows the subroutine
call.
The instruction that returns control is the RETURN instruction.
Subroutines may be internal and designated by a label as in example 1, or they may be external
and designated by the data set member name that contains the subroutine.
The example 2 illustrates an external subroutine.
User written external subroutines must reside in an execution library that is part of the implicit
search order, for example SYSEXEC or SYSPROC, or be in the same PDS.
Note: Because internal functions and subroutines generally appear after the main part of the exec,
when you have an internal function or subroutine, it is important to end the main part of the exec
with the EXIT instruction.
V10.1
Student Notebook
Uempty
Writing a function
• Example 1: Internal function • Example 2: External function
Figure 4-6. Writing a function ES52G5.0
Notes:
An exec invokes a user-written function the same way it invokes a built-in function -- by the function
name immediately followed by parentheses with no blanks in between. The parentheses can
contain up to 20 arguments or no arguments at all.
function(argument1, argument2,...)
or
function()
A function requires a returned value because the function call generally appears in an expression.
x = function(argument1, argument2,...)
When the function ends, it uses the RETURN instruction to send back a value.
The example 1 illustrates an internal function. The example 2 illustrates an external function.
User written external functions must reside in an execution library that is part of the implicit search
order, for example SYSEXEC or SYSPROC, or be in the same PDS.
Student Notebook
Here is an example of an internal function that adds three numbers. Note the commas (,) between
the function's arguments which are the variables “number1”, “number2”, and “number3”.
/* REXX - internal "ADD3" function example */
v1 = add3(10,20,30)
v2 = add3(5,100,25)
SAY "V1=" v1
SAY "V2=" v2
EXIT /* be sure to include for internal function calls */
Add3:
ARG number1, number2, number3
answer = number1 + number2 + number3
RETURN answer
V1= 60
V2= 130
The following illustrates ADD3 written as an external function.
REXX.EXEC(MYPGM)
/* REXX - external function call example */
v1 = add3(10,20,30)
v2 = add3(5,100,25)
SAY "V1=" v1
SAY "V2=" v2
EXIT
REXX.EXEC(ADD3)
/* REXX - ADD3 function to add 3 numbers */
ARG number1, number2, number3
answer = number1 + number2 + number3
RETURN answer
V10.1
Student Notebook
Uempty
Built-in functions
• Probably the simplest and most useful
• Several types:
– String manipulation
– Comparison
– Formatting
– Conversion
– Binary
– Arithmetic
– Information
– Program diagnostic
Figure 4-7. Built-in functions ES52G5.0
Notes:
Much of the rest of this discussion will focus on the built-in functions, as they are some of the most
useful functions, and they are the simplest to code. After all, the functions are already there, all you
have to do is call them from your program. For the purposes of this discussion, the TSO/E external
functions will also fall into this same category - they already exist, all you have to do is call them.
More complex aspects of functions will come later.
The visual above breaks the built-in functions into different categories. Some of the functions that
belong in each category will be shown on the following pages.
Student Notebook
String manipulation
• About 30 string manipulation functions
• Defaults exist where defaults make sense
• Pad character often optional (typically defaults to blank)
• Count characters, truncate strings
• Search strings, edit strings, translate strings
• Word oriented and character oriented
• “Word" means blank delimited text
• Parse instruction also does string manipulation
Figure 4-8. String manipulation ES52G5.0
Notes:
There are about thirty string manipulation functions that are built-in to REXX. Some of them work on
a character-by-character basis, while others work on a word-by-word basis. Remember that in
REXX, the term “word” means “blank delimited text.”
Many functions have optional arguments. These optional arguments often have sensible default
values if the argument is not coded. For example, most functions that include a pad character as an
argument will default the pad character to a blank.
It is useful to remember that the Parse instruction also has very strong string manipulation
capabilities. Depending on what you want to do, you can decide to use either functions or the Parse
instruction, whichever is easier and gives the best results at the time.
V10.1
Student Notebook
Uempty
String manipulation functions

• These functions extract data from strings:
– Substr(), Strip(), Left(), Right(), Delstr()
• These functions add data to strings:
– Insert(), Center(), Left(), Right(),
– Justify(), Overlay()
• These functions find data within strings:
– Pos(), Lastpos(), Verify(), Abbrev()
• These functions manipulate in "words":
– Word(), Wordindex(), Wordlength(), Wordpos()
– Words(), Delword(), Subword()
• To count the number of characters in a string -- Length()
• To translate a string -- Translate()
• To reverse the characters in a string -- Reverse()
Figure 4-9. String manipulation functions ES52G5.0
Notes:
The visual above shows some of the names of the different types of string manipulation functions.
Student Notebook
Substr()
• The Substr() function breaks an input string into parts and
returns one of the parts
• Syntax:
Substr(input,n )
,length
,pad
• input is the input string to be divided
• n is the character position where the division is to occur
• length is the number of characters to be returned
• pad is used as a fill character, if needed
• Example:
– x = Substr('abcdefg',3)
– x = Substr('abcdefg',3,4)
– x = Substr('abcdefg',3,7,'!')
Figure 4-10. Substr() ES52G5.0
Notes:
The Substr() function (pronounced “substring”) returns a portion of an input character string.
The first argument is the input string to be divided. The second argument is a number, which is the
character position in the input string where the division is to occur. The third and fourth arguments
are optional. The default for Substr() is to return the rest of the input string back to the caller.
The third argument is the number of characters Substr() is to return to the caller. If this number
exceeds the number of characters remaining in the input string, the returned string is padded with
the pad character, which is the fourth argument. The default pad character is a blank.
What will be the results of the examples in the visual?
V10.1
Student Notebook
Uempty
Comparison functions
• To test the type of data:
Datatype()
• To compare one string with another:
Compare()
Figure 4-11. Comparison functions ES52G5.0
Notes:
The visual above shows two comparison functions. The Datatype() function is very important. You
should know how this function works.
Student Notebook
Formatting functions
• Center(), Centre()
• Copies()
• Format()
• Justify()
• Left()
• Right()
• Space()
• Strip()
Figure 4-12. Formatting functions ES52G5.0
Notes:
Note that both the US English and the UK English spellings of “Center” are accepted.
To make multiple copies of a string, use Copies().
To format and round a number, use Format().
To add or delete spaces and other characters between words, use Space().
To remove leading and/or trailing characters from a string, use Strip().
V10.1
Student Notebook
Uempty
Conversion functions
• Convert data between Character, Hexadecimal, and Decimal
– In any combination using:
• C2X(), X2C(), C2D(), D2C(), D2X(), X2D()
– Convert between Binary and Hexadecimal
• B2X(), X2B()
'A'
X2C() C2D()
C2X() D2C()
X2D()
'C1' '193'
D2X()
X2B() B2X()
'1100 0001'
Figure 4-13. Conversion functions ES52G5.0
Notes:
These functions are very useful when you are trying to deal with hexadecimal or binary values in
REXX. You can convert in any direction between character, hexadecimal, and decimal values.
You can also convert between hexadecimal and binary values.
Student Notebook
Other functions
• Binary logic functions:
– Bitand()
– Bitor()
– Bitxor()
• Numeric functions:
– Abs(), Min(), Max(), Sign(), Trunc(), Format()
– Random()
– Digits(), Form(), Fuzz()
Figure 4-14. Other functions ES52G5.0
Notes:
The binary functions shown on the visual can manipulate data at the bit level.
The numeric functions are designed to deal with REXX numbers.
V10.1
Student Notebook
Uempty
Informational functions
• General informational functions:
– Date(), Time(), Userid()
• Sysprog information functions:
– SYSVAR(), MVSVAR(), SYSCPUS()
• Program diagnostic functions:
– Sourceline(), Errortext(), Condition()
• Terminal width:
– Linesize()
Figure 4-15. Informational functions ES52G5.0
Notes:
The second set of functions above, SYSVAR(), MVSVAR(), and SYSCPUS() are TSO/E external
functions. These functions are not built-in to REXX, but are supplied as part of TSO/E. Even though
they are TSO/E functions, they are only usable within REXX execs. They are also, of course, not
necessarily available in other implementations of REXX.
Student Notebook
Subroutines
• Minor differences between functions and subroutines:
Functions Subroutines
Must return a value May or may not return a value
Returned value replaces Returned value stored in Rexx
function call special variable "result"
Invoked with function call: Invoked with Call instruction:
functionname(args) Call subroutinename args
• All functions can be called as subroutines.
Figure 4-16. Subroutines ES52G5.0
Notes:
Functions and subroutines are very similar to each other, though there are some minor differences.
First, a function absolutely must return a value to the calling program, otherwise the program fails. A
subroutine may or may not return a value to the caller.
Second, when a function returns its value, the value replaces the function call in the calling
program. If a subroutine returns a value, the value is automatically assigned to the REXX special
variable called “result”.
Finally, the function is recognized by the left parenthesis that immediately follows the function
name. A subroutine is invoked with the REXX instruction “Call.”
All functions can be invoked with a Call instruction, so all functions can be used as subroutines. As
subroutines are not required to return a value, not all subroutines can be invoked as functions.
V10.1
Student Notebook
Uempty
Why should we code functions/subroutines?

• Necessary for structured programming
– Avoid "spaghetti-code"
• Break the program up into modules
• Reuse code wherever possible
– Execute the same code from several locations in a program
• Functions and subroutines can be either internal or external
– Execute the same code from several different programs
Figure 4-17. Why should we code functions/subroutines? ES52G5.0
Notes:
Functions and subroutines (hereafter collectively called “subprocedures”) are necessary to maintain
a structured programming paradigm, and to avoid the “spaghetti-code” of non-structured
programming languages. You can often modularize a program, with each module being written as a
subprocedure. The mainline portion of the program then would just place calls to these various
subprocedures, where the real work would take place.
Using subprocedures allows you to execute the same code from various parts of your program
without having to rewrite the same lines of code over and over again. As they can be external to
your program, it also allows you to reuse the same code in several different programs that need to
perform the same tasks.
Student Notebook
Coding internal subprocedures

• REXX looks for internal functions or subroutines first
• Internal subprocedure is marked by a label:
– Symbol name followed by colon (:)
• Code is executed until Return keyword instruction (different
from Exit keyword instruction!)
• Internal subprocedures are part of the same program,
therefore all variables are shared by default
– Internal subprocedures can protect some or all variables with the
Procedure keyword instruction
• Remember to isolate internal subprocedures with a preceding
Return or Exit instruction
Figure 4-18. Coding internal subprocedures ES52G5.0
Notes:
Once REXX knows it has to look for a subprocedure, it does exactly the same thing whether it is a
subroutine or a function. First it looks for the name of the subprocedure as a label in the currently
executing exec. This is an internal subprocedure. A label is a name (or symbol) followed
immediately by a colon ( : ).
If the label is found, control is transferred to the label, and the REXX instructions following the label
are executed until a Return keyword instruction is encountered. The Return instruction will cause
REXX to return control back up into the main line program.
If a function is being executed, Return must be followed by an expression which will be evaluated.
This will become the value the function returns to the main program.
If a subroutine is being executed, then the Return instruction does not have to be followed by a
value. If a value is returned, it will be assigned to the REXX special variable “result” in the main
program.
V10.1
Student Notebook
Uempty
Internal subprocedure example

...
Call Sub1 parm1,parm2
...
Main ...
Program x=Sub1(parm1,parm2)
...
...
Exit
Internal Sub1:
subpro- Procedure
...
cedure
Return
Figure 4-19. Internal subprocedure example ES52G5.0
Notes:
The subprocedure itself is coded in much the same way whether it is a function or a subroutine. The
biggest difference is whether or not it must return a value to the calling program. Functions must
return a value, subroutines may or may not.
Note the Exit instruction before the subprocedure. This prevents accidentally falling through into the
internal subprocedure code. A Return instruction could have been used here instead.
Student Notebook
Procedure instruction
• Without Procedure instruction, all variables are shared
between main program and internal subprocedure.
• With Procedure instruction, no variables are shared between
main program and internal subprocedure.
• Adding Expose keyword to Procedure instruction allows
some variables to be shared, but not others.
– Variables to be shared may be created anywhere
• Example:
Sub1:
Procedure Expose var1 var2 var3
....
Return Only these variables
will be shared,
and no others.
Figure 4-20. Procedure instruction ES52G5.0
Notes:
The Procedure instruction is used to prevent REXX from automatically sharing variables between
the main program and an internal subprocedure. The programmer has complete control over how
much variable sharing is to take place.
The Procedure instruction is very useful if you want to reuse some variable names in the internal
subprocedure, but not have those variables with the same names modified in the main program. It
is also useful if you intend to eventually externalize the subprocedure.
V10.1
Student Notebook
Uempty
Coding external subprocedures

• Create subprocedures as members of a PDS concatenated to
//SYSEXEC or //SYSPROC
• Subprocedure name is member name: limited to PDS member
naming rules (no label is required)
• The Exit keyword instruction is identical to the Return
keyword instruction
• External subprocedures maintain separate variable pools; no
variable sharing is allowed (that is, Procedure instruction is
implied, with no Expose)
Figure 4-21. Coding external subprocedures ES52G5.0
Notes:
As your application grows, you may want to place subprocedures in separate members of the PDS
concatenation. This also facilitates reusing code in multiple programs.
The Return and the Exit keyword instructions will both act in the same way here. They will both
return control to the calling program.
Internal subprocedures can use REXX naming rules (same rules as for variable names), but
external ones must conform to PDS member naming rules (1 to 8 characters, alpha, numeric, or the
national character set: @ # $, and the first character cannot be a number).
A REXX program is all of the code within one member of a data set, and it uses one pool of
variables. Another program gets another pool of variables, so you will not have conflicting variable
names. That means that an internal subprocedure can and will share variables with the main
program (unless the Procedure instruction is used), but an external one cannot. The variables in the
main program are not available to an external subprocedure, and the variables in an external
subprocedure are not available to the main program. This provides a greater level of isolation and
integrity for complex applications.
Student Notebook
Returning values from subprocedures

• Value returned from function replaces function call
• Value returned from subroutine stored in REXX special
variable called result
...
Call Sub1 parm1, parm2
Say result
Main ...
Program x=Sub1(a,b)
...
...
Exit
Internal Sub1:
subpro- Procedure
cedure ...
Return value
Figure 4-22. Returning values from subprocedures ES52G5.0
Notes:
When a subroutine returns a value, it is returned to the REXX special variable called ‘result.’
When a function returns a value, it replaces the function call.
V10.1
Student Notebook
Uempty
Passing arguments to subprocedures

• Up to 20 argument strings are passed to the subprocedure:
x = myrtn(argstr1,argstr2,...,argstr20)
Call myrtn argstr1,argstr2,...,argstr20
• Argument strings are received at the subprocedure with the
Parse Arg instruction:
Parse Arg template1, template2,...,template20
• Can also use Arg() function.
• Only one argument string can be passed when calling an exec
as a command.
Figure 4-23. Passing arguments to subprocedures ES52G5.0
Notes:
A call to a subprocedure may include up to twenty arguments, more properly called argument
strings. Each argument string is a REXX expression, which contains any combination of literals,
variables, functions, or other operator characters (arithmetic, concatenation, comparison, or logical
operators). Therefore, each argument to a subprocedure may contain many words of data.
Just as input arguments passed to an exec from the command line are received by the Parse Arg
instruction, the argument strings passed by a subprocedure are received by a Parse Arg instruction
as well.
The Parse Arg instruction contains a parsing template, which describes how the input arguments
are to be broken up and assigned to variables. In a call to a subprocedure, each comma delimited
argument string is parsed separately by multiple comma delimited parsing templates coded in the
Parse Arg instruction.
The Arg() function can be used to parse multiple input argument strings as well.
When invoking an exec as though it were a command, only one argument string is allowed.
Student Notebook
Passing arguments: Example 1

arga = 'One';argb = 'Two';argc = 'Three'
argd = 'Four Five';arge = 'Six Seven Eight'
Call myrtn arga,argb,argc,argd,arge
....
Myrtn:
Procedure
Parse Arg var1,var2,var3,var4
Parse Upper Arg var1,var2,var3,var4 var5,var6
Parse Arg var1 var2,var3,var4,var5,var6 var7 var8
What value is assigned to each variable?
Figure 4-24. Passing arguments: Example 1 ES52G5.0
Notes:
In the Call instruction, each comma delimited argument string is first evaluated by REXX, and the
result of these evaluations are then passed to the subroutine. The Parse Arg instruction in the
subroutine parses each argument string with its own comma delimited parsing template.
What value is assigned to each variable in the examples above?
V10.1
Student Notebook
Uempty
Passing arguments: Example 2

arga = 'One';argb = 'Two';argc = 'Three'
argd = 'Four Five';arge = 'Six Seven Eight'
Call myrtn arga argb,argc argd,arge
....
Myrtn:
Procedure
Parse Arg var1,var2,var3,var4
Parse Arg var1 var2,var3 var4,var5 var6
Parse Arg var1 var2,,var4 var5 var6 var7 var8
What value is assigned to each variable?
Figure 4-25. Passing arguments: Example 2 ES52G5.0
Notes:
Here are some more examples. Again, what value is assigned to each variable in the examples
above?
Student Notebook
Checkpoint (1 of 2)
1. What is the purpose of a function?
2. An internal subprocedure should be preceded by a (blank) or

(blank) keyword instruction.
3. Internal subprocedures can use (blank) naming rules, but

external ones must conform to (blank) naming rules.
4. True or False: When returning from a function, control is

returned to the next instruction following the function call.
Notes:
V10.1
Student Notebook
Uempty
Checkpoint (2 of 2)
5. True or False: Subroutines do not have to return a value to
the calling program.
6. True or False: All functions can be called as subroutines.
7. True or False: All subroutines can be called as functions.
8. You can pass up to (blank) arguments to a subprocedure.
9. REXX searches for (blank) subprocedures first.
Notes:
Student Notebook
Unit summary
• Understand the differences between internal and external
routines
• Code external and external subroutines
Notes:
V10.1
Student Notebook
Uempty
Unit 5. Debugging and error handling

This unit discusses ways to write easy-to-maintain REXX programs and
routines, describing standards of professionalism, coding style, common
program layout, error handling, and integrity.

• Discuss program design and coding style
• Use the Trace instruction
• Use the Signal instruction
• Understand other debugging aids
• Write error handling routines

Accountability:
• Exercises
References
© Copyright IBM Corp. 1999, 2016 Unit 5. Debugging and error handling 5-1
Student Notebook
Unit objectives
Notes:
V10.1
Student Notebook
Uempty
Professionalism aims
• Your programs should:
– Be reliable, that is, it does what it is supposed to do
– Be able to cope with the unexpected
– Issue meaningful error messages to users
– Set a non-zero return code on failure
– Be easy to maintain!
Figure 5-2. Professionalism aims ES52G5.0
Notes:
The statement “REXX is simple and easy to write” has encouraged many people to write unreliable
programs. REXX execs can be written in many different ways, using many different styles. A REXX
programmer should be no different than a COBOL, PL/1, or C programmer: standards of
professionalism should be maintained.
Proper coding will save a lot of time for the programmer, for the maintainer, and for the users of the
program. To this end many application development groups have implemented policies and
procedures governing standards to which programmers are required to adhere.
Student Notebook
Ease of maintenance
• Always include good comments
• Most execs follow a common layout:
– Documentation including change history
– Mainline routine
– Subprocedures
– Error recovery routines
• Use sensible variable names -- long(?) and descriptive
• Try to adopt a consistent design methodology
• Develop a coding style!
Figure 5-3. Ease of maintenance ES52G5.0
Notes:
Start your exec with a comment like this:
/* Rexx exec execname will .... */
You can provide plenty of documentation in that initial comment. Perhaps twenty to forty lines might
be all the documentation required. If a team is responsible for the exec, a change history log should
be included in the initial comments. The change history should include such things as the date, who
made the change, why the change was made, what the change did, and so forth.
Most execs will typically follow a fairly common layout. The exec should have a mainline routine,
then internal subprocedures (if any), then error recovery routines.
Variables should have long and descriptive names. The term long is relative, though. What one
programmer might consider a reasonable length, another may consider to be too long. The keyword
here is “descriptive.” Variable names should describe the data or purpose for which they are
being used. Variable names such as “abc,” “xyz”, or single character variable names should be
avoided.
V10.1
Student Notebook
Uempty
Signal instruction
• Causes unusual transfer of control
• Used to trap error conditions
• Destroys control structures
– Do - End, If, Select
• Five signal trapnames:
– Error
– Failure
– Halt
– Novalue
– Syntax
• Instruction syntax:
Signal On <trapname>
Signal Off <trapname>
Figure 5-4. Signal instruction ES52G5.0
Notes:
The Signal instruction is typically coded at or near the beginning of the program to set a trap for
various error conditions which may occur. If the error does occur, the trap “springs,” and control is
immediately transferred to an error handling routine.
The “Signal On <trapname>” instruction is used to set condition traps. The trapname can be:
• Novalue – uninitialized variable has been used (next page)
• Error – non-zero return code from host command
• Failure – negative return code from host command
• Halt – external attempt to interrupt exec: PA1, then HI
• Syntax – syntax errors and runtime errors
To turn the error trap off, code “Signal Off <trapname>”. Multiple signal traps may be set, and
they may be turned on and off anywhere in the program. You must code a separate Signal
instruction for each trap.
Student Notebook
Signal On Novalue
• Uninitialized variable (default value -- variable's own name in
upper case)
• Huge source of errors
• Causes logic errors, strange or incorrect program flow
• Error messages often do not point at true cause of error
• Almost every exec should include Signal On Novalue at or
near the beginning of the program
Figure 5-5. Signal On Novalue ES52G5.0
Notes:
As REXX was originally defined, uninitialized variables were given a default value, which is the
same as the variable name in uppercase. Use of this rule can lead to logic errors and sometimes
perplexing program flow. These errors are often hard to diagnose as the system may detect an
error, and point to somewhere else from the true error location.
The Signal On Novalue instruction was provided to remove this situation and replace it with a new
rule: all variables must be assigned a value before they are used.
V10.1
Student Notebook
Uempty
Return codes from host commands

• Always check the return code from host commands!
• The command is almost always useless if it fails.
• By default, the REXX exec will continue executing.
• Special (reserved) variable name, rc, contains return code
from last host command.
• Using Signal On Error helps as it checks automatically.
Figure 5-6. Return codes from host commands ES52G5.0
Notes:
You must always check the return code (held in the special variable rc) of all host commands. The
command is typically useless if it fails. For example, if you allocate a data set, perform data set I/O,
or display a panel, the exec almost always cannot be allowed to continue if the command fails. Yet,
that is the default action of the REXX exec. If the command fails, the exec keeps going. It is
therefore the responsibility of the programmer to ensure the host command was successful.
You have a choice of one of two techniques:
• Signal On Error – useful if all non-zero return codes represent failures and no recovery is
possible. Some host commands set expected non-zero return codes.
• Check the variable rc after each command.
It is very common for programmers to omit these checks. As a result, it is common for execs to
have erratic and unpredictable failures
Student Notebook
Return code conventions

• 0 = complete, unambiguous success
• 4 = very likely successful, but warning
• 8 = probable failure, but the system is still working
• 12 = certain failure
• 16 = worse than 12
• 20 = fundamental system environment error
Figure 5-7. Return code conventions ES52G5.0
Notes:
The return codes listed on the visual above are the conventions for IBM products in the z/OS
environment. The reason they step up by four is related to an Assembler programming feature used
to process return codes. You do not need to restrict yourself to these values, but if they are not
inconvenient, you might as well do so. You should at least include comments in your program and
issue meaningful error messages when using unconventional return code values.
Certainly, the convention that “0 means complete unambiguous success” is an important
convention to adhere to.
V10.1
Student Notebook
Uempty
Recovery and integrity

• You must consider the intended user of the exec:
– Yourself
– Others in your team
– Other programmers
– End users
Figure 5-8. Recovery and integrity ES52G5.0
Notes:
The standard of program coding related to recovery, integrity, messages, and diagnostics depends
very much on who will be the intended user of the exec. You should also consider whether the end
user can be expected to read and modify the code.
The highest standards are required when the exec is to be used by non-programmer end users,
especially when it is part of the production work at the site.
One thing to remember is that execs that you write exclusively for your own use often wind up being
used by others. They will not be impressed when, if your exec breaks, you say to them, “Well, I
never intended for you to use my exec in the first place.” You may as well code all of your execs so
that anyone can use them.
Student Notebook
Diagnostic functions
• Sourceline()
– Returns number of lines of code, or actual line of source code
• Condition()
– Returns information depending on one of four arguments
• Errortext()
– Returns text of REXX error message associated with argument
number
• REXX special variable sigl
– Assigned with line number where condition trap error occurred
Figure 5-9. Diagnostic functions ES52G5.0
Notes:
The functions shown on the visual above are most useful in error handling routines.
The REXX special variable called sigl is automatically assigned with the line number where the
condition trap, set with the Signal On instruction, was sprung. In other words, this is the line number
where the error occurred. This variable can then be used in the error recovery routine.
The Sourceline() function accepts zero or one argument. With no arguments Sourceline() returns
the number of lines of code in the REXX exec. The argument you can provide is a whole number,
and Sourceline() will then return the content of the source code from that line in the exec.
The Condition() function accepts one argument, which can be C, D, I, or S. The value returned
depends on which argument value is passed to Condition().
The Errortext() function will return the text of the REXX error message associated with the whole
number argument passed to the function. This is a number between 0 and 99. If there is no REXX
error message associated with the error number, a null value is returned.
V10.1
Student Notebook
Uempty
Coding for error recovery (1 of 2)
Novalue: /* Uninitialized variable used */

Trace N
Say "Exec VMCAT: Uninitialized variable used,",
"at source line" sigl
Say "Name of uninitialized variable:" Condition('D')
Say "Source code statement from VMCAT:"
Say Sourceline(sigl)
Exit 20
Figure 5-10. Coding for error recovery (1 of 2) ES52G5.0
Notes:
The visual above shows an example of an error recovery routine for the Novalue condition.
Student Notebook
Coding for error recovery (2 of 2)
Error: /* non-zero return code from the host environment */
Signal Off Error

Signal Off Novalue
Trace N
Do While Queued() \= 0
Parse Pull
End /* must clear the stack */
Say "Exec VMCAT: Host command (TSO/ISPF) failed or data format error,",
"source line =" sigl
Say "rc =" rc
Say "ISPF error message text (zerrlm):"
Say zerrlm
zispfrc = 20
Address ISPEXEC 'VPUT (ZISPFRC) SHARED'
Exit 20
Figure 5-11. Coding for error recovery (2 of 2) ES52G5.0
Notes:
The visual above shows a more involved example of an error recovery routine for the Error
condition.
V10.1
Student Notebook
Uempty
Testing
• Amount of testing depends on intended end user scale
• Start testing with less data
• Test all parts of the code
• Test recovery from error situations
– Force the error
• Use REXX aids to confirm the program flow
– Trace instruction
Figure 5-12. Testing ES52G5.0
Notes:
If your program reads a large data set, you can create a smaller version with typical data for your
initial testing. Keep that data set, as you will probably need it during maintenance. Make sure that
your program can detect bad data by placing incorrect data in the test data set.
Make sure you test all parts of your code. Unless you actually execute the code, the REXX
interpreter does not check the syntax. The compiler does: that is an integrity benefit of the compiler.
You can use the REXX tracing facilities during testing to confirm that the exec is doing what you
expect. As it is so easy to add tracing in REXX, it is not usually necessary to place debugging code
in a REXX exec.
Student Notebook
Trace instruction
• REXX Trace instruction - useful options
– Trace R – "Results" – most useful
– Trace N – "Normal" – traces negative return codes
– Trace O – "Off" – turns tracing off
– Trace I – "Intermediates" – most information
• Other trace options:
– A, C, E, F, L, S, ?, !, +n, -n
• Trace without modifying the code:
– TSO/E command EXECUTIL TS - before running exec
• REXX Trace() function
– trace_actions_in_effect = Trace()
Figure 5-13. Trace instruction ES52G5.0
Notes:
We introduced the Trace instruction earlier in the course, and discussed the trace options listed
under the first bullet point in the visual above.
The second bullet point shows the other trace options, which are of lesser use. The “+n” and “-n”
indicate positive and negative numbers. The “?” places your exec into interactive debugging mode,
which is discussed on the next page.
What if you cannot put a Trace instruction into an exec to trace its execution? The TSO command
EXECUTIL can be used to “turn on” tracing mode before starting the exec. Entering
EXECUTIL TS
just before starting the exec will start the exec in normal interactive debug mode.
The Trace() function returns the current tracing options.
V10.1
Student Notebook
Uempty In order to aid in debugging an exec with an error condition or a logic problem, REXX provides a
powerful TRACE instruction. You can use the TRACE instruction to display how the language
processor evaluates each operation of an expression as it reads it (TRACE I), or to display the final
result of an expression (TRACE R). These two types of tracing are useful for debugging execs,
however, there are also many other TRACE options (?,A,C,E,F,I,L,N,O,R).
Tracing Operations: To trace operations within an expression, use the TRACE I (TRACE
Intermediates) form of the TRACE instruction. All expressions that follow the instruction are then
broken down by operation and analyzed as:
>V> Variable value - The data traced is the contents of a variable.
>L> Literal value - The data traced is a literal (string, uninitialized variable, or constant).
>O> Operation result - The data traced is the result of an operation on two terms.
>F> Function result - The data traced is the result of a function call.
>C> Compound variable - The data traced is the name of a compound variable
>P> Prefix operation - The data traced is the result of a prefix operation
Other trace output is as follows:

*-* A source line from the program
+++ A trace message from REXX
>>> An expression result (TRACE R)
>.> A value assigned to a place holder
Example using TRACE I:
EDIT USERID.REXX.EXEC(TRACEI) Columns 00001 00072
Command ===> Scroll ===> CSR
***************************** Top of Data *****************************
000001 /* rexx */
000002 x = 9
000003 y = 2
000004 TRACE I
000005 IF x + 1 > 5 * y THEN
000006 SAY 'x is big enough.'
000007 ELSE NOP /* No operation on the ELSE path */
**************************** Bottom of Data ***************************
Student Notebook

5 *-* IF x + 1 > 5 * y
>V> "9"
>L> "1"
>O> "10"
>L> "5"
>V> "2"
>O> "10"
>O> "0"
7 *-* ELSE
*-* NOP /* No operation on the ELSE path */
First you see the line number (5 *-*) followed by the expression. Then the expression is broken
down by operation as follows:
>V> "9" (value of variable x)
>L> "1" (value of literal 1)
>O> "10" (result of operation x + 1)
>L> "5" (value of literal 5)
>V> "2" (value of variable y)
>O> "10" (result of operation 5 * y)
>O> "0" (result of final operation 10 > 10 is false)
Tracing Results: To trace only the final result of an expression, use the TRACE R (TRACE Results)
form of the TRACE instruction. All expressions that follow the instruction are analyzed and the
results are displayed as:
>>> Final result of an expression
If you changed the TRACE instruction operand in the previous example from an I to an R, you
would see the following results.
5 *-* IF x + 1 > 5 * y
>>> "0"
7 *-* ELSE
With interactive debugging, you also have the ability to single or multi-step though instructions. The
language processor will pause between instructions to await debug input. While paused you can
enter any commands or REXX statements or re-execute the last instruction.
To enable interactive debug prefix the TRACE action with a ? (for example TRACE ?R). Using the
previous example with TRACE ?R you would see the following:
5 *-* IF x + 1 > 5 * y
>>> "0"
+++ Interactive trace. TRACE OFF to end debug, ENTER to continue. +++
V10.1
Student Notebook
Uempty After pressing ENTER, you would step though to the next result (if any) and the language processor
would pause awaiting input.
7 *-* ELSE
While paused you can continue tracing by entering a null line, type one or more additional
instructions to be processed before the next instruction is traced, enter an equal sign (=) to
re-execute the last instruction, or change trace options. For example, TRACE N (TRACE Normal)
would turn back the default tracing options (trace failures only), TRACE O (TRACE Off) would turn
off all tracing, and TRACE ? would turn off interactive tracing (but leave the current tracing options
in effect).
Student Notebook
Interactive debug
• Trace ?
• Pauses at each instruction:
– Press Enter to continue
– Type = and press Enter to re-execute last clause
– Type anything else - Like REXXTRY - process line immediately
• Trace n (or +n) - skip n pauses (n is a whole number)
Figure 5-14. Interactive debug ES52G5.0
Notes:
The Trace ? Instruction places the exec in interactive debug mode. Interactive debug mode causes
REXX to pause after executing each clause. During these pauses, the user may:
• Press Enter to continue execution to the next pause point.
• Type = and press Enter to re-execute the previous clause again.
• Type any other command to execute that command immediately (sort of like REXXTRY does).
V10.1
Student Notebook
Uempty
Other debug aids

• Attention mode (PA1) immediate commands
– HE – halt execution
– HI – halt interpretation
– TS – trace start
– TE – trace end
– HT – halt typing
– RT – resume typing
Figure 5-15. Other debug aids ES52G5.0
Notes:
These six commands are called immediate commands. They can be entered after typing the PA1
key to interrupt your exec. If, instead of typing an immediate command, you simply press Enter,
your exec will continue execution.
Student Notebook
Checkpoint
1. True or False: REXX instructions set return codes.
2. Every exec should begin with a (blank).
3. True or False: If you code a Signal instruction, you must code a label
for the condition trap.
4. The REXX special variable rc contains (blank).
5. The REXX special variable sigl contains (blank).
6. What does Trace ?R do?
Notes:
V10.1
Student Notebook
Uempty
Unit summary
Notes:
Student Notebook
V10.1
Student Notebook
Uempty
Unit 6. Executing host commands

This unit describes how to execute host commands from a REXX program. It
also discusses the REXX Address instruction and the different host
command environments, which are provided as part of the REXX
implementation under z/OS TSO/E. Other IBM program products which
interface with or exploit the REXX language are also mentioned at the end of
the unit.

• Examine available host command environments
• Define how to switch environments
• Issue host commands from a REXX program
• Identify other IBM products that work with REXX

Accountability:
• Exercises
References
© Copyright IBM Corp. 1999, 2016 Unit 6. Executing host commands 6-1
Student Notebook
Unit objectives
Notes:
V10.1
Student Notebook
Uempty
Issuing host commands

• What is a host command?
• What is a host command environment?
• REXX provides a facility to switch environments.
• Facility to check environment existence.
• A host command can be a REXX expression.
• All host commands set return codes (captured in REXX special
variable rc).
Figure 6-2. Issuing host commands ES52G5.0
Notes:
REXX provides a unique ability (among programming languages) to issue commands directly to a
host command environment or software platform. If REXX finds an expression on a line where it
would expect to find a keyword instruction, it treats that expression as a host command, and
automatically passes that command to the host command environment for execution.
This remarkable feature of REXX includes the ability to switch between many available host
command environments, as often as you want within a REXX exec.
Note that a host command is built from a REXX expression. A REXX expression contains any
combination of literals, variables, functions, or other operator characters. This means you can
construct host commands from data contained in variables in your program, results from function
calls, and so forth.
Student Notebook
REXX external environments

• One of the main reasons REXX is so powerful as a development
language
• ADDRESS instruction is used to define the external environment to
receive host commands
– Address <environment name>
• There are many different environments that provide many different
functions
– TSO
– MVS
– ISPEXEC
– ISREDIT
– CONSOLE
– LINK, LINKMVS, LINKPGM, ATTACH, ATTCHMVS, ATTCHPGM
– SYSCALL
– SDSF
– DSNREXX
– …and more
Figure 6-3. REXX external environments ES52G5.0
Notes:
Issuing commands to the surrounding environment is an integral part of REXX and one of the things
that makes REXX such a powerful tool.
Environments
The system under which REXX programs run includes at least one host command environment for
processing commands. An environment is selected by default on entry to a REXX program. In
TSO/E REXX, the environment for processing host commands is known as the host command
environment. You can change the environment by using the ADDRESS instruction. You can find out
the name of the current environment by using the ADDRESS built-in function.
TSO/E provides several host command environments for a TSO/E address space (TSO/E and
ISPF) and for non-TSO/E address spaces. For example, in REXX processing, a host command can
be:
• A TSO/E command processor, such as ALLOCATE, FREE, or EXEC.
• A TSO/E REXX command, such as NEWSTACK or QBUF.
• A program that you link to or attach.
V10.1
Student Notebook
Uempty • An MVS system or subsystem command that you invoke during an extended MCS console
session.
• An ISPF command or service.
The ADDRESS instruction
• Controls execution environment for non-REXX commands
• Can pass single command to another environment
• With no operands, returns to previous environment
ADDRESS instruction is used to define the external environment to receive host commands
For example, to set TSO/E as the environment to receive commands
ADDRESS TSO
Several host command environments available in z/OS
A few host command environments available in z/VM
/* REXX - parse example with periods as placeholders */
parse source . . . . . . . ENV . .
if ENV = 'OMVS' then do /* are we running under UNIX ? */
(instructions)
end
if ENV = 'TSO/E' then do /* are we running under TSO/E? */
(instructions)
end
if ENV = 'ISPF' then do /* are we running under ISPF? */
(instructions)
end
if ENV = 'MVS' then do /* are we running under MVS? */
(instructions)
end
Student Notebook
Host command environments

• Each address space specifies a host command environment
table
Non-TSO/E TSO/E ISPF
MVS (default) TSO (default) TSO (default)
LINK LINK LINK
ATTACH ATTACH ATTACH
CPICOMM MVS MVS
LU62 CONSOLE CONSOLE
APPCMVS CPICOMM CPICOMM
LU62 LU62
APPCMVS APPCMVS
ISPEXEC
ISREDIT
• Host command environments can come with a product

• Can write your own
Figure 6-4. Host command environments ES52G5.0
Notes:
Every address space which can run a REXX exec specifies a Host Command Environment table.
This table list the environments which are available to be used within that address space. Several
environments are provided by default as part of the z/OS installation. These are shown in the chart
in the visual above, along with the type of address space where they can be used.
Both IBM and other vendor products can provide host command environments as well. Some of the
IBM environments are mentioned at the end of this unit. An individual may also create their own
host command environment. This means, of course, that the Host Command Environment Table
can be modified.
V10.1
Student Notebook
Uempty
TSO/E REXX command SUBCOM

• Tests for the existence of what might be a valid host command
environment
• Syntax:
SUBCOM envname
where envname is the name of the host command
environment being tested
• Sets return code (captured in REXX variable rc)
– rc = 0 means envname is available
– rc = 1 means envname is not available
Figure 6-5. TSO/E REXX command SUBCOM ES52G5.0
Notes:
SUBCOM is a TSO/E command, but it is only usable in a REXX program. For this reason we call this
command, and some others, TSO/E REXX commands.
The SUBCOM command checks the Host Command Environment table for the existence of the host
command environment specified as the argument of the command. If the environment exists,
SUBCOM sets a return code of zero. If not, SUBCOM sets a return code of one.
Return code zero from SUBCOM means that you can use the REXX Address instruction to switch
to that host command environment.
Student Notebook
Switching environments
• Syntax:
Address
env
command
where env is the host command environment

and command is the host command to be executed
y The Address() function returns the current host command
environment
Figure 6-6. Switching environments ES52G5.0
Notes:
The REXX keyword instruction Address can be used to switch host command environments. You
can issue the Address instruction in your program whenever and wherever you want, but you may
only point to a host command environment which is valid for your address space. In other words,
the host command environment you name on the Address instruction must be included in the Host
Command Environment Table (see the discussion of the SUBCOM command on the previous page).
Address can either permanently or temporarily switch host command environments depending
upon which way the instruction is used.
There is also an Address() function which will return the name of the current host command
environment.
V10.1
Student Notebook
Uempty
Coding host commands

Ɣ Code your command as a REXX expression
"ALLOC DD(DDNAME) DSN('MY.DATA.SET') SHR REUSE"
Ɣ REXX expressions can contain variables
"ALLOC DD("ddname") DSN("dsn") SHR REUSE"
Ɣ Example:
If variable ddname = "SYSUT1", variable dsn = "INPUT.DATA", and
our userid is SMITH, then this REXX expression:
"ALLOC DD("ddname") DSN(" Userid()||"."||dsn ") SHR"
will produce this host command:
ALLOC DD(SYSUT1) DSN( SMITH.INPUT.DATA ) SHR
(Note the embedded blanks in the DSN parm, which is allowed by TSO)
Figure 6-7. Coding host commands ES52G5.0
Notes:
A host command is simply a REXX instruction which is unrecognized by REXX, so it is passed
outside of REXX to the host command environment for execution. Some host commands may
consist of simply one literal string, as in the first bullet point above.
All REXX instructions are coded as expressions, so your host commands can also contain REXX
variables (like the second bullet point above), function calls, comparisons, and so forth. REXX will
evaluate the expression, and the result of that evaluation becomes the host command to be
executed.
Can you spot the potential problem in the last example on the visual above?
Student Notebook
Change the host command environment

• Environment can be set for a single ADDRESS ISPEXEC /* Change environt to ISPF */
command, or for all non-REXX "EDIT DATASET("dsname")"
.
commands from a certain point instruction(s)
• Last set environment will be used if .
"SELECT PANEL(TECH001)"
REXX does not recognize a command .
• All commands instruction(s)
. .
– When an ADDRESS instruction ADDRESS TSO /* Change environt back to TSO */
includes only the name of the host "FREE FILE(WORK)"
command environment, all commands
issued afterward within that exec are
processed as that environment's /* Issue one command from the ISPF environt */
ADDRESS ISPEXEC "EDIT DATASET("dsname")"
commands. /* Return to the default TSO host command environt */
• Single command "ALLOC DA("dsname") F(SYSEXEC) SHR REUSE"
– When an ADDRESS instruction

includes both the name of the host
command environment and a
command, only that command is
affected. After the command is issued,
the former host command environment
becomes active again.
Figure 6-8. Change the host command environment ES52G5.0
Notes:
To change the host command environment, use the ADDRESS instruction followed by the name of
an environment. The ADDRESS instruction has two forms: one affects all commands issued after
the instruction, and one effects only a single command.
ADDRESS Example 1:
/* rexx */
SAY 'Do you know your PF keys?'
PULL answer
IF answer = 'NO' | answer = 'N' THEN
ADDRESS ispexec "SELECT PGM(ISPOPT) PARM(ISPOPT3)"
ELSE
SAY 'O.K. Never mind.'
V10.1
Student Notebook
Uempty ADDRESS Example 2:

/* REXX */
text = 'PROGRAM' pgname 'ABENDED. PLEASE ACKNOWLEDGE BY REPLYING!'
ltext = d2c(length(text),2)
wtor = ltext || text
ADDRESS LINKPGM "OPSWTOR wtor"
Exit 0
Student Notebook
Host command environments in z/OS

• TSO
– Used to run TSO/E commands like ALLOCATE and TRANSMIT
– Only available to REXX running in a TSO/E address space
– The default environment in a TSO/E address space
– Example:
Address TSO “ALLOC FI(INDD) DA(‘USERID.SOURCE’) SHR”
• MVS
– Use to run a subset of TSO/E commands like EXECIO and MAKEBUF
– The default environment in a non-TSO/E address space
– Example:
Address MVS “EXECIO * DISKR MYINDD (FINIS STEM MYVAR”
Figure 6-9. Host command environments in z/OS ES52G5.0
Notes:
When you invoke a REXX exec in the TSO/E address space, the default initial host command
environment is TSO (ADDRESS TSO). When you run a REXX exec in a non-TSO/E address
space, the default initial host command environment is MVS (ADDRESS MVS).
MVS
• Use to run a subset of TSO/E commands like EXECIO and MAKEBUF
• The default environment in a non-TSO/E address space, for example
• See: TSO/E REXX Reference
Address MVS "EXECIO * DISKR MYINDD (FINIS STEM MYVAR“
Address TSO
• One of the most common environments, and the default if running in a TSO/E address space
• Used to run TSO/E commands like ALLOCATE and TRANSMIT
http://www-01.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.ikja300/toc
.htm
V10.1
Student Notebook
Uempty Examples:
Address TSO "ALLOC F(SYSIN) NEW RECFM(F B) LRECL(80) SP(1 1) TRACKS“
Address TSO "EXECIO * DISKR SYSPRINT (STEM cmdout. FINIS “
Address TSO "TSOEXEC CALL *(BLZPASTK) '"USER APPLID PASSTCKT"'"
Address TSO "DELETE ‘DOHERTL.MY.DATASET’”
Student Notebook
TSO host command environment

• TSO/E commands (and others)
– From TSO/E Command Reference manual
– From TSO/E REXX Reference manual
– IDCAMS commands
– RACF commands
– RMM (sub)commands
– HSM commands
– IPCS (sub)commands
– TCP/IP commands
– ISPSTART command
– Other product commands
– User written tools and programs
– CLISTs and REXX execs concatenated to //SYSEXEC or //SYSPROC
DD's
Figure 6-10. TSO host command environment ES52G5.0
Notes:
The TSO host command environment allows the programmer to execute TSO/E commands directly
from the REXX exec. This includes many more than just the TSO/E command processor set,
though, as many other product and subsystem commands are considered to be, in essence, TSO/E
commands. At a typical site, this could cover well in excess of a thousand different commands.
Be aware that the documentation for all these commands is spread over a great many manuals.
Each of the products and subsystems named on the visual above are described in one or more
manuals.
Some products implement subcommands. You would issue the command to start the processor, the
command prompt changes, and then you issue the subcommands. Among others, RMM and IPCS
work this way.
V10.1
Student Notebook
Uempty
ISPEXEC host command environment

• Application programming interface (API) to the services of
ISPF
• Approximately 100 services to:
– Display panels, pop-up windows
– Manipulate data sets and member lists
• Similar to ISPF options 3.4, 3.3, and 3.2
– Use Table services
– Manipulate variables
– Perform file tailoring (also known as skeleton processing)
• Example:
Address ISPEXEC 'DISPLAY PANEL(ISR@PRIM)'
Figure 6-11. ISPEXEC host command environment ES52G5.0
Notes:
ISPF provides a very useful set of services for both batch and online REXX execs. They provide the
support for interactive applications, like panels, messages, pop-up windows, menu bars, and help
facilities. They also provide facilities for manipulation of data sets and partitioned data set members,
similar to the things you can do in PDF options 3.2, 3.3, and 3.4, and the member display lists.
There is a facility called ISPF tables, which is a way to store structured data in a row and column, or
table, format. This is almost akin to a simple spreadsheet.
Another facility is called “file tailoring,” or “skeleton processing.” This facilitates the production of
structured files from skeletons. It is most suitable for JCL and utility control card input.
Student Notebook
Address ISPEXEC
• Used to invoke ISPF services like DISPLAY and SELECT
• Only available to REXX running in ISPF
• See: ISPF Services Guide
http://www-
01.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.f54sg00/toc.htm
• Examples:
Address ISPEXEC
"ADDPOP ROW(2) COLUMN(4)"
"DISPLAY PANEL(BLZ@ABOU)"
"REMPOP"
Figure 6-12. Address ISPEXEC ES52G5.0
Notes:
The ISPEXEC and ISREDIT host command environments are available only to REXX execs that
run in ISPF (ADDRESS ISPEXEC and ADDRESS ISREDIT).
Use these environments to invoke ISPF commands and services, and ISPF edit macros.
To use ISREDIT, you must be in an edit (or view) session.
ISPEXEC
• Used to invoke ISPF services like DISPLAY and SELECT
• Only available to REXX running in ISPF
• Example:
Address ISPEXEC “DISPLAY PANEL(APANEL)”
V10.1
Student Notebook
Uempty
ISREDIT host command environment

• API to the services of the ISPF Editor
• Approximately 100 services to do everything the ISPF Editor
can do, like:
– Find, change
– Insert data
– Move lines
– Shift data
– Sort data
– Submit jobs
• Example:
Address ISREDIT "FIND" instrng "FIRST"
Figure 6-13. ISREDIT host command environment ES52G5.0
Notes:
The ISREDIT host command environment provides a REXX exec with the services of the ISPF
editor. You can find and change data, check that your changes have properly worked, insert or
delete data in a data set, and also query and change any and all of the settings of the editor.
The ISREDIT environment is typically used to create ISPF Edit macros, which allow you to extend
the function of the editor. In essence, you can create your own editing commands.
The ISPF editor must be up and running in order to switch to the ISREDIT host command
environment. This is done with the ISPF command EDIT. Of course, you must switch to the
ISPEXEC environment in order to issue the EDIT command from your REXX exec.
Student Notebook
Address ISREDIT
• Used to invoke ISPF edit macro commands like FIND and
DELETE
• Only available to REXX running in an ISPF edit session
• See: ISPF Edit and Edit Macros
http://www-
01.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.f54em00/toc.htm
• Examples:
Address ISREDIT "MACRO (PARMSTR)“
Do while (PARMSTR /= '')
Parse var PARMSTR cmd ';' PARMSTR
Address ISREDIT cmd
End
Address ISREDIT 'END‘
Address ISREDIT "MACRO“
Address ISPEXEC "VGET (CONFLICT) SHARED"
Address ISPEXEC "VGET (ZMOD) SHARED“
Address ISREDIT "COMPARE '"CONFLICT"' X"
Figure 6-14. Address ISREDIT ES52G5.0
Notes:
The ISPEXEC and ISREDIT host command environments are available only to REXX execs that
run in ISPF (ADDRESS ISPEXEC and ADDRESS ISREDIT).
Use these environments to invoke ISPF commands and services, and ISPF edit macros. To use
ISREDIT, you must be in an edit (or view) session.
ISREDIT
• Used to invoke ISPF edit macro commands like FIND and DELETE
• Only available to REXX running in an ISPF edit session
• Example:
Address ISREDIT “DELETE .ZFIRST .ZLAST”
V10.1
Student Notebook
Uempty
ISPF edit macro language

• ISREDIT enables quick writing of edit macros
• An example ISREDIT macro in REXX
• Note the “address ISREDIT” to set the environment
Figure 6-15. ISPF edit macro language ES52G5.0
Notes:
Writing ISPF Edit Macros with REXX
Edit macros are ISPF dialogs that run in the ISPF editor environment. You can use edit macros,
which contain statements that look like ordinary editor commands, to extend and customize the
ISPF editor. You can use edit macros to:
- Perform repeated tasks
- Simplify complex tasks
- Pass parameters
- Retrieve and return information
Edit macros can be either CLISTs or REXX execs written in the CLIST or REXX command
language, or program macros written in a programming language (such as FORTRAN, PL/I, or
COBOL). Our focus here will only be on REXX. Since REXX is such a powerful language, REXX
edit macros have virtually endless possibilities.
In order to use an edit macro, it must reside in partitioned data set that is part of the implicit search
order (see the previous section).
Student Notebook
REXX edit macros statements

• REXX edit macros are made up of REXX statements that fall into one of
the following categories:
– Edit macro commands
– REXX command procedure statements and comments
– ISPF and PDF dialog service requests
– TSO commands
• Must run under the ISPEXEC or ISREDIT host command environment:
– (ADDRESS ISPEXEC or ADDRESS ISREDIT)
• Any statement in an edit macro that begins with ISREDIT is assumed to
be an edit macro command or assignment statement:
/* REXX - this is an edit macro */

ADDRESS ISPEXEC
"ISREDIT MACRO"
"ISREDIT CHANGE JANUARY FEBRUARY ALL"
Figure 6-16. REXX edit macros statements ES52G5.0
Notes:
All statements are initially processed by the TSO command processor, which scans them and does
symbolic variable substitution. It is important to recognize the different kinds of CLIST and REXX
statements listed because:
• They are processed by different components of the system.
• They have different syntax rules and error handling.
• Their descriptions are in different manuals.
Since edit macros need to use ISPF services, they must run under the ISPEXEC or ISREDIT host
command environment (ADDRESS ISPEXEC or ADDRESS ISREDIT). ISREDIT passes
commands directly to the PDF editor and ISPEXEC is needed for using other ISPF services within
an edit macro.
Any statement in an edit macro that begins with ISREDIT is assumed to be an edit macro command
or assignment statement:
ADDRESS ISPEXEC
"ISREDIT FIND 'PGM='" /* edit macro command */
"ISREDIT BOUNDS = 1,50" /* edit macro assignment statement */
V10.1
Student Notebook
Uempty If you have several edit macro commands within a REXX EXEC, you can change the host
command environment default to the PDF editor with the ADDRESS ISREDIT instruction.
ADDRESS ISREDIT
"FIND 'PGM='" /* edit macro command */
"BOUNDS = 1,50" /* edit macro assignment statement */
All edit macros must have an ISREDIT MACRO statement as the first edit command.
/* REXX - this is an edit macro */
ADDRESS ISPEXEC
"ISREDIT MACRO"
"ISREDIT CHANGE JANUARY FEBRUARY ALL"
The MACRO command is also used to pass parameters to an edit macro. Parameters are enclosed
within parenthesis after the MACRO command. Multiple parameters are separated by a blank or
comma. Example:
/* REXX - MYMAC edit macro */
ADDRESS ISPEXEC
"ISREDIT MACRO (PARM1,PARM2,REST)"
If you executed this edit macro with parameters like this:
Command ===> MYMAC FIRST SECOND THIRD FOURTH
PARM1 would be set to FIRST, PARM2 to SECOND, and REST would be assigned the value
THIRD FORTH.
Here is a simple edit macro called “INCL”. It can be used to exclude all lines in the editor except for
a particular sting. The string to include is passed as a parameter to the macro. To use it you would
type the following on the command line: Command ===> INCL DSN=
/* REXX */ /* REXX */
ADDRESS ISPEXEC ADDRESS ISREDIT
"ISREDIT MACRO (parm1)" OR "MACRO (parm1)"
"ISREDIT EXCLUDE ALL" "EXCLUDE ALL"
"ISREDIT FIND ALL" parm1 "FIND ALL" parm1
You can use most primary commands in an edit macro if you precede it with ISREDIT. Some
commands have additional operands permitted in a macro that cannot be used interactively. You
cannot issue line commands directly from an edit macro. For example, you cannot use the M
(move) line command within an edit macro. However, you can perform most of the functions
provided by line commands by using a combination of primary commands, edit macro commands
and edit assignment statements.
Student Notebook
Edit macros use edit assignment statements to communicate between macros and the editor. An
assignment statement consists of two parts, values and keyphrases, which are separated by an
equal sign.
Data is always transferred from the right side of the equal sign in an assignment statement to the
left side. Therefore, if the keyphrase is on the right, data known to the editor is put into REXX
variables on the left. In the following example, yyy would be a keyphrase, and xxx would be the
value.
ADDRESS ISPEXEC
"ISREDIT xxx = yyy"
Edit assignment statements can be used to:
• Set or query edit parameters, for example CAPS, NULLS, and NUMBER
• Pass values back and forth between the editor and the macro
• Manipulate data (insert, delete, or replace lines)
Here are some examples:
ADDRESS ISPEXEC
"ISREDIT CAPS = OFF" /* set CAPS off */
"ISREDIT (capmode) = CAPS" /* puts value of CAPS into var capmode */
"ISREDIT CAPS = "capmode /* set CAPS to whatever is in capmode var */
In the first statement, CAPS are set to a value of OFF. The second statements queries the current
value of CAPS and places it into variable capmode. The third statement sets the value of CAPS to
whatever is in the capmode variable. If these instructions were executed in this order, the last
statement would be equivalent to the first one.
ADDRESS ISPEXEC
"ISREDIT (lb,rb) = BOUNDS"
"ISREDIT BOUNDS = (lb,rb)"
In the first statement, the current left and right boundaries are stored into the variables lb and rb.
In the second statement, the values from the variables lb and rb are used to change the current
boundaries.
ADDRESS ISREDIT
"(linedat) = LINE "curline
"LINE" curline "= (linedat)"
In the first statement, the data from line number “curline” (a variable used in the exec) is stored into
variable linedat. In the second statement, the data from variable linedat is used to change the
contents of the editor at line number “curline”.
V10.1
Student Notebook
Uempty
Sample edit macros

• This simple edit macro can be • This edit macro can be used to
used to set up the ISPF profile exclude all lines in the editor
defaults that you prefer. except for a particular sting.
– The string to include is passed as a
parameter to the macro.
/* rexx MYPROF edit macro – To use it you would type the following
*/
on the command line:
ADDRESS ISREDIT
"MACRO" Command ===> INCL DSN=
"BOUNDS"
"TABS OFF"
"NULLS ON" /* REXX */
"HILITE AUTO" ADDRESS ISREDIT
"RECOVERY ON" "MACRO (parm1)"
"EXCLUDE ALL"
"FIND ALL" parm1
Figure 6-17. Sample edit macros ES52G5.0
Notes:
This edit macro, called “DELX” will delete everything but a specified string.
The search can optionally be limited to specific columns.
Example:
DELX 'DISP=(NEW'
Student Notebook
/* REXX - DELX edit macro */

Address ISREDIT /* ISREDIT host command environment */
"MACRO (parm col1 col2)" /* MACRO parms */
"(lastln) = LINENUM .ZLAST" /* find out how many lines */
"SEEK "parm col1 col2" FIRST" /* any thing found? */
If rc = 0 then do /* we found something */
"EXCLUDE ALL" /* exclude all lines */
"FIND "parm col1 col2" ALL" /* UN-exclude lines */
"SEEK "parm col1 col2" ALL" /* get counts for later */
"DELETE ALL X" /* delete excluded lines */
"(count,lines) = SEEK_COUNTS" /* save counts for later */
count = Format(count) /* remove leading zeros */
lines = Format(lines) /* remove leading zeros */
deleted = lastln-lines /* how many lines were deleted */
Upper parm /* change parm to upper case for msg */
zedsmsg = deleted' LINES DELETED' /* short msg */
zedlmsg = count 'OCCURRENCES OF "'parm'" WERE KEPT',
'ON 'lines 'LINES - 'deleted 'LINES WERE DELETED.'
"RESET" /* re-display excluded lines */
Address ISPEXEC "SETMSG MSG(ISRZ000)" /* msg - no alarm */
Exit 0 /* exit and set rc to 0 */
End
Else do /* string not found */
Upper parm /* change parm to upper case for msg */
zedsmsg = 'STRING NOT FOUND'
zedlmsg = 'THE STRING "'parm'" WAS NOT FOUND IN THE FILE.'
"RESET" /* re-display excluded lines */
Address ISPEXEC "SETMSG MSG(ISRZ001)" /* msg with alarm */
Exit 12 /* exit and set rc to 12 */
End
V10.1
Student Notebook
Uempty
Other ISPF interfaces

• Panel REXX
– Allows REXX to be run in a panel procedure
– *REXX statement used to invoke it
– REXX can be coded directly in the procedure or taken from a
SYSEXEC or SYSPROC DD member
– REXX can modify the values of ISPF variables
• File tailoring skeleton REXX
– Allows REXX to be run in a skeleton
– )REXX control statement used to invoke it
– REXX can be coded directly in the procedure or taken from a
SYSEXEC or SYSPROC DD member
– REXX can modify the values of ISPF variables
Figure 6-18. Other ISPF interfaces ES52G5.0
Notes:
Student Notebook
CONSOLE host command environment

• Provides the ability to issue MVS operator (console)
commands and get back the command responses
• Security system authorization is required to issue commands
• Examples:
Address TSO 'CONSOLE'
Address CONSOLE
'DISPLAY ASM'
'D A,L'
'P TSO'
'F BPXOINIT,SHUTDOWN=FORKS'
'V 2C6,ONLINE'
Figure 6-19. CONSOLE host command environment ES52G5.0
Notes:
A user may turn their TSO/E session in to an MVS console operator session by issuing the TSO/E
command CONSOLE. You must have the proper security system authority in order to do this. This
authority not only governs which TSO/E users are allowed to issue the CONSOLE command, but
also what operator commands they are allowed to enter while in console mode.
This host command environment allows you to execute MVS Operator commands and capture their
responses from within a REXX exec. After issuing the TSO/E CONSOLE command to switch into
console mode, you would then issue Address CONSOLE to begin executing MVS operator host
commands from your REXX exec.
V10.1
Student Notebook
Uempty
Address CONSOLE
• Used to invoke MVS system and subsystem commands
• Only available to REXX running in a TSO/E address space
• Requires an extended MCS console session
• Requires CONSOLE command authority
• Example:
“CONSOLE ACTIVATE”
Address Console “D A” /* Display system activity */
“CONSOLE DEACTIVATE”
Result:
IEE114I 04.50.01 2011.173 ACTIVITY 602

JOBS M/S TS USERS SYSAS INITS ACTIVE/MAX VTAM OAS
00002 00014 00002 00032 00005 00001/00020 00010
Figure 6-20. Address CONSOLE ES52G5.0
Notes:
The CONSOLE host command environment (ADDRESS CONSOLE) is available only to REXX
execs that run in the TSO/E address space. Use the CONSOLE environment to invoke MVS
system and subsystem commands during an extended MCS console session. To use the
CONSOLE environment, you must have CONSOLE command authority.
Student Notebook
MVS host command environment

• Available in all MVS address spaces
• Subset of TSO host command environment
• Only a subset of TSO/E commands are available
– TSO/E REXX commands
• MVS
– Use to run a subset of TSO/E commands like EXECIO and MAKEBUF
– The default environment in a non-TSO/E address space, for example
– See: TSO/E REXX Reference
Address MVS "EXECIO * DISKR MYINDD (FINIS STEM MYVAR“
Figure 6-21. MVS host command environment ES52G5.0
Notes:
There are some special circumstances where you may want to execute a REXX exec outside the
control of TSO/E. The MVS host command environment allows you to do this.
The MVS host command environment is available in every address space. You can think of it as a
subset of the TSO environment, as only a subset of the TSO/E commands are available for your
use. In fact, only the TSO/E REXX commands, which are described in the TSO/E REXX Reference
manual, are usable in the MVS host command environment. No other TSO/E commands are
allowed.
V10.1
Student Notebook
Uempty
LINK and ATTACH environments

• Total of six host command environments
• LINK: Three varieties
– LINK, LINKMVS, LINKPGM
• ATTACH: Three varieties
– ATTACH, ATTCHMVS, ATTCHPGM
• All six used to run programs (command = program name,
loaded by standard MVS search order)
• ATTACH environments create new TCB for program
• LINK environments reuse existing TCB
• Differences lie in parameter list processing
Figure 6-22. LINK and ATTACH environments ES52G5.0
Notes:
There are actually six host command environments being introduced here. They are called LINK,
LINKMVS, LINKPGM, ATTACH, ATTACHMVS, and ATTACHPGM. The command passed to these
environments is actually the name of the program (load module) you want to execute. This load
module will be located using the standard MVS search order:
• Job Pack Area
• LIBDEF ISPLLIB
• ISPLLIB DD concatenation
• TASKLIB
• STEPLIB or JOBLIB (whichever one is in effect for this step)
• LPA
• Link List
Student Notebook
Address LINK, LINKMVS, LINKPGM, ATTACH,

ATTCHMVS, ATTCHPGM
• Host command environments for linking to and attaching unauthorized
programs
• Available to REXX running in any address space
• LINK and ATTACH - can pass one character string to program
• LINKMVS and ATTCHMVS - pass multiple parameters; half-word length
field precedes each parameter value
• LINKPGM and ATTCHPGM - pass multiple parameters; no half-word
length field
http://www-
01.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.ikja300/toc.htm
• Examples: “FREE FI(SYSOUT SORTIN SORTOUT SYSIN)”
“ALLOC FI(SYSOUT) DA(*)”
“ALLOC FI(SORTIN) DA('VANDYKE.SORTIN') REUSE”
“ALLOC FI(SORTOUT) DA('VANDYKE.SORTOUT') REUSE”
“ALLOC FI(SYSIN) DA('VANDYKE.SORT.STMTS') SHR REUSE”
sortparm = “EQUALS”
Address LINKMVS “SORT sortparm”
Figure 6-23. Address LINK, LINKMVS, LINKPGM, ATTACH,ATTCHMVS, ATTCHPGM ES52G5.0
Notes:
The LINK, LINKMVS, and LINKPGM host command environments are available to any address
space and let you link to unauthorized programs on the same task level (ADDRESS LINK,
ADDRESS LINKMVS, and ADDRESS LINKPGM). The ATTACH, ATTCHMVS, and ATTCHPGM
host command environments are also available to any address space and let you attach
unauthorized programs on a different task level (ADDRESS ATTACH, ADDRESS ATTCHMVS,
and ADDRESS ATTCHPGM).
Address TSO "ALLOC F(NEWDD) DA('DOHERTL.V6DEV.SOURCE') SHR"
Address TSO "ALLOC F(OUTDD) NEW SP(1 1) CYL"
Address TSO "ALLOC F(SYSIN) NEW SP(1 1) CYL"
Sysin.0 = 2
Sysin.1 = "SRCHFOR ‘DAEMON'"
Sysin.2 = "SELECT BLZBKPZP,BLZBUILD,BLZCIVP,BLZCKHIS,BLZCLMM,BLZCNVRT"
Address TSO "EXECIO * DISKW SYSIN (STEM SYSIN. FINIS)"
PARMS = "SRCHCMP,ANYC"
Address LINKMVS 'ISRSUPC PARMS'
"EXECIO * DISKR OUTDD (FINIS STEM outdd."
V10.1
Student Notebook
Uempty
Passing parameters to programs

• R0 points to REXX environment block
• Three different ways to specify parameters
– LINK and ATTACH:
• Parameter is a single string
• Non-standard parameter list format
• Example: Address LINK "MYPGM TABL23 ROW6 COL17"
– LINKMVS and ATTCHMVS:
• Parms are REXX variables, can be updated
• Length of variable value can be changed
• Example: Address ATTACHMVS "MYPGM var1 var2 var3"
– LINKPGM and ATTCHPGM:
• Parms are REXX variables, can be updated
• Length of variable value cannot be changed
• Example: Address LINKPGM "MYPGM var1 var2 var3"
• Note that REXX variables are inside the quotes
Figure 6-24. Passing parameters to programs ES52G5.0
Notes:
The REXX environment block is a control block that is used to describe the REXX exec itself, and
the environment in which it is executing, to the operating system.
Each of the three types of host command environments, LINK and ATTACH, LINKMVS and
ATTACHMVS, LINKPGM and ATTACHPGM, use different methods and have different rules about
how parameters are passed to the program to be executed, and whether the program is allowed to
update and pass those parameters back to the REXX exec.
LINK and ATTACH simply pass a single string of data as the parameters to the program. The
program may use the parameters, but may not pass them back to the REXX exec when it
terminates. The other four environments pass parameters to the program in REXX variables. These
variables and their values may be changed by the program and passed back to the exec. LINKMVS
and ATTACHMVS are both allowed to change the length of the value being passed back to the
exec, but LINKPGM and ATTACHPGM are not allowed to change the value length.
Student Notebook
REXX TSO/E extensions

• IBM Component areas create their own extensions.
– Vendors create extensions
– Users create extensions
– IBM Component areas create new environments
• IBM Component areas create their own extensions.
– DB2 (DSNREXX)
– Communication Server (FTPAPI)
– DFSMS (IGGCSI00)
– TCP/IP (SOCKET)
– SDSF (ISFEXEC)
– z/OS UNIX Services (SYSCALLS)
– Tivoli NetView (NETVIEW, NETVASIS, NETVDATA)
– IMS (REXXIMS, REXXTDLI)
Figure 6-25. REXX TSO/E extensions ES52G5.0
Notes:
This page lists some of the IBM products that can interface with REXX, or use REXX as their driving
language.
Each of these products provide one or more host command environments (HCE’s in the visual
above).
Extensions are
- DSNREXX
- FTPAPI
- IGGCSI00
- SOCKET
- ISFEXEC
- SYSCALLS
- NETVIEW, NETVASIS, NETVDATA
- REXXIMS, REXXTDLI
- ...
- ...
V10.1
Student Notebook
Uempty
DB2 (DSNREXX)
• Provides access to DB2 application programming interfaces
from REXX
• Any SQL command can be executed from REXX
– Only dynamic SQL supported from REXX
• Use RXSUBCOM to make DSNREXX host environment
available
• Must CONNECT to required DB2 subsystem
• Can call SQL Stored Procedures
• See: DB2 Application Programming and SQL Guide
– http://www-
01.ibm.com/support/knowledgecenter/SSEPEK_11.0.0/com.ibm.db2z
11.doc.apsg/src/apsg/db2z_apsg.dita
Figure 6-26. DB2 (DSNREXX) ES52G5.0
Notes:
Optional feature
• JOB DSNTIJRX binds packages and plans.
• Connect to more than one subsystem at the same time.
• Execute STORED PROCEDURES.
Student Notebook
• SELECT with multiple CURSORS.

RXSUBCOM('ADD','DSNREXX','DSNREXX')
SubSys = 'DB2PRD'
Address DSNREXX "CONNECT" SubSys
Owner = 'PRODTBL'
RecordKey = 'ROW2DEL'
SQL_stmt = "DELETE * FROM" owner".MYTABLE" ,
"WHERE TBLKEY = '"RecordKey"'"
Address DSNREXX "EXECSQL EXECUTE IMMEDIATE" SQL_stmt
Address DSNREXX "DISCONNECT“
owner_id = "SYSIBM"
SQLSTMT = "Select CL.TBNAME, CL.NAME,
TB.COLCOUNT, CL.COLNO
FROM SYSIBM.SYSCOLUMNS CL,
SYSIBM.SYSTABLES TB
WHERE CL.TBCREATOR = '"owner_id"'
AND CL.TBNAME = TB.NAME
AND TB.DBNAME LIKE '?'
AND TB.TYPE = 'T'
ORDER BY CL.TBNAME, CL.COLNO“
Address TSO "SUBCOM DSNREXX"
S=RXSUBCOM("ADD","RexxDB2","DSNREXX")
Address RexxDB2
"CONNECT" db2_ssid
"EXECSQL SET CURRENT
PACKAGESET='DSNREXUR'"
"EXECSQL DECLARE C1 CURSOR FOR S1"
"EXECSQL PREPARE S1 FROM :SQLSTMT“
"EXECSQL DESCRIBE S1 INTO :sqlda.C1"
DBNAME = 'DSNDB%'
"EXECSQL OPEN C1 USING :DBNAME"
DO UNTIL SQLCODE <> 0
"EXECSQL FETCH C1 USING DESCRIPTOR
:sqlda.C1"
my.tbname = sqlda.C1.1.sqldata
my.colname = sqlda.C1.2.sqldata
END
"EXECSQL CLOSE C1"
"DISCONNECT"
S=RXSUBCOM("DELETE","RexxDB2","DSNREXX")
V10.1
Student Notebook
Uempty
Communication Server (FTPAPI)

• Started with Communication Server Version 1.6.
• REXX started with CS 1.8.
• Beats stacking sub-commands and blindly executing them.
parse arg host_name user_name pass_word .
ftpapi_rc = FtpApi("fcai.", "create", "")
ftpapi_rc = FtpApi("fcai.", "init", "-w 300" host_name "21")
ftpapi_rc = FtpApi("fcai.", "scmd", "user" user_name, "W")
ftpapi_rc = FtpApi("fcai.", "scmd", "pass" pass_word, "W")
ftpapi_rc = FtpApi("fcai.", "scmd", "cd MYOWN.CNTL", "W")
ftpapi_rc = FtpApi("fcai.", "scmd", "dir *", "W")
ftpapi_rc = FtpApi("fcai.", "scmd", "lcd SHR110.CNTL", "W")
ftpapi_rc = FtpApi("fcai.", "scmd", "get BKUPJOB", "W")
ftpapi_rc = FtpApi("fcai.", "scmd", "QUIT", "W")
ftpapi_rc = FtpApi("fcai.", "term")
return 0
Figure 6-27. Communication Server (FTPAPI) ES52G5.0
Notes:
The interface to the z/OS FTP client enables a user program to send subcommands for the client to
process. The interface also enables the user program to retrieve output that includes the messages
from the client, replies from the FTP server, and other data generated as the result of the request.
A REXX language program requires an intermediate routine to translate from the string format used
within REXX programs to the binary format used by the EZAFTPKS program. An external function
package is provided that serves as this intermediary, facilitating calling the FTP client API from a
REXX language program.
All FTP client API for REXX requests use the same format:
result = ftpapi(stem, request_type, parm1, parm2, ...);
The first parameter is the name of the REXX stem that refers to a specific instance of the FTP client
environment. The second parameter identifies the API request that is being made (for example INIT
or SCMD). The remaining parameters are used to pass data which is sometimes optional for the
specific API request that is being made.
Tip: When passing string literals, enclose them in single or double quotes.
Student Notebook
DFSMS (IGGCSI00)
• Catalog Search Interface started as a 'fee‘ based optional
feature then 'free' with OS/390 DFSMS 1.4.
• SAMPLIB(IGGCSIRX) a decent start for single catalog
searching.
Figure 6-28. DFSMS (IGGCSI00) ES52G5.0
Notes:
IGGCSI00 is a callable subroutine to search the catalog. It is provided by DFHSMS and
documented in Managing Catalogs. It can be used to search for dataset names, tape libraries and
volumes (as cataloged in the DFSMS catalog). There are some assembler and REXX samples in
SYS1.SAMPLIB demonstrating how to call the routine.
The interface to IGGCSI00: you specify filter criteria and field names in a control block and an area
for the routine to return the results. This work area has a header and some variable data that must
be parsed or stepped through.
Assembler and PL/I mappings for the filter criteria control block are provided.
Sample programs
In SYS1.SAMPLIB
• IGGCSILC – list entry types in specified catalogs
• IGGCSIVG – show VSAM stats for a catalog
- Count of clusters, used space, free space, min, max, totals
• IGGCSIVS – find all DSNs for a catalog on specified volser
V10.1
Student Notebook
Uempty • IGGCSIRX – REXX EXEC

- Return entry name, type, volser for specified filter
On IBM FTP site (ftp://ftp.software.ibm.com/servers/storage/support/software/dfsms)
• CATSRCHI – REXX EXEC
- Return specified fields for each entry for given filter key
Below is an example:
MODRSNRC = SubStr(' ',1,4)
CSIFILTK = SubStr('SYS1.**.SCEE*',1,44)
CSICATNM = SubStr(' ',1,44)
CSIRESNM = SubStr(' ',1,44)
CSIDTYPS = SubStr(' ',1,16)
/* ' ' Gets A, B, C, G, H, R, X, U. */
CSIOPTS = 'Y F'
CSINUMEN = '0008'x
CSIENTS = Left('SECFLAGS',8)||
Left('ENTYPE ',8)||
Left('ENTNAME ',8)||
Left('TYPE ',8)||
Left('NAME ',8)||
Left('GDGLIMIT',8)||
Left('GDGATTR ',8)||
Left('OWNERID ',8)
CSIFIELD = CSIFILTK || CSICATNM
CSIFIELD = CSIFIELD || CSIRESNM || CSIDTYPS
CSIFIELD = CSIFIELD || CSIOPTS
CSIFIELD = CSIFIELD || CSINUMEN || CSIENTS
hexzeros = '00000000'x
WORKLEN = 1048575
low_00 = x2c('00')
DWORK = Right(hexzeros||d2c(worklen),4)||,
Copies(low_00,WORKLEN-4)
ADDRESS LINKPGM 'IGGCSI00',
'MODRSNRC CSIFIELD DWORK'
/* Now you get to parse CSIFIELD */
/* Good Luck with that! */
Student Notebook
TCP/IP and REXX Programming with

REXX/SOCKETS
• Communications Server (CS), also known as, VTAM and TCP/IP,
provide a SOCKET API for REXX and other languages.
• REXX/SOCKETS is a REXX interface to the TCP/IP Socket calls
• REXX/SOCKETS provides the REXX function SOCKET:
result = SOCKET(subfunction,arg1,...,argn)
• Supported subfunctions are:
– Initialize, Terminate, SocketSet, SocketSetStatus, ...
– Socket, Bind, Listen, Connect, Accept, Shutdown, Close, ...
– GiveSocket, TakeSocket, GetClientId, ...
– GetHostId, GetHostName, GetHostByAddr, GetHostByName, ...
– Read, Recv, RecvFrom, Write, Send, SendTo, ...
– GetSockOpt, SetSockOpt, Ioctl, ...
• Note: REXX/SOCKETS supports the non–blocking mode (and the
Select socket function) through REXX/WAIT.
• The result consists of a return code and additional data depending on
which subfunction was called.
Figure 6-29. TCP/IP and REXX Programming with REXX/SOCKETS ES52G5.0
Notes:
Any IP function you can dream of.
• Get a URL.
• Do FTP.
• ...
• See the z/OS Communications Server: IP Sockets Programming interface Guide and
Reference:
http://www-01.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.hala001/to
c.htm
Socket Interfaces allow programmers to write their own applications to supplement those supplied
by TCP/IP. Sockets permit full–duplex transmission (transmission in both directions
simultaneously). Reading and writing to a socket appears very similar to performing I/O to a file or
any other network device.
V10.1
Student Notebook
Uempty The design of the socket interface is closely related to the programming language C.
int socket(int domain, int type, int protocol);
...
int s;
...
s = socket(AF_INET, SOCK_STREAM, 0);
There are many socket functions, but the following are of general interest:
socket() – gets a socket number to read from or write to
bind() – associates a socket with a port number
listen() – listens to connect requests on the socket
select() – waits for activity on a socket
connect() – requests a connection
accept() – accepts a connect request
send() or write() – writes data to the socket
recv() or read() – reads data from the socket
close() – returns socket number
givesocket() and takesocket() – transfer a socket
Student Notebook
REXX/SOCKETS client sample

• The client sample program connects to the server (on the
same host) and sends data:
/* SNDSAMPL –– REXX/SOCKETS client example */
parse arg Count Message
parse value SOCKET(’Initialize’,’Example’) with src .
if src<>0 then exit src
parse value SOCKET(’GetHostId’) with src IpAddress .
parse value SOCKET(’Socket’) with src Socket .
call SOCKET ’Connect’,Socket,’AF_INET 1993’ IpAddress
do i=1 to Count by 1
parse value SOCKET(’Send’,Socket,Message) with src msglen .
say ’Sent’ msglen ’bytes with rc=’src
if src<>0 then leave
end
call SOCKET ’Close’,Socket
call SOCKET ’Terminate’
Figure 6-30. REXX/SOCKETS client sample ES52G5.0
Notes:
so=Socket('Initialize', 'URLCHECK', 2)
so=Socket('Socket','AF_INET','STREAM','TCP')
parse var so src s_d
so=Socket('SetSockOpt',s_d,'SOL_SOCKET','SO_ASCII','On')
so=Socket('Connect',s_d,'AF_INET' port server)
so=Socket('Write',s_d,'HEAD / HTTP/1.0' '0D250D25'x)
so=Socket('Recv',s_d,1024,'PEEK')
parse var so src s_peek_len s_data_text
so=Socket('Recvfrom',s_d,s_peek_len)
parse var so src s_type s_port s_ipaddr s_real_len txtdata
say txtdata
so=Socket('Shutdown's_d,'BOTH')
so=Socket('Terminate')
V10.1
Student Notebook
Uempty
SDSF (ISFEXEC)
• Used to invoke interfaces to SDSF panels and panel actions
• Use isfcalls(‘ON’) function to establish the SDSF host
environment
• Use the ISFEXEC host command to access an SDSF panel
• Panel fields returned in stem variables
• Use the ISFACT host command to take an action or modify a
job value
• See: SDSF Operation and Customization
– http://www-
01.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2
r1.isfa500/toc.htm
• And: Implementing REXX Support in SDSF
– http://www.redbooks.ibm.com/abstracts/sg247419.html?Open
Figure 6-31. SDSF (ISFEXEC) ES52G5.0
Notes:
• SDSF API
• Does not bypass SDSF security.
• Picture what would show on a screen based on filters and that is what you get in compound
variables.
• Behavior change with z/OS 1.10 regarding what columns you get.
Student Notebook
Example 1:
rc=isfcalls('ON')
mycmd.0=1
mycmd.1="D IKJTSO,AUTHPGM"
Address SDSF ISFSLASH "("mycmd.") (WAIT)"
Say RC
/* List any error messages */
Say "isfmsg is:" isfmsg
Say "isfmsg2.0 is:" isfmsg2.0
if datatype(isfmsg2.0) = "NUM" then
do ix=1 to isfmsg2.0
Say "isfmsg2."ix "is:" isfmsg2.ix
end
rc=isfcalls('OFF')
/* get output */
do i = 1 to ISFULOG.0
say ISFULOG.i
end
Example 2:
rc=ISFCalls(“ON”)
Address SDSF “ISFEXEC ST”
Do ix = 1 to JNAME.0
If Pos(“MYREXX”,JNAME.ix) = 1 Then
Do
say “Cancelling job ID” JOBID.ix “for MYREXX”
Address SDSF “ISFACT ST TOKEN(‘”TOKEN.ix”’) PARM(NP P)”
End
End
rc=ISFCalls(“OFF”)
Exit
V10.1
Student Notebook
Uempty
Address SDSF
Figure 6-32. Address SDSF ES52G5.0
Notes:
Student Notebook
Address SYSCALL
• Used to invoke interfaces to z/OS UNIX callable services
• SYSCALL provide many services for accessing HFS files
• The default environment for REXX run from the z/OS UNIX file system
• Use syscalls(‘ON’) function to establish the SYSCALL host environment for a REXX
run from TSO/E or MVS batch
• See: Using REXX and z/OS UNIX System Services
http://www-
01.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.bpxb600/toc.htm
• Examples: Call Syscalls ‘ON’
Address Syscall ‘readdir / root.’
Do i=1 to root.0
Say root.i
End
Result:
…
bin
dev
etc
…
Figure 6-33. Address SYSCALL ES52G5.0
Notes:
SYSCALL can be run from TSO/E or UNIX Shell
• Start program with syscall(‘on’)
- Ensures that ADDRESS syscall is enabled
- Ensures that the address space is a process (this is called ‘dubbing’)
- Initializes the REXX variables in the initial variable pool
- Sets the process signal mask to block all blockable signals
- Clears the argc and argv variables
Several hundred variables are assigned when the SYSCALL environment is activated
• Values are documented in Appendix A of SA22-7806 - Using REXX and z/OS UNIX System
Services
• Use is shown under the command description in the same manual
• Variables are used as parameters to SYSCALL commands
Establish/end the SYSCALLS environment by using CALL SYSCALLS.
V10.1
Student Notebook
Uempty • SYSCALL environment automatically activated (without the CALL) when running an exec stored
in the HFS (for example, ISHELL, OSHELL,OMVS)
The SH environment: for a REXX program with syscall commands that will be run from a z/OS shell
or from a program, SH is the initial host environment. The SYSCALL environment is automatically
initialized as well, so you do not need to begin the REXX program with a syscalls(’ON’) call.
Syscall commands within the REXX program (for example, chmod) are interpreted as z/OS shell
commands, not as syscall commands.
SYSCALL host commands can set RC, RETVAL, ERRNO, and ERRNOJR
• RC: Return code from command
• RETVAL: Usually ‘0’ for success, ‘-1’ for failure.
• ERRNO: Hexadecimal error number (only if RETVAL= -1)
• ERRNOJR: Hexadecimal reason code (only if RETVAL= -1)
Refer to: UNIX System Services Messages and Codes (SA22-7807)
call syscalls "ON"
address syscall "readdir (path) d."
do i = 1 to d.0
dpath=path"/"d.i
rt = ketcall("lstat (dpath)" st.)
if (rt >< 0) then,
do
say "rt" rt retval
return 0
end
address syscall "gmtime" st.11 "'gm.'“
if ((st.st_type=s_isdir) & ,
(d.i <> '.') & (d.i <> '..')) then,
call rdir dpath
else,
if ((d.i <> '.') & (d.i <> '..')) then,
do
if (left(d.i,left_length) = file_prefix) then,
do
say "File:" tabs"/"d.i
end
end
End
address syscall,
"readfile (path_file) mylines."
rt = ketcall("unlink" dir_file_prefix)
say 'Error codes:' rt retval errno errnojr
"%BPXMTEXT" errnojr
call syscalls "OFF"
Student Notebook
UNIX commands
• SYSCALL commands (userid-related):
– getgid, getlogin, getpwnam
• SYSCALL commands (directory-related):
– readdir, mkdir, rmdir
• SYSCALL commands (file-related):
– access, open, close, creat, read, write, readfile,
writefile, unlink
• z/OS UNIX REXX functions:
– exists, lines, linein, lineout, bpxwunix,…
Figure 6-34. UNIX commands ES52G5.0
Notes:
z/OS UNIX REXX functions: see z/OS Using REXX and z/OS UNIX System Services,
SA23-2283-00. The z/OS UNIX REXX functions extend the REXX language on z/OS when it is
used in the z/OS UNIX REXX environment.
Except for bpxwunix() and syscalls(), these functions must be run in a z/OS UNIX environment.
The z/OS UNIX REXX functions include functions for standard REXX I/O, and for accessing
common file services and environment variables.
Examples
• mkdir defines a new directory.
- Watch out for permissions in the containing directory.
- Set permissions for new directory appropriately.
• rmdir removes an empty directory.
• unlink removes a directory entry (almost the same as deleting a file).
• Create an HFS file with writefile.
V10.1
Student Notebook
Uempty • Read an HFS file with read

- “read (fd) buf 1000“
- “fd” variable returned from successful “open” call’s RETVAL
- “buf” variable receives up to 1000 bytes
• An easier approach for reading an HFS file is readfile.
- “readfile (pathname) line.”
- “pathname” must already be assigned
- Lines added to LINE.1, LINE.2, and so on
- LINE.0 is the number of lines that were obtained
Student Notebook
Other external environments (1 of 2)

• IPCS
– Used to invoke IPCS subcommands from REXX
– Only available when run from in an IPCS session
– See: MVS IPCS Commands
• CPICOMM, LU62, and APPCMVS
– Supports the writing of APPC/MVS transaction programs (TPs) in REXX
– Programs can communicate using SAA common programming interface (CPI)
Communications calls and APPC/MVS calls
– See: TSO/E REXX Reference
• REXX for CICS
class = 'STARTED'
• RACF interfaces profile = ‘BLZBFA.*'
– IRRXUTIL rc=IRRXUTIL("EXTRACT",class,profile,"RACF","
","FALSE")
• REXX interface
racfUser = RACF.STDATA.USER.1
to R_admin
racfGroup = RACF.STDATA.GROUP.1
callable service
(IRRSEQ00) extract request
Figure 6-35. Other external environments (1 of 2) ES52G5.0
Notes:
IBM Component areas create new environments.
QMF
• HCE: QRW
• Manual: SC18-7651: QMF V8 - Developing DB2 QMF Applications
Tivoli NetView
- HCE's: NETVIEW, NETVASIS, NETVDATA
- Manual: SC31-8862: IBM Tivoli NetView for z/OS Programming: REXX and the NetView
Command List Language
REXX for CICS
- HCE's: REXXCICS, CICS, EXECDB2, EXECSQL, EDITSVR, FLSTSVR, RFS, RLS
- Manual: SH21-0482: REXX for CICS/ESA R1V1 Guide and Reference
IMS
- HCE's: REXXIMS, REXXTDLI
- Manual: SC18-7812: IMS V9 Application Programming: Transaction Manager
V10.1
Student Notebook
Uempty
Other external environments (2 of 2)

• RACF interfaces
– IRRXUTIL
• REXX interface to R_admin callable service (IRRSEQ00) extract request
• Stores output from extract request in a set of stem variables
class = 'STARTED'
profile = ‘BLZBFA.*'
rc=IRRXUTIL("EXTRACT",class,profile,"RACF","","FALSE")
racfUser = RACF.STDATA.USER.1
racfGroup = RACF.STDATA.GROUP.1
– RACVAR function
• Provides information from the ACEE about the running user
• Arguments: USERID, GROUPID, SECLABEL, ACEESTAT
If racvar(‘ACEESTAT’) <> ‘NO ACEE’ Then

Say “You are connected to group “
racvar(‘GROUPID’)”.”
Figure 6-36. Other external environments (2 of 2) ES52G5.0
Notes:
RACF: IRRXUTIL
• REXX interface to R_admin callable service (IRRSEQ00) extract request
• Stores output from extract request in a set of stem variables
• See: Security Server RACF Macros and Interfaces
- http://www-01.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.icha300/
toc.htm
myrc=IRRXUTIL(“EXTRACT”,”FACILITY”,”BPX.DAEMON”,”RACF”,””,”FALSE”)
Say “Profile name: “||RACF.profile
Do a=1 to RACF.BASE.ACLCNT.REPEATCOUNT
Say “ “||RACF.BASE.ACLID.a||”:”||RACF.BASE.ACLACS.a
End
Student Notebook
Checkpoint (1 of 2)
1. What is a host command environment?
2. True or False: The default host command environment for

every address space is TSO.
3. The instruction used to change host command environments

is called (blank).
4. True or False: If you attempt to switch to a nonexistent host

command environment, your REXX program will abend.
Notes:
V10.1
Student Notebook
Uempty
Checkpoint (2 of 2)
5. True or False: ISPF provides a very useful set of services for
both batch and online REXX execs.
6. True or False: You can use REXX to write your own ISPF edit
commands.
7. True or False: Anyone can use the CONSOLE host

command environment.
Notes:
Student Notebook
Unit summary
Notes:
V10.1
Student Notebook
Uempty
Unit 7. Compound variables and the data stack

This unit describes the usage of REXX compound variables and the data
stack. The components and special properties of compound variables are
discussed, along with some examples of how to use them. The REXX
instructions and TSO/E commands that are used to manage the data stack
are covered here. The Symbol() and OUTTRAP() functions are also
discussed in this unit. The unit concludes with the advantages and
disadvantages of both compound variables and the data stack.

• Identify the components of REXX compound variables
• Create and use compound variables
• Use and manage the data stack
• Use the OUTTRAP() function
• Determine when it is appropriate to use either compound variables or the
data stack in a given programming situation

Accountability:
• Interactive exercise
• Exercises
References
© Copyright IBM Corp. 1999, 2016 Unit 7. Compound variables and the data stack 7-1
Student Notebook
Unit objectives
• Determine when it is appropriate to use either compound
variables or the data stack in a given programming situation
Notes:
V10.1
Student Notebook
Uempty
Compound variables
• Sometimes called "stem variables"
• Consist of two parts: The stem. and the tail
• Stem. starts at beginning of variable name and includes the
first period
• Tail follows the stem
– Tail can have many elements, separated by periods
– Element can be a constant, a simple variable, or a null
• Compound variables are not arrays!
– Though you can do some simple array-like processing with them
• Compound variables have some special properties that simple
variables do not
Figure 7-2. Compound variables ES52G5.0
Notes:
REXX compound variables are composed of two parts: the stem, which ends in a period, and the
tail. The stem begins with the first character of the variable, and goes up to and includes the first
period. The first period is part of the stem.
The tail follows the stem. Most of the time you will see or use only one element in the tail of a
compound variable, but each compound variable tail may have many elements, each separated
from the others by a period. The period is not part of the element. Each element may be one of
three things: a simple REXX variable in and of itself, a constant (like a number), or a null.
Compound variables have some very special properties of which you can take advantage, which
simple variables do not. We will discuss these special properties over the next few pages.
Student Notebook
First special property: The stem

• A simple variable value defaults to its own name in uppercase
(uninitialized variables).
• Initializing a stem to some value automatically initializes every
compound variable in the program with the same stem to the
same value as the stem.
• Example:
day. = 'Monday‘
Don't forget the period!
• Now, every compound variable in the program that begins with

"day." will automatically hold the value "Monday", unless you
specifically assign a different value to that individual compound
variable.
Figure 7-3. First special property: The stem ES52G5.0
Notes:
If you do not assign a value to a variable in REXX, that variable is “uninitialized.” Uninitialized
variables assume as their value their own names in uppercase.
If you assign a value to a compound variable stem, then every other compound variable used in the
exec that has the same stem automatically assumes the value assigned to the stem, not its own
name in uppercase, unless you specifically assign that individual compound variable to a different
value.
V10.1
Student Notebook
Uempty
Stem exercise
day. = "Monday"
day.2 = "Tuesday"
day.3 = "Wednesday"
• What value do these compound variables hold?
day.1
day.6
day.Tuesday
day.table
day.2
day.2.3
Figure 7-4. Stem exercise ES52G5.0
Notes:
Fill in the values for the compound variables on the visual above.
Student Notebook
Compound variable example

/* initialize month. with error message */
month. = "no such month"
/* assign individual months */
month.1 = "January"
month.2 = "February"
month.3 = "March"
...
Say month.1 January
Say month.2 February
Say month.99 no such month
Say month.march no such month
Figure 7-5. Compound variable example ES52G5.0
Notes:
Note in the example above the initialization of the stem, followed by individual compound variable
assignments.
V10.1
Student Notebook
Uempty
Second special property: The tail

• If an element is a simple REXX variable itself, then REXX will
substitute the value for the element before resolving the whole
compound variable.
• Examples:
day. = "Monday"
day.2 = "Tuesday"
day.3 = "Wednesday"
cat = 2
Say day.cat cat=2, so this becomes day.2,
dog = 3 which is Tuesday!
Say day.dog
Say day.cat.dog
Figure 7-6. Second special property: The tail ES52G5.0
Notes:
A REXX compound variable element can be one of three items. An element may be a simple REXX
variable in and of itself; an element may be a constant, like a number or a literal string; or an
element may be a null value. An element may not be a function, a comparison, nor an arithmetic
expression. So, coding something like a.6 + 4 will not reference a variable called a.10, instead it
will add 4 to the value of the a.6 variable.
If an element in the tail of a compound variable is, in and of itself, a simple REXX variable, then
REXX will resolve that simple variable with its value before REXX tries to resolve the entire
compound variable. The value of the variable is substituted into the compound variable in place of
the element, and that value becomes part of the compound variable name which is resolved by
REXX.
What will be the values of the compound variables shown at the end of the visual?
Student Notebook
Compound variables in loops

• Compound variables are often used in loops.
• Loop control variable can be used as the tail:
Do i = 1 To 15
Say leadin.i
End i
• Note how the tail, "i," has its value substituted with each
iteration through the loop.
• Negative numbers and zero are allowed.
Figure 7-7. Compound variables in loops ES52G5.0
Notes:
Compound variables are often used in loops, particularly in the control variable type of loop. The
control variable is used as the tail of the compound variable, so that for each iteration through the
loop, a different compound variable is being referenced.
Note, in the example above, that the tail of the compound variable, i, is the loop control variable
name. This variable will be resolved with its value, so the compound variables being referenced are
leadin.1, leadin.2, and so on, through leadin.15.
Compound variable tails are not restricted to positive whole numbers. Negative numbers and zero
are also allowed as values of elements. In fact, element values are not even restricted to numbers
at all, they can be any character string you want.
V10.1
Student Notebook
Uempty
Uses of compound variables

• Simple, one-dimensional arrays (example on previous page)
• Can access information by key values (the tail does not have
to be numeric)
• Output from functions and commands
– OUTTRAP()
– EXECIO
• SYMBOL("stem.tail") function tells you if the variable exists
and holds a valid value (will discuss shortly)
Figure 7-8. Uses of compound variables ES52G5.0
Notes:
The example on the previous page shows compound variables being used in a control variable
loop. This is a very common usage of compound variables, and is a way to simulate simple,
one-dimensional array processing in REXX.
As the tail of a compound variable does not have to be a number, but can be any character string at
all, it can be used as a key to the value the variable holds. We will see an example of this shortly.
A number of functions and commands can be used to populate a series of compound variables with
information. The OUTTRAP() function and the EXECIO command are just two examples.
Sometimes, after dynamically creating a number of variables, we may not be sure whether a
particular variable name exists, or is valid, within our exec. This is especially true with compound
variables. The Symbol() function will test this for us. We will discuss this function on the next page.
Student Notebook
The Symbol() function

• Syntax:
Symbol('name')
where 'name' is a string which may be a valid REXX simple or
compound variable
• Normally 'name' is passed to Symbol() as a literal
• Returns one of three strings:
– 'BAD' (name is not a valid symbol)
– 'LIT' (name is a literal or uninitialized variable)
– 'VAR' (name is a valid REXX variable assigned with a
value)
Figure 7-9. The Symbol() function ES52G5.0
Notes:
The Symbol() function is used to test an argument for its validity as a REXX symbol. The argument
is typically passed to the function as a literal string, thereby letting the Symbol() function resolve the
variable itself.
Symbol() returns one of three strings:
• ‘BAD’ which means that the input string contained characters that are not valid in a REXX
variable name.
• ‘LIT’ which means that the input string is either a literal or an uninitialized variable.
• ‘VAR’ which means that the input string is indeed a valid REXX variable, and it also has a valid
value assigned to it.
V10.1
Student Notebook
Uempty
Another compound variable example

• Consider the following code fragment:
Do i = 1
Say "Enter student name and score:"
Parse Pull name.i score.i
If name.i = '' Then Leave i
End i
• Dynamically creates the number of variables needed.
• Two sets of variables related by the tail (name.4 and score.4 go
together).
• When finished, we know exactly how many variables were created (i -
1), so to process the information:
name.0 = i - 1;score.0 = name.0
Do j = 1 To name.0
Say name.j score.j
....
Figure 7-10. Another compound variable example ES52G5.0
Notes:
In this example we are dynamically creating two sets of compound variables, name.i and score.i.
The exec will create exactly the number of variables that are required, no more, no less. The two
sets of variables are related by the tail number.
When the loop is finished, we know just how many variables have been created (i – 1), so we can
then process the correct number of variables in the next loop.
Student Notebook
Using tails as indexes to data

• Given input data like:
Country Pop. Area Capital
Germany 81M 138K Frankfurt
France 66M 211K Paris
Mexico 120M 762K Mexico City
• We can extract the unique country name and use it as the tail of
compound variables to hold the rest of each record's values:
'EXECIO * DISKR INDD (STEM rec. FINIS'
Do i = 2 To rec.0
Parse Var rec.i cntry pop.cntry area.cntry cap.cntry
End i
Say "What country do you want to learn about?"
Parse Pull country
Say "The population of" country "is" pop.country"."
Say country "has" area.country "square miles."
Say "The capital of" country "is" cap.country"."
Figure 7-11. Using tails as indexes to data ES52G5.0
Notes:
Because we are not limited to using numeric values for the tail of a compound variable, the tail can
become an index, or reference, to the value of the variable itself.
The first bullet above shows our input data records. The EXECIO command (which we will discuss
in the next unit) will read the records from the data set into a series of compound variables called
rec.1, rec.2, and so on. The rec.0 variable contains the number of compound variables that
were created.
In the loop, we parse each record, getting the first word (the country name) into a variable called
cntry, then using that value as the tail of other compound variables to hold the rest of the data
from that country’s record.
To reference the data, we get the country name from the user, then use that as the tail of the
variable which holds the data we want to see. This is a direct, one variable lookup, so it is very fast.
V10.1
Student Notebook
Uempty
The OUTTRAP() function

• Capture output from TSO/E commands into compound
variables
• Syntax:
OUTTRAP( )
OFF
stem.
,max ,concat ,skip
where:
OFF turns output trapping off
stem. is the stem of a compound variable
max is the maximum number of lines of output that may be trapped
concat is either the word CONCAT or NOCONCAT
skip is the number of lines of output to skip before trapping begins
Figure 7-12. The OUTTRAP() function ES52G5.0
Notes:
The OUTTRAP() function provides the ability to capture and store the output from TSO/E
commands into REXX compound variables. This is a TSO/E REXX function, that is, it is provided as
part of the TSO/E implementation of REXX, and is not available on all platforms.
As all functions may be invoked as subroutines, OUTTRAP() may be used this way as well.
Student Notebook
How to use OUTTRAP()

• Turn OUTTRAP() on, issue command, turn OUTTRAP() off
• Example:
x = OUTTRAP('rec.','*','NOCONCAT')
"LISTA STAT" /* TSO command to list allocations */
x = OUTTRAP('OFF')
• Remember, all functions can be called as subroutines
Figure 7-13. How to use OUTTRAP() ES52G5.0
Notes:
While you can trap output from multiple commands at once, this is typically not the way OUTTRAP()
is used. Normally you would set the trap, issue one command, and turn the trap off.
Note in the example above that all of the arguments are passed as literal strings, even the stem of
the compound variable. This is necessary because the OUTTRAP() function must receive the
actual stem name, so we do not want REXX to resolve the variable with its value before calling the
function.
If we were to invoke OUTTRAP() as a subroutine in the example above, the syntax would be:
Call OUTTRAP ‘rec.’,’*’,’NOCONCAT’
What is the purpose of the variable x?
V10.1
Student Notebook
Uempty
Variables created by OUTTRAP()

• OUTTRAP() creates these variables:
– rec.1, rec.2, ... rec.n - Contain lines of captured output
– rec.0 -- "dot-zero" variable - Contains value of "n"
– rec.MAX - Contains value of second argument to OUTTRAP()
– rec.CON - Contains value of third argument to OUTTRAP()
– rec.TRAPPED - Contains total number of lines of command output
that have been trapped
– rec.SKIPPED - Contains the number of lines of output that have
been skipped so far
– rec.SKIPAMT - Contains the number of lines of output to be skipped
before output trapping begins
Figure 7-14. Variables created by OUTTRAP() ES52G5.0
Notes:
Using the example from the previous page, the lines of output from the LISTALC STATUS
command will be stored in a series of compound variables called rec.1, rec.2, and so on, for all
of the lines of output from the command. The number of lines of command output that were trapped
is held in the rec.0 variable.
OUTTRAP() creates a number of other variables, as shown in the visual.
The rec.TRAPPED variable may hold a different value than rec.0. The rec.SKIPPED variable
value may not be higher than that of the rec.SKIPAMT variable.
Student Notebook
When does OUTTRAP() work?

• All command output generated with PUTLINE macro.
• OUTTRAP() will not capture output created with TPUT or WTO.
• Works for:
– Almost all TSO/E commands
– LISTALC, LISTCAT, and all other IDCAMS commands
– RACF commands
– RMM commands
– REXX Say instruction in an exec invoked by your exec (tso/call)
• Does not work for:
– HSM commands
– OUTPUT command
– REXX messages (IRX prefix)
– REXX Trace messages
– Say instructions in current exec
Figure 7-15. When does OUTTRAP() work? ES52G5.0
Notes:
OUTTRAP() is pretty good, but unfortunately it doesn't work for absolutely every command. First,
the TSO/E command must be coded appropriately for OUTTRAP() to work. This is not a big
limitation, as OUTTRAP() is only a REXX interface to what was a preexisting TSO/E feature. TSO/E
provides a number of programming mechanisms (macros or application programming interfaces)
for TSO/E programs to communicate with the user. TPUT and WTO will only create messages
directed at screens, whereas PUTLINE puts a message into a stream which can be redirected.
If you’re not sure whether OUTTRAP() will capture the output of a command you want to issue, you
can always test it with REXXTRY.
V10.1
Student Notebook
Uempty
What is the data stack?

• A dynamically sized buffer in memory
• Provided by the operating system or by REXX (implementation
dependent)
• Temporary data storage
• Stack attributes are implementation dependent
• Can place records into stack from top or bottom
• Can only retrieve records from the top!
Figure 7-16. What is the data stack? ES52G5.0
Notes:
REXX makes available to the programmer a dynamically expandable data structure called a data
stack in which you can temporarily store information. Each element of the stack can be thought of
as a record. Each record can contain a virtually unlimited number of bytes. The size of the stack is
limited by the available virtual storage of your address space.
Records (items, elements) may be placed on the stack from either the top (LIFO) or the bottom
(FIFO). Records may only be removed from the top of the stack.
Student Notebook
Data stack
Can stack Can stack
records LIFO records FIFO
Last In First First In

Out First Out
elem 4
elem 3 elem 4
elem 1
elem 2 elem 3
elem 2
elem 1 elem 2
elem 3
elem 1
elem 4
elem 5
Figure 7-17. Data stack ES52G5.0
Notes:
Data records, or items, or elements (these terms are virtually interchangeable) may be placed into
the stack from the top. Data records may only be removed from the top of the stack. When this is
done, the last record placed into the stack will be the first record removed from the stack. We say
that we are stacking these records “LIFO”, or Last In, First Out.
Data records may also be placed into the stack from the bottom. Again, records may only be
removed from the top of the stack. When records are placed in the stack from the bottom, the first
record placed in the stack will be the first record removed from the stack. We say that we are
stacking these records “FIFO”, or First In, First Out.
The data stack has some unique characteristics, such as:
- It can contain a virtually unlimited number of data items of virtually unlimited size.
- It can contain commands to be issued after the exec ends.
- It can pass information between REXX execs and other types of programs in a TSO/E or
non-TSO/E address space.
V10.1
Student Notebook
Uempty Because of the data stack's unique characteristics, you can use the data stack specifically to:
- Store a large number of data items for a single exec's use.
- Pass a large number of arguments or an unknown number of arguments between a routine
(subroutine or function) and the main exec.
- Pass responses to an interactive command that can run after the exec ends. Note: Data left
in the stack when the exec ends will be treated as TSO commands and will try to execute as
such.
- Store data items from an input data set, which were read by the EXECIO command.
Student Notebook
Using the data stack

• Three basic REXX instructions:
– Push - Put one record on top of stack
– Queue - Put one record on bottom of stack
– Parse Pull - Remove one record from top of stack
• One REXX function:
– Queued() - Return number of records in the stack
Figure 7-18. Using the data stack ES52G5.0
Notes:
Data is added to the stack with either the Push or Queue keyword instructions. Both have a single
operand, which is a REXX expression. The result of the evaluation of the expression becomes the
record which is placed into the stack. The Push instruction places one record on the stack from the
top. The Queue instruction places one record on the stack from the bottom.
The Parse Pull instruction removes one record from the top of the stack. The content of the record
will be divided into variables according to the rules in the variable template.
The Queued() function returns the number of records currently in the stack. There are no
arguments to this function.
The following examples illustrate the difference when QUEUE and PUSH are used to place data in
the data stack. PARSE PULL is used to retrieve information from the stack.
REXX in TSO/E uses an expandable data structure called a data stack to store information. Data
stacks are used to temporarily hold data items until they are needed.
Data is placed into the data stack using either the PUSH or QUEUE instructions. Data is retrieved
from the data stack using the PULL or PARSE PULL instruction. The difference between the PUSH
and QUEUE commands is apparent when the data is retrieved from the data stack.
V10.1
Student Notebook
Uempty PUSH is used to place data on top of the stack. This equates to last in first out (LIFO) when the data
is retrieved. QUEUE places data last in the stack, equating to first in first out (FIFO).
To determine the number of elements in the stack you use the built in function QUEUED(). This will
return a number representing the number of elements in the stack.
When an exec issues a PULL instruction, and when it issues an interactive TSO/E command, the
data stack is searched first for information and if that is empty, information is retrieved from the
terminal.
QUEUE example:
/* REXX */
DO A = 1 TO 3
QUEUE "A=" A /* PUT DATA IN THE STACK (FIFO) */
END
SAY "NUMBER OF ELEMENTS IN THE STACK IS:" QUEUED()
IF QUEUED() > 0 THEN
DO QUEUED() /* DISPLAY ALL THE ITEMS IN THE STACK */
PARSE PULL V1
SAY V1
END
EXIT
When executed the results are:
NUMBER OF ELEMENTS IN THE STACK IS: 3
A= 1
A= 2
A= 3
PUSH example:
/* REXX */
DO A = 1 TO 3
PUSH "A=" A /* PUT DATA IN THE STACK (LIFO) */
END
SAY "NUMBER OF ELEMENTS IN THE STACK IS: " QUEUED()
IF QUEUED() > 0 THEN
DO QUEUED() /* DISPLAY ALL THE ITEMS IN THE STACK */
PARSE PULL V1
SAY V1
END
EXIT
When executed the results are:
NUMBER OF ELEMENTS IN THE STACK IS: 3
A= 3
A= 2
A= 1
Student Notebook
What happens when the stack is empty?
Parse Pull
When
Queued() = 0
REXX expects the

terminal to respond
Figure 7-19. What happens when the stack is empty? ES52G5.0
Notes:
When records are read from the stack with the Parse Pull instruction, they are removed from the
stack. If, after reading the last record from the stack, another Parse Pull instruction is issued, REXX
expects to receive a response from the terminal keyboard.
It is the responsibility of the programmer to manage the stack. Use the Queued() function to
determine the number of records in the stack.
V10.1
Student Notebook
Uempty
What if you want to request information from the user
while using the data stack?
Say "Please type the info:"
Bypasses Parse External var1
the data Say "Thanks for the info!"
stack
elem 1
elem 2
elem 3
elem 4
Figure 7-20. What if you want to request information from the user while using the data stack? ES52G5.0
Notes:
Note that the stack sits between the program and the user. This is a useful feature. It means that
you can simulate user input by using the stack. But it is extremely inconvenient if you do not want to
use this feature, and want to get input from the terminal.
You may bypass the data stack with the Parse External instruction. Parse External and Parse Pull
are very similar. The difference is that Parse Pull always reads from the stack first, and if it’s empty,
then it looks to the terminal. Parse External bypasses the data stack and always goes directly to the
terminal.
Student Notebook
What if you exit the exec with elements in the data

stack?
Push element2
Push element1
...
Exit
element1
These elements are treated
element2
as commands!
element3 They fall out of the stack
element4
and are executed in order.
You must practice good stack management!!
Figure 7-21. What if you exit the exec with elements in the data stack? ES52G5.0
Notes:
If an exec ends with data records on the stack, those records are passed to the host environment
where they are processed as commands. This may seem odd, but it is done that way for a reason,
and sometimes you might actually want this to happen.
Most of the time, though, you do not want this to happen, because the records in the stack are not
commands, but data records, so you will see error messages such as:
IKJ56621I INVALID COMMAND NAME SYNTAX
when you exit the exec leaving records in the stack.
This means that you must remember to clear the stack before exiting the exec. In normal use, the
stack will clear as you process it. But what if your program fails? Using a Signal instruction and an
error recovery routine, you can simply add this code to the routine:
Do Queued()
Parse Pull
End
V10.1
Student Notebook
Uempty
TSO/E REXX stack commands

• NEWSTACK - Create a new stack, protect previous stack
• DELSTACK - Destroy current stack, restore previous stack
• QSTACK - Which is the current stack?
• MAKEBUF - Create new buffer inside stack
• QBUF - Which is the current buffer?
• QELEM - How many elements in the buffer created by
MAKEBUF
• DROPBUF - Destroy buffer(s)
Figure 7-22. TSO/E REXX stack commands ES52G5.0
Notes:
The commands shown above are all TSO/E REXX commands. This means that they are part of
TSO/E, but they are only usable within a REXX exec. We will discuss each of these commands
over the next several pages.
MAKEBUF - Create a buffer in the data stack
DROPBUF- Drop a buffer in the data stack
QBUF - Find the number of buffers in a data stack
QELEM - Find the number of elements in a buffer
NEWSTACK - Create a new data stack
DELSTACK - Delete the most recently created data stack
QSTACK - Find the number of stacks that exist
Student Notebook
NEWSTACK command
• First stack (created at log • NEWSTACK command is issued:
on), with three records
queued
Address TSO 'NEWSTACK'
elem 1
elem 1
elem 2
elem 2
elem 3
elem 3
Stack 1 Stack 1 Stack 2
Say Queued() Say Queued()
3 0
Figure 7-23. NEWSTACK command ES52G5.0
Notes:
The first stack available to your TSO/E address space is created at logon time. We will call this
Stack 1. The NEWSTACK command creates another stack, Stack 2, then Stack 3, and so forth.
You may have many stacks in existence, but only one stack may be used at a time. When a new
stack is created, the currently active stack is closed and protected.
V10.1
Student Notebook
Uempty
DELSTACK command
• Current stacks • DELSTACK command is issued:
Address TSO 'DELSTACK'

elem 1
elem 1 elem 1
elem 2
elem 2 elem 2
elem 3
elem 3 elem 3
elem4
Say Queued() 4
Figure 7-24. DELSTACK command ES52G5.0
Notes:
The DELSTACK command deletes the current stack, and all of its records. It then reopens the next
previous stack so that it is available again.
If a DELSTACK command is issued against Stack 1, that stack is simply emptied. It is still considered
more elegant to use a simple loop to empty the stack:
Do Queued()
Parse Pull
End /* Queued() */
Student Notebook
QSTACK command
Current stacks
elem 1 elem 4 elem 1
elem 2 elem 3 elem 2
elem 3 elem 2
elem 1
Address TSO 'QSTACK'

Say rc
Figure 7-25. QSTACK command ES52G5.0
Notes:
The QSTACK command sets a return code with the number of the current stack. So, if only one
NEWSTACK command was issued, the return code from QSTACK would be 2. If no NEWSTACK
command is issued, QSTACK sets a return code of 1.
The return code is captured in the REXX special variable called rc.
V10.1
Student Notebook
Uempty
MAKEBUF command
• Each stack has an initial buffer, • MAKEBUF command is issued,
Buffer 0 creating a new buffer:
Address TSO
'MAKEBUF'
elem 4
elem 1
3
elem 5
elem 2 Buffer 1
elem 6
elem 3
1 Buffer 0
elem 1 Queue
Stack 1 Queue elem 2
elem 3 Buffer 0
Stack 1
All MAKEBUF really does is change the point of
FIFO insertion into the stack!
Figure 7-26. MAKEBUF command ES52G5.0
Notes:
Every stack, when it is created, contains a buffer, called Buffer 0. When records are placed in the
stack, they are placed into the current buffer. New buffers may be created with the MAKEBUF
command. MAKEBUF sets a return code with the number of the buffer it just created.
Creating a new buffer simply changes the point of FIFO insertion into the stack. If a Queue
instruction is used to place a record into the stack, that record is inserted into the bottom of the
current buffer.
Student Notebook
QBUF command
Current stack
elem 6
elem 7
elem 8 Buffer 2
elem 4
Address TSO 'QBUF'
elem 5 Buffer 1 Say rc
elem 1
elem 2
elem 3 Buffer 0
2
Stack 1
Figure 7-27. QBUF command ES52G5.0
Notes:
The QBUF command sets a return code with the number of the current buffer. If no MAKEBUF
command has been issued, QBUF sets a return code of 0.
V10.1
Student Notebook
Uempty
QELEM command
• QELEM sets return code with number of elements in the buffer
most recently created by MAKEBUF
Current stack Current stack
elem 4 elem 1
elem 5 elem 2
Buffer 1
elem 6 elem 3
elem 4
elem 1
elem 2 elem 5
elem 3 Buffer 0 elem 6 Buffer 0
Stack 1 Stack 1
Address TSO 'QELEM' Address TSO 'QELEM'
Say rc Say rc
3 0
Figure 7-28. QELEM command ES52G5.0
Notes:
The QELEM command sets a return code with the number of records in the current buffer which was
created by MAKEBUF. This is an important point to note! If no MAKEBUF command has been issued,
QELEM sets a return code of 0.
Student Notebook
DROPBUF command
elem 7
elem 8
Buffer 2
elem 4 elem 4
elem 5 elem 5
Buffer 1 Buffer 1
elem 6 elem 6
Address TSO
elem 1 elem 1
'DROPBUF'
elem 2 elem 2
elem 3 Buffer 0 elem 3 Buffer 0
elem 7
elem 8
Buffer 2
elem 4
elem 5
Buffer 1
elem 6
Address TSO
elem 1 elem 1
'DROPBUF 1'
elem 2 elem 2
Buffer 0
elem 3 Buffer 0 elem 3
Figure 7-29. DROPBUF command ES52G5.0
Notes:
The DROPBUF command deletes a buffer and all of its records. Entering DROPBUF without operands
deletes only the current buffer and its records. Following DROPBUF with a number will delete that
numbered buffer, its records, plus all later buffers and their records as well.
If DROPBUF 0 is issued, or if no MAKEBUF command was issued and you issue a DROPBUF, the
stack will be emptied, but Buffer 0 will still exist. Just as Stack 1 is indestructible, Buffer 0 within any
stack is indestructible, for as long as that stack exists.
V10.1
Student Notebook
Uempty
Uses of the data stack

• Communication with other programs
– EXECIO command
– As an alternative to passing parameters
• Subcommands and responses to prompts
– Such as FTP command
• Temporary data storage
• Executing commands after the exec ends
Figure 7-30. Uses of the data stack ES52G5.0
Notes:
The data stack has many uses. It can be used to pass large amounts of data between programs
and routines, such as external subroutines. The EXECIO command, which will be discussed in the
next unit, can use either compound variables or the data stack.
As the data stack sits between the user and the program, it can be used to provide subcommands
or command responses, removing the need for the user to type these things in while the program is
running.
The stack is often used to temporarily store data records which will be retrieved and used later in
the program. Also, once in a while, the stack may be used at the end of an exec to store a
command to be executed after the exec ends.
Student Notebook
Stack advantages and disadvantages

• Advantages:
– Good for passing parameters between external routines
• Disadvantages:
– Two step process: read data from input source into stack, then read
from stack into variables (opposite for write)
– Stack attributes are OS dependent
– Stack usage commands are OS dependent
– Stack management is the programmer's responsibility
Figure 7-31. Stack advantages and disadvantages ES52G5.0
Notes:
The data stack is excellent for passing parameters, and particularly large amounts of data, between
your REXX exec and external routines.
But there are a number of disadvantages to using the data stack, as noted above.
V10.1
Student Notebook
Uempty
Compound variables advantages and
disadvantages
• Advantages:
– They are just REXX variables
– They are already inside your exec - only one step to assign
– Rexx will manage them like other variables
– They help provide clever and imaginative programming methods
• Disadvantages:
– They cannot be passed between external routines
Figure 7-32. Compound variables advantages and disadvantages ES52G5.0
Notes:
Compound variables have several advantages, as noted above.
The main disadvantage of using compound variables is that it is more difficult to pass them, and
their values, to external programs. This is true of all REXX variables.
Student Notebook
Checkpoint (1 of 3)
1. Compound variables consist of two components, the (blank)
and the (blank).
2. True or False: Each compound variable can have only one

tail.
3. A compound variable tail may be one of three items: a

(blank), a (blank), or a (blank).
4. True or False: If you do not initialize the stem, then an

uninitialized compound variable will assume as its value its
own name in uppercase.
Notes:
V10.1
Student Notebook
Uempty
Checkpoint (2 of 3)
5. In the following OUTTRAP() function, which variable will hold
the number of records of command output?
X = OUTTRAP(‘line.’,’*’,’NOCONCAT’)
6. True or False: Data records can be removed from either the

top or the bottom of the data stack.
7. The instruction to remove one record from the top of the

stack is (blank).
Notes:
Student Notebook
Checkpoint (3 of 3)
8. True or False: When the QELEM command sets a return code
of zero, you know the data stack is empty.
9. The Push instruction stacks records (blank).
10. The Queue instruction stacks records (blank).
Notes:
V10.1
Student Notebook
Uempty
Unit summary
• Determine when it is appropriate to use either compound
variables or the data stack in a given programming situation
Notes:
Student Notebook
V10.1
Student Notebook
Uempty
Unit 8. Reading and writing data sets in REXX

This unit discusses the commands and functions used in REXX execs to
accomplish I/O operations. The TSO/E EXECIO command is covered, as are
the REXX Stream I/O functions. The Stream I/O functions are shipped with
the IBM Library for REXX on System z, and also are available with the REXX
Alternate Library on System z.

• Discuss the TSO/E EXECIO command
• Understand the stream I/O concept
• Discuss the REXX stream I/O functions

Accountability:
• Exercises
References
© Copyright IBM Corp. 1999, 2016 Unit 8. Reading and writing data sets in REXX 8-1
Student Notebook
Unit objectives
Notes:
V10.1
Student Notebook
Uempty
EXECIO command
• Sequential data set or partitioned data set member
• Uses ddnames, not data set names
• Can read one or more records at a time
– Usually read/write entire data set or member
• Can update records one at a time
• Can use either compound variables or the data stack
Figure 8-2. EXECIO command ES52G5.0
Notes:
The TSO/E EXECIO command is the traditional method for reading and writing data sets from within
a REXX program. EXECIO actually uses ddnames, not data set names, so you must allocate a
ddname to a data set before issuing EXECIO. It may also read from and write to the TSO/E console
(keyboard and screen) by specifying the appropriate ddnames referencing the console device.
For data set I/O, EXECIO will only read and write sequential data sets and partitioned data set
members. It will not work with VSAM, nor any other type of data set. Typically one would read or
write the entire data set or member with one command, though you may read or write any number
of records at a time that you want. Be aware that data sets are read into your address space virtual
storage, so a very large data set may exhaust your virtual storage resources.
EXECIO may read or write either the data stack or compound variables, depending upon the way in
which you use the command.
Student Notebook
EXECIO command syntax

EXECIO num fnctn ddname
* start parms
where:
num is the number of lines to read or write ('*' means all)
fnctn is either DISKR, DISKW, or DISKRU
ddname is the ddname of the data set to read or write
start is the starting line number (for DISKR only)
parms is a function dependent set of parameters (next page)
Figure 8-3. EXECIO command syntax ES52G5.0
Notes:
The syntax of the TSO/E REXX EXECIO command is shown above. The first operand is the number
of lines to read or write. The asterisk (*) means all lines. The second operand of the command is the
function EXECIO is to perform. DISKR means that you want to read from disk. DISKW means you
want to write to disk. DISKRU means “read with update.” This operand is designed so that you can
read one record, update it, and then write that record back to the data set. In modern programming
paradigms, this operand would rarely be used. The fourth operand (start) is only valid with DISKR
and DISKRU. It represents the line number of the data set where reading is to begin.
The third operand (ddname) is the name of the file to which the sequential data set or member of
the PDS was allocated. You must allocate the file before you can issue EXECIO. For example, you
can allocate a file by using the ALLOCATE command in the TSO/E address space or you can use a
JCL DD statement.
The parms operand is a set of parameters that are dependent upon the function being used
(DISKR, DISKRU, or DISKW). These parameters are discussed on the next page.
V10.1
Student Notebook
Uempty
EXECIO optional read and write parameters

y For DISKR and DISKRU:
(
FIFO OPEN FINIS SKIP )
LIFO
STEM stem.
• For DISKW:
(
STEM stem. OPEN FINIS )
where:
FIFO places records on the data stack FIFO
LIFO places records on the data stack LIFO
STEM stem. identifies the stem of a compound variable
OPEN opens the data set if not already open
FINIS closes the data set when EXECIO completes
SKIP skips over records
Figure 8-4. EXECIO optional read and write parameters ES52G5.0
Notes:
The parameters you use with EXECIO are slightly different depending on whether you want the
command to read or write a data set. When reading a data set, EXECIO will place the records it
reads into the data stack FIFO by default, so FIFO is the default parameter.
If you code the parameter STEM, you must follow it with the stem name of a compound variable. Do
not forget the period at the end of the stem! The first record read from the data set is assigned to
the variable stem.1, the second record is assigned to stem.2, and so forth. The variable stem.0
is automatically created with the number of records read (in other words, the number of compound
variables created). When writing records by using the STEM parameter, the data in variables
stem.1, stem.2, and so on, are written to the data set. When writing, the stem.0 variable is not
automatically used.
The OPEN parameter will open the data set if it is not already open. This is usually not required,
because the data set will be opened automatically anyway. The FINIS parameter closes the data
set when EXECIO is done. If not coded, the data set remains open. The SKIP parameter reads the
specified number of lines, but does not place them on the stack or in variables. In other words,
EXECIO skips over these records.
Student Notebook
EXECIO command examples

z 'EXECIO * DISKR SYSUT1'
z 'EXECIO * DISKR' myindd '(STEM rec.'
z 'EXECIO 1 DISKRU INDD 4 (STEM txt.'
z 'EXECIO 1 DISKW FOGGY (STEM data.'
z 'EXECIO' Queued() 'DISKW' ddout '(FINIS'
z 'EXECIO' rec.0 'DISKW MYOUT (STEM rec. FINIS'
z 'EXECIO 0 DISKW OUTDD (FINIS'
z 'EXECIO 0 DISKW OUTPUT (OPEN FINIS'
What will each of these commands do?
Figure 8-5. EXECIO command examples ES52G5.0
Notes:
Here are some examples of using the EXECIO command. Note the use of quotes. As EXECIO is a
TSO/E REXX command, you may only code this command in a REXX exec.
V10.1
Student Notebook
Uempty
Using EXECIO in REXX (1 of 2)

/* Rexx EXECIO example to copy a data set */
Signal On Error
'ALLOC DA(MY.INPUT) FI(INDD) SHR REUSE'
'ALLOC DA(''TSOCH27.OUTPUT.DATA'') FI(OUTDD) OLD REUSE'
Say "Reading from MY.INPUT."
'EXECIO * DISKR INDD (STEM rec. FINIS'
Say rec.0 "records were read from MY.INPUT."
Say "Writing to 'TSOCH27.OUTPUT.DATA'."
'EXECIO' rec.0 'DISKW OUTDD (STEM rec. FINIS'
Say "Done."
'FREE FI(INDD OUTDD)'
Exit 0
Error:
Say "Error occurred on line" sigl". Return code:" rc Say
"Source code at this line is:"
Exit 99
Figure 8-6. Using EXECIO in REXX (1 of 2) ES52G5.0
Notes:
Here is an example of a REXX exec which contains EXECIO commands as well as other supporting
commands. This exec copies one data set to another.
Student Notebook
Using EXECIO in REXX (2 of 2)

/* Rexx EXECIO example to update data set records */
"ALLOC DA('WX235.IN.PDS(MYDATA)') FI(INDATA) SHR REUSE"
If rc <> 0 Then Call Errtn
Do Forever
'EXECIO 1 DISKRU INDATA'
If rc = 2 Then Leave /* reached EOF */
Parse Pull inline
Say inline
Say "Type new line if desired."
Say "If no changes, just press ENTER."
Parse Pull newline
If newline = '' Then Nop
Else
Do
Push newline
'EXECIO 1 DISKW INDATA'
End /* Else Do */
End /* Do Forever */
'EXECIO 0 DISKW INDATA (FINIS'
'FREE FI(INDATA)'
Exit 0
Errtn:
Figure 8-7. Using EXECIO in REXX (2 of 2) ES52G5.0
Notes:
Here is another example of a REXX exec which uses EXECIO. It reads and optionally updates the
records in a data set.
V10.1
Student Notebook
Uempty
REXX stream I/O function package

• Shipped with the IBM REXX Compiler Library for z/OS (FMID
5695-014)
• Also shipped with the IBM Alternate Library for REXX with
z/OS
– Installed with SMP/E
• Can fully install as a REXX function package
– Must assemble and linkedit IRXPARMS and IRXTSPRM modules
• Can also //STEPLIB to function load libraries
Figure 8-8. REXX stream I/O function package ES52G5.0
Notes:
Functions for performing stream I/O operations are included as part of the REXX implementation on
many platforms. These functions are available for use under TSO/E as a function package, which is
included as part of the IBM Library for REXX on zSeries product, FMID 5695-014, which you would
acquire in conjunction with the REXX compiler. The function package is also included with the IBM
Alternate Library for REXX, which is included as part of the z/OS system, and can be downloaded
from IBM's website free of charge.
Whichever way the function package is acquired, it must be installed on your system. Follow the
directions provided in the IBM Compiler and Library for REXX on zSeries User's Guide and
Reference (SH19-8160) to install the function package in your system's LPA. You can also make
the data sets containing the functions available to add to your STEPLIB DD statements.
Student Notebook
Why stream I/O?

• EXECIO command is not available on all platforms
• Almost all REXX implementations support stream I/O functions
• Extends and enhances I/O capabilities of REXX for TSO/E
• Shields complexity of z/OS data set I/O (to some degree)
• Leads to easier coding syntax
• Provides better portability of REXX between OS platforms
Figure 8-9. Why stream I/O? ES52G5.0
Notes:
Stream I/O is a concept already implemented in REXX for various operating system platforms. On
z/OS and its predecessors, though, programmers needed to use the EXECIO command to access
z/OS data sets. EXECIO requires programmers to consider many parameters, and to care about the
allocation and deallocation of data sets. The TSO/E REXX Stream I/O functions hide this
complexity. Programmers can use these easy-to-use functions to access z/OS data. Further, the
use of stream I/O functions makes REXX more portable among platforms that support stream I/O.
V10.1
Student Notebook
Uempty
The stream I/O concept

• A stream is simply a sequence of characters
• Stream can be read or written character by character
• Stream can be read or written line by line
• Functions perform stream I/O operations
– Open, close, and name streams
– Query existence, characteristics of streams
– Read and write data
– Check for further data availability in input streams
• Position pointer is maintained within stream during I/O
operations (while stream is open)
• Streams can be persistent or transient
Figure 8-10. The stream I/O concept ES52G5.0
Notes:
A stream is a popular concept for how to perform input and output to and from a program. Basically,
a stream is a sequence of characters with functions to take characters out of one end of the stream,
and put characters into the other end of the stream. One end of the stream is connected to a
physical or logical I/O device, such as a keyboard, display screen, file, or queue. If it is an output
stream, your program puts characters into one end of the stream, and an output device takes
characters out of the other end. If it is an input stream, an input device puts characters into one end
of the stream, and your program takes characters out of the other end.
The purpose of stream I/O is to simplify a programmer’s view of input and output devices. The
physical characteristics of I/O devices and the organization of data remain hidden, thus shielding
the complexity of z/OS data set I/O from the programmer.
Student Notebook
Naming streams
• A stream name may be:
• A data set name
– Sequential data set or PDS name with member
• A ddname
– TSO ALLOCATE command
– JCL DD statement
– Assigned using the Stream() function
• A default value
– For TSO/E foreground
• SYSIN is the input stream (the terminal keyboard)
• SYSOUT is the output stream (the terminal screen)
– For TSO/E background and z/OS
• SYSTSIN is the input stream
• SYSTSPRT is the output stream
Figure 8-11. Naming streams ES52G5.0
Notes:
If you do not specify the name of a stream in a stream I/O function, the default input or output
stream will be used. Interactively in TSO/E, these represent the terminal keyboard and display, or,
the SYSIN and SYSOUT ddnames (you should just let them default and not use the ddnames). In
TSO/E in batch, or in an MVS address space, the SYSTSIN and SYSTSPRT ddnames are used.
In order to use other than the default input and output streams, you must explicitly name a stream in
the function you are using. A stream name may be either a fully or non-fully qualified sequential
data set name or partitioned data set name with a member name. Some of the examples of the
functions we’ll see will show this.
A stream name may also be a ddname. This ddname may be assigned by using a JCL DD
statement or by using the TSO/E ALLOCATE command. It may also be assigned by the Stream()
function, which we will also see shortly.
V10.1
Student Notebook
Uempty
The Stream() function

• Syntax:
Stream(name,operation,streamcommand)
where:
name is the name of the stream (see previous page)
operation is the literal word 'Command' or letter 'C'
streamcommand is one of:
OPEN opens the stream for input operations
OPEN READ same as OPEN
OPEN WRITE opens the stream for output operations
CLOSE closes the named stream
CLOSE ALL closes all streams opened in this program
QUERY EXISTS queries existence of named stream
QUERY REFDATE queries date when stream was last referenced
QUERY SERVICELEVEL queries the service level of the
Stream I/O function package
Figure 8-12. The Stream() function ES52G5.0
Notes:
The Stream() function is used to identify a name for a stream, open the stream for input or output,
close the stream, or query information about a stream or the stream I/O function package itself.
The first argument is the name of the stream. This may be a data set name or a ddname known to
TSO/E. The second argument is required, and is either the word ‘Command’, or the letter ‘C’.
The stream command provides the operation the Stream() function is to perform. OPEN and
OPEN READ both open the stream for input operations, and OPEN WRITE opens the stream for
output operations. You should not open a stream for read and write operations at the same time.
CLOSE ALL closes all of the streams opened so far in the REXX program. The name of the stream
is meaningless when you use CLOSE ALL, and may be omitted.
The values returned by the stream function will vary depending upon the stream command used.
These values are discussed on the next page.
Student Notebook
Values returned by Stream()

z For OPEN, Stream() returns:
– A ddname in the form of &SYSxxxxx (xxxxx is a number)
– The string -ERROR
z For CLOSE, Stream() returns 0 if successful, else it returns 4

z For QUERY EXISTS, Stream() returns the fully qualified data
set name allocated to the named stream
z For QUERY REFDATE, Stream() returns the date when the
named stream was last referenced in Julian form (yyyy/ddd)
z For QUERY SERVICELEVEL, Stream() returns the version,
release, modification, fix level, and date of the function
package, for example: REXXSIO 140 FIX0000 20030801
Figure 8-13. Values returned by Stream() ES52G5.0
Notes:
Each time the Stream() function opens a stream that is specified as a data set name, it
automatically generates enumerated ddnames of the form &SYSxxxxx. The leading ampersand
distinguishes them from data set names, and xxxxx is a number. These unique ddnames can be
used in a REXX program to explicitly name a stream with the stream I/O functions. If the open fails,
the string “-ERROR” is returned.
When a stream is successfully closed, a value of 0 (zero) is returned. If the close is unsuccessful,
the function returns a value of 4.
The QUERY EXISTS command returns the fully qualified data set name allocated to the named
stream. The QUERY REFDATE returns the date, in Julian form, that the stream was last referenced,
like 2007/341.
V10.1
Student Notebook
Uempty
Stream() examples
infile = Stream("'TSOCH27.IN.DATA'",'C','OPEN READ')
x = Stream('MY.DATAFILE','C','CLOSE')
indd = Stream(strinp,'C','OPEN WRITE')
dsn = Stream(infile,'C','QUERY EXISTS')
jdate = Stream(infile,'C','QUERY REFDATE')
done = Stream(,'Command','CLOSE ALL')
Figure 8-14. Stream() examples ES52G5.0
Notes:
Some examples of the stream function are shown in the visual above. Note the use of quotes
around the literals, particularly the data set names.
What value will be returned in each of these examples?
Student Notebook
The Charin() function

z Syntax:
Charin( )
name ,
start ,length
where:
name is the name of the input stream
start can be 1 for a persistent stream, must not be
specified for a transient stream
length is the number of characters to be read from the stream
• Charin() returns either a string of characters or a null string
Figure 8-15. The Charin() function ES52G5.0
Notes:
The visual shows the syntax of the Charin() function. The first argument is the name of the input
stream. The second argument is the starting point where Charin() will begin to read data. This value
may be a 1 for a persistent stream. No other value is supported. Do not specify a starting position
for a transient stream, as the next character is always the transient stream starting point. The third
argument is the number of characters the function is to read. Specifying a length value of 0 means
that no data will be read.
Specifying a start value of 1 and a length of 0 together means that the read position is set to the
beginning of the stream and no characters will be read.
The value returned by Charin() will be either the character string read from the input stream, or a
null value.
V10.1
Student Notebook
Uempty
Charin() examples
indata = Charin('MY.FILE',1,10)
x = Charin("'TSOCH27.INPUT.DATA'",1,0)
nextchar = Charin(infile)
nexttwo = Charin(myfile,,2)
termchar = Charin()
nxtchars = Charin(,,5)
Figure 8-16. Charin() examples ES52G5.0
Notes:
The visual shows several examples of the Charin() function that may be used in a REXX exec.
What will each of these examples accomplish? What values will be returned?
Student Notebook
The Charout() function

z Syntax:
Charout( )
name ,
string ,start
where:
name is the name of the output stream to be written
string is the string to write to the output stream
start can be 1 for a persistent stream, must not be
specified for a transient stream
• Charout() returns 0 (zero) if successful, else returns 1
Figure 8-17. The Charout() function ES52G5.0
Notes:
The visual shows the syntax of the Charout() function. The first argument is the name of the output
stream. The second argument is the string to write to the output stream. The third argument
specifies the starting point where Charout() will begin to write data. This value may be a 1 for a
persistent stream. No other value is supported. Do not specify a starting position for a transient
stream, as the next character is always the transient stream starting point.
For a persistent stream (like a data set), the length of the string to be written is limited to a
maximum of 32760 characters. For transient streams (like terminal output), the length of the string
is limited by the capabilities of the device being written, which is typically 80 characters.
Specifying a null string together with a start value of 1 means that the write position is set to the
beginning of the stream and no characters will be written.
The value returned by Charout() will be 0 if the write was successful, or 1 of the string could not be
written to the output stream.
V10.1
Student Notebook
Uempty
Charout() examples
chorc = Charout('OUT.FILE','Hello world.')
x = Charout(outdd,,1)
iorc = Charout(outdd,outrec)
termout = Charout(,'Hello world.')
done = Charout(myfile)
Figure 8-18. Charout() examples ES52G5.0
Notes:
The visual above shows some examples of the Charout() function.
What will each of these examples do, and what values will be returned?
Student Notebook
The Chars() function

z Syntax:
Chars( )
name
where name is the name of the input stream to be tested for

remaining input characters
• Chars() returns 1 if one or more characters are available in
the input stream, else returns 0
• Example:
Do While Chars(indd)
If Charin(indd) \= '0D'x Then
string = string || Charin(indd)
End /* While */
Figure 8-19. The Chars() function ES52G5.0
Notes:
The syntax of the Chars() function is shown. This function tests for the availability of more input data
in the named stream. If one or more characters remain available in the input stream, a value of 1 is
returned. Otherwise, Chars() returns a value of 0. These values may be used as true or false test
results, as shown in the example.
V10.1
Student Notebook
Uempty
The Linein() function

y Syntax:
Linein( )
name ,
line ,count
where:
name is the name of the input stream to be read
line is the line number in the input stream where
reading begins; do not specify for a transient stream
count is the number of lines to read, can be 0 or 1
• Linein() returns a line of data or a null string
Figure 8-20. The Linein() function ES52G5.0
Notes:
The syntax of the Linein() function is shown above. The first argument to Linein() is the name of the
input stream. The second argument is the line number (not character position) where the Linein()
function will begin reading. Only specify this argument for persistent streams, not for transient
streams. The third argument is the number of lines of data (not characters) to be read. This value
may only be 0 or 1. A value of 0 means no data would be read, and a null string would be returned.
Specifying a count of 0 means the position pointer will be set at the beginning of the specified line of
the input stream, and no data will be read.
Linein() will return either the line of data that was read or a null string.
Student Notebook
Linein() examples
data = Linein('IN.FILE')
line5 = Linein('''TSOCH27.INPUT.DATA''',5,1)
firstline = Linein(myfile,1,1)
Figure 8-21. Linein() examples ES52G5.0
Notes:
The visual above shows some examples of the Linein() function.
What will each of these examples do, and what values will be returned?
V10.1
Student Notebook
Uempty
The Lineout() function

y Syntax:
Lineout( )
name ,
string ,line
where:
name is the name of the output stream to be written
string is the string to write to the output stream as a line
line can be 1 or null (it is there for compatibility
reasons only)
• Lineout() returns 0 if line is successfully written, else returns

1 if unsuccessful or line only partially written
Figure 8-22. The Lineout() function ES52G5.0
Notes:
The syntax for the Lineout() function is shown above. The first argument is the name of the output
stream. The second argument is the string of data to write to the output stream. The third argument
is present for compatibility reasons, but may only be a null value or a 1. It does not allow you to set
the pointer position to a specific line.
The function will write, by default, starting at the current write position. If the string to be written is
longer than the logical record length of the data set being written, the line will be truncated, and a
value of 1 is returned by Lineout().
Lineout() will return a 0 if the line is written successfully. It will return a 1 if the line could not be
written to the output stream, or if the line is only partially written.
Student Notebook
Lineout() examples
lorc = Lineout(myfile,'Hello world.')
termrc = Lineout(,dataline)
done = Lineout(outdd)
Figure 8-23. Lineout() examples ES52G5.0
Notes:
The visual shows some examples of the Lineout() function.
What do these example instructions do, and what values do they return?
V10.1
Student Notebook
Uempty
The Lines() function

Ɣ Syntax:
Lines( )
name
where name is the name of the input stream to be tested for

remaining lines of data
• Lines() returns 1 if one or more lines (or partial lines) are
available in the input stream, else returns 0
• Example:
Do i = 1 While Lines(indd)
rec.i = Linein(indd)
End i
rec.0 = i - 1
x = Stream(indd,'C','CLOSE')
Figure 8-24. The Lines() function ES52G5.0
Notes:
The syntax of the Lines function is shown above. This function, like the Chars() function, tests the
named input stream for remaining lines of data. If one or more lines or partial lines remain in the
input stream, Lines() returns a value of 1. If the input stream is exhausted, a value of 0 is returned.
This means that the data set or member is empty, the last line of data has been read, or an EOF
condition has been triggered.
The values returned by Lines() (1 or 0) may be used as the result of a conditional expression, as
shown in the example.
Student Notebook
Example REXX I/O functions

• This example opens a stream for the file mydata.txt:
file=stream(’mydata.txt’,’c’,’open write’)
• This example opens a stream for the file mydata.txt, but
replaces the file if it exists:
file=stream(’mydata.txt’,’c’,’open write replace’)
• To read the next 256 characters:
say charin(file,,256)
• To set the read location to the sixth 80-byte record:
call charin file,5*80+1,0
Figure 8-25. Example REXX I/O functions ES52G5.0
Notes:
REXX I/O functions
See z/OS Using REXX and z/OS UNIX System Services SA23-2283-00
The REXX input functions are charin() and linein(). The chars() and lines() functions determine
whether data remains in an input stream.
The REXX output functions are charout() and lineout().
The REXX stream() function controls the processing of I/O streams (file streams and process
streams) and obtains their status.
A number of commands are used within the stream() function to control stream processing.
V10.1
Student Notebook
Uempty
Submit a Job to JES2

• submit()
– Submits a job to the primary subsystem (JES), returning the job ID of
the submitted job.
– Parameters
• stem. : The stem compound variable contains the number of lines in
stem.0 , and each variable from stem.1, stem.2, ... contains a line for the
job that is being submitted.
• Example
– This example reads the file into the stem, sets the number of lines,
and submits the job:
do i=1 by 1 while lines(fn)>0
fn.i=linein(fn)
end
fn.0=i-1
say submit(’fn.’)
Figure 8-26. Submit a Job to JES2 ES52G5.0
Notes:
submit() function.
See z/OS Using REXX and z/OS UNIX System Services SA23-2283-00
Student Notebook
BPXWDYN, interface to dynamic allocation

• This example allocates SYS1.MACLIB to SYSLIB and directs
messages to z/OS UNIX standard error (sdterr):
call bpxwdyn "alloc fi(syslib) da(sys1.maclib) shr
msg(2) ”
• This example requests that the name of the data set allocated
to ddname SYSLIB be returned in the REXX variable dsnvar .
call bpxwdyn "info fi(syslib) inrtdsn(dsnvar)"
• This example frees SYSLIB and traps messages in stem
S99MSG.:
call bpxwdyn "free fi(syslib)"
• This example concatenates SYS1.SBPXEXEC to SYSPROC:
if bpxwdyn("alloc fi(tmp) da(sys1.sbpxexec) shr
msg(2)")=0 then
call bpxwdyn "concat ddlist(sysproc,tmp) msg(2)"
Figure 8-27. BPXWDYN, interface to dynamic allocation ES52G5.0
Notes:
BPXWDYN is a text interface to a subset of the SVC 99 (dynamic allocation) and SVC 109
(dynamic output) services. BPXWDYN supports data set allocation, unallocation, concatenation,
the retrieval of certain allocation information, and the addition and deletion of output descriptors.
BPXWDYN is designed to be called from REXX, but it can be called from several other
programming languages, including Assembler, C, and PL/I.
This interface makes dynamic allocation and dynamic output services easily accessible to
programs running outside of a TSO environment; however, it also functions in a TSO environment.
The syntax for allocation is quite similar to that of TSO for the TSO ALLOCATE and FREE
commands.
Allocate This example allocates SYS1.MACLIB to SYSLIB and directs messages to z/OS UNIX
standard error (sdterr):
call bpxwdyn "alloc fi(syslib) da(sys1.maclib) shr msg(2)"
Info This example requests that the name of the data set allocated to ddname SYSLIB be
returned in the REXX variable dsnvar.
call bpxwdyn "info fi(syslib) inrtdsn(dsnvar)"
V10.1
Student Notebook
Uempty Free This example frees SYSLIB and traps messages in stem S99MSG.:
call bpxwdyn "free fi(syslib)" Concatenate if bpxwdyn("alloc fi(tmp)
da(sys1.sbpxexec) shr msg(2)")=0 then call bpxwdyn "concat ddlist(sysproc,tmp)
msg(2)"
Student Notebook
Checkpoint (1 of 2)
1. True or False: The EXECIO command will work with
sequential data sets, members of partitioned data sets, and
VSAM data sets.
2. True or False: You can write to whatever line you wish with
the Lineout() function.
3. The default EXECIO read parameter is (blank).
4. How many characters can you write to a persistent stream

with a single Charout() function?
Notes:
V10.1
Student Notebook
Uempty
Checkpoint (2 of 2)
5. True or False: You can read from whatever character position
you wish with the Charin() function.
6. True or False: A stream must be opened in order to read from

it or write to it.
7. Is the Stream() function required in order to open a stream?
8. Can you use an asterisk to represent the number of lines to

be written with EXECIO?
Notes:
Student Notebook
Unit summary
Notes:
V10.1
Student Notebook
Uempty
Unit 9. The parse instruction

This unit discusses the single most powerful instruction in the REXX
language, Parse. The general syntax of Parse is discussed, as are the eight
sources of input to Parse, and the many different ways of constructing
variable templates.

• Understand the syntax of the parse instruction
• Discuss the sources of input to the parse instruction
• Discuss the various ways to construct parsing templates

Accountability:
• Exercises
References
© Copyright IBM Corp. 1999, 2016 Unit 9. The parse instruction 9-1
Student Notebook
Unit objectives
Notes:
V10.1
Student Notebook
Uempty
The parse instruction

• "To resolve something into its component parts"
• Syntax:
Parse source
Upper variabletemplate
where:
Upper translates input data to upper case before assigning to
variables in template
source is the input source of the data to be parsed
variabletemplate are the rules for parsing that data, and the
variables to which the data parts
will be assigned.
Figure 9-2. The parse instruction ES52G5.0
Notes:
The visual above should look a little familiar. It’s the same one we saw in the Getting started with
REXX unit of this course. It is repeated here as a reminder of the purpose and syntax of the Parse
instruction.
The keyword “Upper” translates the input data, from whatever source it comes, into uppercase
before assigning it to the variables in the template.
The variable template contains the rules governing the way in which the input data is divided up
(parsed) into parts, and the variables to which those different parts of data are assigned.
Student Notebook
Sources of input: Pull and external

• Parse Pull
– Reads from data stack first
– If stack is empty, reads from keyboard
– Pull is shorthand for Parse Upper Pull
elem 1
elem 2
Parse Pull var1
elem 3
• Parse External
– Bypasses the data stack
– Reads directly from the keyboard
elem 1
elem 2
elem 3
Parse External var1
Figure 9-3. Sources of input: Pull and external ES52G5.0
Notes:
Parse Pull and Parse External have already been discussed, so this should be review for most
students.
Parse Pull first looks to the data stack for a line of input. If there are records in the stack, the first
line is retrieved from the stack as input to Parse Pull. If the stack is empty, then Parse Pull reads
from the terminal keyboard. Remember that the Pull instruction by itself is a shorthand form of
Parse Upper Pull.
Parse External always reads directly from the terminal keyboard. If there are records in the data
stack, they will be bypassed. This gives the REXX program the ability to prompt the user to type
information at the keyboard even when there are records still in the stack. There is no shorthand
form for Parse External, so to translate the data to uppercase, you must code Parse Upper
External.
V10.1
Student Notebook
Uempty
Sources of input: Arg

• Parse Arg reads from the "command line buffer"
– Buffer content never destroyed
– Can be parsed over and over
– Same for command line, functions, subroutines
– Arg is shorthand for Parse Upper Arg
READY
%myrexx 24 72 my.data Buffer
24 72 my.data
/* Rexx exec myrexx */
Parse Arg var1 var2 var3
Parse Arg allinput
Parse Arg arg1 arg23
Figure 9-4. Sources of input: Arg ES52G5.0
Notes:
You should already be familiar with the Parse Arg instruction as well, as it has been covered earlier
in the course, just as Parse Pull and Parse External have.
Arguments that are passed to the exec from the command line when the exec is invoked, or are
passed to a function or a subroutine, are placed in a buffer in memory. This buffer is read by the
Parse Arg instruction.
The data in the buffer is never destroyed (unlike the data stack, for example), so the programmer
may issue Parse Arg whenever, wherever, and as often as wanted, to parse and re-parse the same
input data over and over again. This allows the input data to be parsed in many different ways.
Remember that the Arg instruction by itself is a shorthand form of the Parse Upper Arg instruction.
Student Notebook
Sources of input: Version and numeric

• Parse Version returns the current version of Rexx
– First word is the language name, REXX370
– Second word is language level, like 3.48
– Remainder is language processor release date, like 01 May 1992
/* Rexx Version */
Parse Version vers
REXX370 3.48 01 May 1992
Say vers
• Parse Numeric returns the current Numeric settings

– First word is the numeric digits setting, default is 9
– Second word is the numeric fuzz setting, default is 0
– Third word is numeric form setting, default is SCIENTIFIC
/* Rexx Numeric */
Parse Numeric vers
9 0 SCIENTIFIC
Say vers
Figure 9-5. Sources of input: Version and numeric ES52G5.0
Notes:
The Parse Version instruction returns a predefined string of data describing the version of REXX
that you are running on your system. The words returned are the name of the interpreter, the
version and level number, and the date on which the language processor was released.
The Parse Numeric instruction also returns a predefined string of data. It returns the current REXX
numeric settings in your exec, as defined by default or by the Numeric instruction. The first word
returned is the numeric digits setting, which is 9 by default. This is the maximum number of digits
REXX will return when calculating the result of an arithmetic expression. The second word is the
numeric fuzz setting. This is the number of digits which may be ignored during a numeric
comparison. The default is zero (0), which means no digits may be ignored. The third word is the
numeric form setting, which indicates the form of exponential notation REXX will use when
calculating very large or very small numbers. The default value is SCIENTIFIC, which means that
only one non-zero digit may appear before the decimal point.
V10.1
Student Notebook
Uempty
Sources of input: Source

Parse Source returns nine tokens of information:
1. First word is always TSO.
2. Second word is COMMAND, FUNCTION, or SUBROUTINE.
3. Third word is the name of the exec.
4. Fourth word is the ddname to which exec is allocated.
5. Fifth word is the data set name containing the exec.
6. Sixth word is the name of the exec as it was invoked.
7. Seventh word is the initial host command environment (TSO or MVS).
8. Eighth word is the address space name (MVS, TSO/E, or ISPF).
9. Ninth word is the PARSETOK field in the PARMBLOCK control block.
/* Rexx Source Example */

Parse Source srce
Say srce
TSO COMMAND RXSRCE SYSEXEC ? ? TSO TSO/E ?
Figure 9-6. Sources of input: Source ES52G5.0
Notes:
Like Parse Version and Parse Numeric, Parse Source also returns a predefined string of data, but
at least some of this data will be different for each different REXX program that you execute. In
TSO/E, Parse Source always returns nine words of information, as shown in the visual above.
Other platform implementations of REXX will return different amounts of information (for example,
in z/VM, Parse Source returns seven words of data).
By far, the most important piece of data returned by Parse Source is the second word. This word,
which is either COMMAND, FUNCTION, or SUBROUTINE, indicates how this REXX program was
invoked. Based upon this information, your REXX exec can take different processing paths, or be
programmed to react in different ways.
Student Notebook
Sources of input: Var and value

• Parse Var parses one variable name (following the keyword
Var) into the variable template:
/* Rexx Parse Var example */
invar = 'This is the data.'
Parse Var invar var1 var2 var3 var4
Input
Variable Template
Variable
• Parse Value parses a REXX expression into the variable

template:
– Must include keyword 'With'
/* Rexx Parse Value example */
invar = 'This is some more data.'
Parse Value Subword(indata,1,4) With var1 var2 var3 var4
Input Variable Template

Expression With
Keyword
Figure 9-7. Sources of input: Var and value ES52G5.0
Notes:
Parse Var was used in one of the Rexxtry labs earlier in the course. It parses the content of a single
variable (the variable name following Parse Var) into a new variable template. This is actually quite
common in REXX, particularly when you do not know how many words of input data you have to
process. Consider the following code fragment:
Do i = 1 To Words(input)
Parse Var input word.i input
End i
This loop parses the content of the variable input, word by word, into separate variables, word.1,
word.2, and so forth, for as many words as input contains. For each iteration through the loop, the
first word of input is stored in word.i, then the rest of the data is placed back into the variable
input.
Parse Value works a bit like Parse Var, except for one big difference. Parse Var only allows you to
parse the content of one single REXX variable, but Parse Value allows you to parse the content of
an entire REXX expression. As the REXX expression to be parsed may contain several variable
names, the keyword “With” is required as a separator between the expression to be parsed and
the variable template. Parse Value is the only Parse instruction which requires this keyword.
V10.1
Student Notebook
Uempty
Parsing templates
• You can parse an input string
– By word (blank delimited text)
– By matching literal string
– By absolute column number
– By relative column number
– By matching variable value
Parse Pull v1 =10 v2 +6 v3 ':' v4 v5 (delim) v6

Absolute Relative
Matching Matching
column column
literal variable
number number
string value
Word
by
word
Figure 9-8. Parsing templates ES52G5.0
Notes:
So far this week we have done only one type of parsing, that being word by word parsing. There are
many other possibilities that we can use to parse data, as shown on the visual above. This is what
we will discuss over the rest of this unit.
The example in the visual also shows that you may mix any of these different parsing techniques in
one template.
Student Notebook
Parsing templates: Word by word

• "Word" means blank delimited text
• One word per variable
– Last variable gets all remaining words
– Variables left over after assigning all data are assigned null values
• What we have been doing all week!
Word
/* Rexx word parsing example */ by
input = 'I love New Orleans.' word
Parse Var input who emote city
Say who
Say emote I
Say city love
New Orleans.
Figure 9-9. Parsing templates: Word by word ES52G5.0
Notes:
In REXX, the term “word” means blank delimited text. When we parse data on a word by word
basis, the blanks between words in the input string become the delimiters for the data we assign to
variables. Leading and trailing blanks between words are removed, and one word is assigned to
each variable in the template, until we reach the last variable in the template. The last variable is a
special case, in that it will be assigned with all remaining data in the input string, including leading
and trailing blanks.
On the other hand, if we run out of input data before we exhaust the list of variables in the template,
then all of the variables left over in the template are assigned the null value.
None of this should come as a surprise to anyone at this point in the course, as it is what we’ve
been doing all week.
V10.1
Student Notebook
Uempty
Period place holder

• To ignore some of the input data, you could code a "dummy"
variable:
Parse Pull var1 var2 dummy var3
Parse Arg var1 var2 dummy var3
• Rather than waste a variable name, code the "parsing place
holder" in the variable template, a period in place of a variable
name:
Parse Pull var1 var2 . var3
Parse Arg var1 var2 . var3
• The period must be blank delimited.
• Data that would have been assigned to a variable in that
position is ignored.
Figure 9-10. Period place holder ES52G5.0
Notes:
Let’s assume that several words of information are being passed to a Parse instruction. Let’s also
assume that we do not care about one or more of these words. How can we ignore part of the input
data, and parse the rest of the input data?
One thing we could do is code a dummy variable to accept the word that we are not interested in,
then just don’t use that variable in the rest of the exec. That method would work, but it does waste a
variable name, and causes REXX to go through some unnecessary overhead.
Instead, the “Parsing Placeholder” can be used. Coding a blank-delimited period (.) in place of a
variable name in a variable template causes the Parse instruction to ignore any data that would
have been assigned to a variable in that position.
What would happen if the following instruction were to appear in a REXX exec?
Parse Pull var1 var2 .
Student Notebook
Parsing templates: Matching literal pattern

• Quoted literal string in template matched in input string
– Data before matching literal in input string is assigned to variable(s)
before literal in template
– Data following matching literal in input string is assigned to variable(s)
following literal in template
– If matching literal is not found, REXX assumes a match at
Length(input) + 1
Matching
/* Rexx literal parsing example */
literal
input = 'John, Paul, George, Ringo'
string
Parse Var input name1 ',' name2 ',' name3 ',' name4
Say name1
Say name2 John
Say name3 Paul
Say name4 George
Ringo
Figure 9-11. Parsing templates: Matching literal pattern ES52G5.0
Notes:
Instead of using the blanks between words as the delimiters for assigning data to variables, you
may code your own delimiters. Simply include a literal character string (enclosed within quotes, of
course) in the template. REXX scans the variable template, scans the input string, and matches the
literal patterns in the template with matching literals in the input string. REXX then assigns the
variables between the quoted literals in the template with the data between the matching literals in
the input string. The literals themselves are not assigned.
In the example in the visual, the input string contains three commas. The template in the Parse Var
instruction also contains three commas in quotes. REXX lines up the commas in the template with
the commas in the input string, then assigns the variables to the data between those matching
points. So, the variable name1 is assigned the value ‘John’, name2 is assigned the value ‘Paul’,
and so on. Notice that the spaces between the words now become significant characters that are
assigned to the variable names themselves.
If a literal pattern in the template is not found in the input string, REXX assumes that pattern is
matched at the next character past the end of the string (length of string plus one character).
V10.1
Student Notebook
Uempty
Another literal pattern example

/* Rexx literal parsing example */
input = 'John Rodgers:Paul Thomas:George Smith:Ringo Jones'
Parse Var input name1 ':' name2 ':' name3 ';' name4
Say name1
Say name2
Say name3
Say name4
John Rodgers
Paul Thomas
George Smith:Ringo Jones
Matching
literal
string
Figure 9-12. Another literal pattern example ES52G5.0
Notes:
In the example on the visual above there are colon characters (:) appearing between each of the
names in the input string. The variable template contains matching literal colon characters, but the
last literal is a semicolon (;), not a colon. This is a common typographical error a programmer may
make, as these two characters typically appear on the same key on the keyboard.
When REXX scans the input string and the parsing template, it will match the colon characters
appropriately. But as there is no semicolon in the input string, REXX assumes a match for that
characters at one character past the end of the input string. This causes REXX to assign all of the
remaining data (the last two names as well as the colon between them) to the variable name3,
leaving nothing to assign to name4. The variable name4, then, is assigned a null value.
Student Notebook
Parsing templates: Absolute column number

• Data assigned to variable:
– Begins at column position before variable name
– Up to but not including column position following variable name
• Column number is preceded by equal sign (=) or is unsigned
/* |...+....1....+....2....+....3....+....4 */
input = 'Germany 81M 138K Frankfurt '
Parse Var input =1 ctry =11 pop =17 area =24 cap =40
Say "'" || ctry || "'"
Say "'" || pop || "'" 'Germany '
Say "'" || area || "'" '81M '
Say "'" || cap || "'" '138K '
'Frankfurt '
Absolute
column
Note the trailing blanks
number
Figure 9-13. Parsing templates: Absolute column number ES52G5.0
Notes:
Column numbers may be included in a variable template. If a column number is preceded by an
equal sign (=), or if a column number is not signed at all (no equal, plus, nor minus sign), then it is
considered to be an absolute column number within the input string.
REXX sets a starting position with the column number appearing before the variable name, and a
matching position with the column number following the variable name. REXX then assigns the
variable with the value starting in the starting position, and going up to, but not including, the value
in the matching position. The first variable in the template defaults to a starting position of column
one if no column number precedes that variable name.
V10.1
Student Notebook
Uempty
Another absolute column example

• When column number following variable is lower than column
number before variable, variable is assigned with remainder of
string, then back up to lower column number to assign next
variable:
|...+....1....+....2....+....3....+....4
input = 'We have met the enemy, and he is us.'
Parse Var input var1 9 var2 12 var3 23 var4 4 var5 16
var1 = 'We have ' Absolute

var2 = 'met' column
var3 = ' the enemy,' number
var4 = ' and he is us.'
var5 = 'have met the'
Figure 9-14. Another absolute column example ES52G5.0
Notes:
In the example above, the variable var1 is assigned columns 1 through 8 from the input string,
var2 is assigned columns 9 through 11, and var3 is assigned columns 12 through 22.
The value following var4 is 4, which is a lower value than the 23 before var4. So var4 is assigned
from column 23 through the end of the string, then we back up to column 4 to begin assigning
var5, from column 4 through column 15.
Student Notebook
Another useful example

• User can type parameters in any order:
myalloc fi(mydd) da(my.data) lrecl(80)...
• MYALLOC exec can parse input like this:

Parse Upper Arg 1 'DA(' indsn ')' ,
1 'LRECL(' reclen ')' ,
1 'FI(' indd ')',
...
• Missing arguments can be checked and assigned defaults:

If reclen = '' Then reclen = 80
...
Figure 9-15. Another useful example ES52G5.0
Notes:
Consider a command like ALLOCATE, which has many optional keyword operands and parameters.
These operands may be typed in any order, and only the operands that are needed are the ones
the user types. How could one write a REXX exec that would accept arguments such as this? The
visual shows such an example.
The example Parse instruction included here uses operands from the ALLOCATE command, but of
course it would work for any set of operands.
V10.1
Student Notebook
Uempty
Parsing templates: Relative column

• Signed number is relative column number; relative value is
added to last matching position
• Can think of this as "number of characters" to assign to
variable
|...+....1....+....2....+....3....+....4
Parse Var input var1 +8 var2 +3 var3 +11 var4
Relative
var1 = 'We have '
var2 = 'met' column
Figure 9-16. Parsing templates: Relative column ES52G5.0
Notes:
A number preceded by an equal sign (=) or an unsigned number in a parsing template represents
an absolute column number in the string being parsed. A number preceded by a plus (+) or minus
(-) sign represents a relative column number. This number is added to the previous matching point
in the input string to determine the next matching point. REXX assigns the variable beginning at the
previous matching point (the starting point for that variable) up to, but not including, the next
matching point. One could also think of this as the number of columns of data to assign to the
variable.
In the example on the visual above, the variable var1 is assigned beginning at column 1, up to but
not including column 9 (or, for a length of 8 columns). Column 9 is the matching point for the
assignment of var1, and is also the starting point for the variable var2. The variable var2 is
assigned beginning at that point, column 9, up to but not including column 12 (or, for a length of 3
columns). This makes column 12 the matching point for var2, and the starting point for assigning
var3. That variable, var3, is then assigned with the next 11 columns beginning at column 12
(columns 12 through 22). The next variable, var4, is assigned starting from column 23 through the
end of the string.
Student Notebook
Another relative column example

• Signed column number may be positive or negative
• Negative column number much like lower absolute column
number
|...+....1....+....2....+....3....+....4
Parse Var input var1 +8 var2 +3 var3 +11 var4 -19 var5 +12
var1 = 'We have ' Relative

var2 = 'met' column
var5 = 'have met the'
Figure 9-17. Another relative column example ES52G5.0
Notes:
A negative value in a relative column number following a variable name is treated in much the same
way as a lower absolute column number following a variable name than that preceding the variable
name.
In the example, var1 is assigned beginning at column 1 for a length of 8 columns, var2 is
assigned beginning at column 9 for a length of 3 columns, and var3 is assigned beginning at
column 12 for a length of 11 columns. This places the matching point after var3 at column 23.
The value following var4 is negative, so it represents a lower value than the value before var4.
This means that var4 is assigned beginning at column 23 through the rest of the string. The
starting point for var5 is then 19 columns before column 23 (in other words, column 4). The
variable var5, then, is assigned for the next 12 columns beginning at column 4 (in other words,
columns 4 through 15).
V10.1
Student Notebook
Uempty
Parsing templates: Matching variable value

• A variable's value may be used as a matching pattern.
• The matching variable must be enclosed in parentheses.
delim = '/'
Parse Value Date('U') With month (delim) date (delim) year
• But there is one small catch, though:
/* |...+....1....+....2....+....3....+ */
input = "France 58M 211K Paris"
dlm = 29
Parse Var input (dlm) capital
Say "The capital of France is:" capital || "."
Matching
The capital of France is: . variable
value
Figure 9-18. Parsing templates: Matching variable value ES52G5.0
Notes:
The value of a variable may be used as a matching pattern in a variable template. The variable
whose value is to be matched must be enclosed within parentheses, to distinguish it from variables
to be assigned with values from the input string. REXX will use the value of this variable just as
though a quoted literal were used in the template.
In the example in the visual above, the variable delim is assigned with a single forward slash (/).
The Parse Value instruction will parse the value returned by the Date(‘U’) function. This is the US
date format, in the form mm/dd/yy. The Parse instruction uses the value of the delim variable as
the separator to assign the variables month, date, and year.
Student Notebook
Another matching variable example

• The matching variable value may come from the input string.
• Input data set allocated to ddname INDD:
:Ty Cobb:.367:118:4191:357:1961:
&Hank Aaron&.364&755&3771&1383&2297&
/Rogers Hornsby/.358/301/2930/679/1584/
$Tris Speaker$.345$117$3514$220$1559$
;Babe Ruth;.342;714;2873;1330;2211; Matching
!Willie Mays!.302!660!3283!1526!1903! variable
• Parse example: value
'EXECIO * DISKR INDD (STEM rec.'
Do i = 1 To rec.0
Parse Var rec.i 1 dlm 2 name (dlm)
name = Space(name,0)
Upper name
Parse Var rec.i 2 (dlm) ba.name (dlm) ,
hr.name (dlm) hits.name (dlm) ,
so.name (dlm) rbi.name (dlm)
End i
...
Figure 9-19. Another matching variable example ES52G5.0
Notes:
The example in the visual shows several records in a data set allocated to the ddname INDD. The
first character of each record is the delimiter character being used throughout the rest of the record
to separate the pertinent data. The EXECIO command reads these records into a series of
compound variables, rec.1, rec.2, and so forth. Remember that EXECIO also assigns rec.0
with the number of records that were read.
The Parse Var instruction in the loop parses each record in turn. It assigns the first character in the
record to the variable dlm. Then it uses that value as the matching pattern to separate out the
values to assign to each of the rest of the variables. The next variable, name, is assigned with the
name of the baseball player in each record. That variable is then used as the tail for the compound
variables through the rest of the parse instruction, assigning the player’s batting average, home
runs, hits, strikeouts, and runs batted in, respectively.
Notice that there is a space in the player’s name, which is assigned as the tail of these compound
variables. Also, when assigning literals as the tail of a compound variable, they are case sensitive
when searching for them. This is why the next two instructions in the example remove the space
and uppercase the value of the variable name, so that we can search for a single character string
without regard to case or spaces.
V10.1
Student Notebook
Uempty
One special exception

z When combining matching literal strings and relative column numbers:
– With matching literal string before variable name, and relative position
following variable name
– Matching literal string is not skipped, but is assigned to variable
input = 'REstructured eXtended eXecutor'
Parse Var input 1 var1 3 'X' var2 +1 'X' var3 +1
Say var1 || var2 || var3
Matching Relative
variable column
REXX
value number
Figure 9-20. One special exception ES52G5.0
Notes:
We have seen that when using quoted literal strings in parsing templates as matching patterns, that
literal string is not assigned to any variable. There is a special exception to this rule, though. If a
quoted literal appears before a variable name in a template, and a relative column number (a
signed number) appears after the variable name, then the variable is assigned starting at the
beginning of the matching literal string. This means that the matching literal is indeed assigned to
the variable.
The example in the visual above illustrates this special exception. The variable var1 is assigned
with the first two characters of the input string, ‘RE’. Following the absolute column number 3 we
see a literal uppercase ‘X’. This moves us to the first ‘X’ in the input string to begin assigning the
next variable. Following the variable var2 is a relative column number, +1. This causes the ‘X’ in
“eXtended” to be assigned to var2. Similarly, the next ‘X’ in “eXecutor” is assigned to the variable
var3.
Student Notebook
Checkpoint (1 of 3)
1. Which source of input to the parse instruction requires the
keyword “With”?
2. True or False: The Arg instruction is shorthand for Parse Arg.
3. True or False: The Var instruction is shorthand for Parse

Upper Var.
4. How can I find out how my REXX program was invoked?
Notes:
V10.1
Student Notebook
Uempty
Checkpoint (2 of 3)
5. What will be assigned to each variable in the following code
fragment?
input = 'This is the data.'
Parse Var input 6 var1 var2 ' d'
var1 = (blank)
var2 = (blank)

fragment?
Parse Var input var1 'is' var2 . 13 var3 +4
var1 = (blank)
var2 = (blank)
var3 = (blank)
Notes:
Student Notebook
Checkpoint (3 of 3)
fragment?
Parse Var input var1 var2 var3 8 . 'a' var4 '.' -4 ,
var5 +2
var1 = (blank)
var2 = (blank)
var3 = (blank)
var4 = (blank)
var5 = (blank)
Notes:
V10.1
Student Notebook
Uempty
Unit summary
Notes:
Student Notebook
V10.1
Student Notebook
Uempty
Unit 10. Using REXX: REXX compiler, REXX in
batch, MVS console commands

This unit discusses three topics that were too short to comprise their own
units, so they were gathered into one unit here. The REXX compiler is
discussed first, including how to compile REXX execs into compiled exec
code both interactively and in batch, some compiler options, and some
compiler control directives. Then there is a discussion of running REXX
execs in batch jobs, using either IKJEFTxx (where xx is 01, 1A or 1B, all of
which are TSO/E in batch programs) or IRXJCL (REXX in batch). Finally
there is a discussion about executing z/OS MVS operator console
commands from within a REXX exec.

• Compile REXX execs
• Run REXX in batch jobs
• Execute MVS console commands in a REXX exec

Accountability:
• Exercises
References
SH19-8179 IBM Compiler and Library for REXX on System z:
Diagnosis Guide
SH19-8160 IBM Compiler and Library for REXX on System z: User's
Guide and Reference
ISPF Services Guide
- z/OS V1, SC19-3626
© Copyright IBM Corp. 1999, 2016 Unit 10. Using REXX: REXX compiler, REXX in batch, MVS console 10-1
Student Notebook
- z/OS V2, SC34-4819

ISPF Dialog Developer’s Guide and Reference
- z/OS V1, SC19-3619
- z/OS V2, SC34-4821
ISPF Edit and Edit Macros
- z/OS V1, SC19-3621
- z/OS V2, SC28-1312
SA22-7806 Using REXX and z/OS UNIX System Services
SA22-7670 SDSF Operation and Customization
SC19-4051 DB2 Application Programming and SQL Guide
SA22-7594 MVS IPCS Commands
SA22-7605 MVS Programming Authorized Assembler Services Guide
SA22-7682 Security Server RACF Macros and Interfaces
V10.1
Student Notebook
Uempty
Unit objectives
Notes:
Student Notebook
The REXX products

• IBM Compiler for REXX on zSeries Release 4
– z/VM, z/OS: product number 5695-013
• IBM Library for REXX on zSeries Release 4
– z/VM, z/OS: product number 5695-014
• z/VSE
– Part of operating system
• IBM Alternate Library for REXX on zSeries Release 4
– Included in z/OS base operating system
– Free download for z/VM (and z/OS)
• http://www.ibm.com/software/awdtools/rexx/rexxzseries/altlibrary.html
• REXX Interpreter
– Included in all z/OS and z/VM releases
Figure 10-2. The REXX products ES52G5.0
Notes:
The REXX library is required to run compiled programs
Compiled REXX is not an LE Language
Compiled with run one of two ways
Run-Time Library: Purchased Program Product
REXX Alternate: Installed on z/OS
Will use the native systems REXX interpreter
Compiled REXX will use whichever library is available at execution time
Compiled code runs in 31-bit mode
Uses old opcodes such as BALR. Can run on old hardware
No z/Architecture in plan today.
V10.1
Student Notebook
Uempty
REXX interpreter and libraries

• The Interpreter executes (interprets) REXX code “line by
line”
– Included in all z/OS and z/VM releases
• A REXX library is required to execute compiled programs
– Compiled REXX is not an LE language
• Two REXX library choices:
– (Runtime) Library - a priced IBM product
– Alternate library - a free IBM download
• Uses the native system’s REXX interpreter
• At execution, compiled REXX will use whichever library is
available:
– (Runtime) Library
– Alternate Library
Figure 10-3. REXX interpreter and libraries ES52G5.0
Notes:
IBM Compiler and Library for REXX on zSeries V1R4 User's Guide and Reference
SH19-8160-05
IBM Compiler for REXX on zSeries Release 4
• VM, MVS: PID 5695-013
IBM Run Time Library for REXX on zSeries Release 4
• VM, MVS: PID 5695-014
IBM Alternate Library for REXX on zSeries Release 4
• Free download
http://www-306.ibm.com/software/awdtools/rexx/rexxzseries/altlibrary.html
• Included in z/OS 1.9 base operating system
Continued ongoing support for Release 4
• Release 4 has been available since 2003
Student Notebook
Primary and Alternate libraries

• The Alternate Library is necessary for:
– Customers who want to run compiled REXX programs, but do not
have the Library installed
– Software developers who want to make their programs available to
users who do not have the Library installed
• By enabling their programs to run with both the Library and the
Alternate Library, software developers give their customers the
following possibilities:
– Use the Alternate Library provided with the application, if they have no
library installed.
– Use the IBM Library for REXX on zSeries, if it is installed.
• Use the SLINE and ALT options to enable a compiled program to run
also with the Alternate Library. Use the CONDENSE option to hide the
source lines.
• Will run whichever library is loaded in memory
– Alternate library execution requires ALT and SLINE
Figure 10-4. Primary and Alternate libraries ES52G5.0
Notes:
There is a loosely coupled software prerequisite when compiled REXX code is to be processed;
IBM Library for REXX on zSeries Alternate Library (5695014/HWJ9143) will automatically be
included on z/OS ServerPacs, should the installation not be licensed for IBM Library for REXX on
zSeries (5695014/HWJ9140).
This Alternate Library is entitled and provides a basic runtime processor capable of interpreting
compiled REXX execs.
Its inclusion is necessary as some IBM REXX code is shipped only in compiled format.
V10.1
Student Notebook
Uempty
REXX compiler
• Two components:
– Compiler for REXX on zSeries, 5695-013
– Library for REXX on zSeries, 5695-014
• Output can be compiled exec (CEXEC) code or object code
• Improved performance
– Compiled code runs faster than interpreted code
• Improved reliability
– Syntax check of all source code at compile time
• Source code can be hidden from users
• Manual: IBM Compiler and Library for REXX on zSeries User's
Guide and Reference: SH19-8160
Figure 10-5. REXX compiler ES52G5.0
Notes:
IBM offers a REXX compiler (and library) as an alternative to the REXX interpreter. While the
interpreter is supplied with TSO/E (and indeed all of IBM’s other platforms as well), the compiler
and library are extra cost optional features. The interpreter is more suitable than a compiler for
program development, but the compiler can provide benefits in performance, reliability, and
security.
A compiler scans an entire program for such errors as incorrect instructions and variable names,
even in parts of a program that are not used when the program is run. By contrast, an interpreter
stops as soon as it detects an error. It does not detect syntax errors in parts of a program that are
not executed during a particular invocation.
The compiler will create either compiled exec (also called CEXEC) code, object code which may be
link-edited into a load module, or both. The REXX compiler also provides, as most compilers do, a
listing file, which is the human readable description of what the compiler did with the program. The
listing file may include diagnostic information, as well as a cross reference listing.
Student Notebook
Compiler Advantages
• Why use the REXX compiler?
– Source Code Protection
• Protects your intellectual property
• Protects your code from manipulation
• Keeps your code maintainable
– Meet IBM packaging rules to include a copyright in the load
– Program performance
• Approximately 30% performance gain unless you are using the REXX
Alternate library
– Compiler syntax checks the code without the need for execution
• Lists all errors, rather than stopping at the first error when run
interactively
Figure 10-6. Compiler Advantages ES52G5.0
Notes:
Compiler control directives
- %include, %page, %copyright, %stub, %sysdate, %systime, %testhalt
Source Code Protection
- Protects your intellectual property
- Protects your code from manipulation
- Keeps your code maintainable
- Source code not in deliverables
Performance enhancement
Improved Productivity and Quality
- Debugging: cross reference listing
- Syntax check of all statements
- Syntax check without code execution
V10.1
Student Notebook
Uempty - Compile time code checks

- Compiler error messages
- Lists all errors – no stopping at first error
- Source and cross reference listings
User’s Guide and Reference: http://publibfi.boulder.ibm.com/epubs/pdf/h1981605.pdf
Student Notebook
Compiler output
• Compiler options for code output:
– CEXEC: Compiled exec code
– OBJECT: Object code, can be link-edited into load modules
– DLINK: Includes external references in object code for subroutines,
external function calls
– CONDENSE: Creates "packed" CEXEC or object code
• Loads faster, runs slower (code must be uncondensed in storage)
• Mutually exclusive with DLINK and TRACE
• Compiler options for listing output:
– PRINT: Default - create listing output
– XREF: Include cross reference listing in listing output
– SOURCE: Default - include source code in listing output
Figure 10-7. Compiler output ES52G5.0
Notes:
The REXX compiler can produce compiled code that is not in the form of object code nor load
modules. This code is called CEXEC and is immediately available for execution. The compiler will,
by default, create the CEXEC data set for you. You should allocate this data set to the //SYSEXEC
ddname, ahead of the source library in the concatenation, otherwise you will execute the
interpreted version of the program.
The OBJECT option tells the compiler to create object code, which can be processed by the binder
or linkage editor. It may be link-edited with code from other languages when creating load modules.
The DLINK option allows you to satisfy external references during the link-edit step, thus helping to
avoid searching during program execution.
The CONDENSE option “packs” or “condenses” the CEXEC or object code into a smaller space.
This means that the code will load faster, as there is less data to actually load into memory, but it
will run a little slower, as it must by uncondensed before it can be used (this is automatic).
V10.1
Student Notebook
Uempty
Cross reference listing

• Includes:
– Variables
• Simple variables, stems and compound variables
– Labels
– Constants (literals and numbers)
– Built-in functions
– External routines
– Host commands
– Optimizing stoppers
– Source code listing (unless NOSOURCE option is specified)
• Can specify XREF(SHORT) to exclude
– Constants
– Commands
– Optimizing stoppers
Figure 10-8. Cross reference listing ES52G5.0
Notes:
The Cross Reference Listing can be very useful because it breaks out and lists many of the different
items used in the program. Simple REXX variables are listed, as are compound variables and
stems. Constant values, like numbers and literals, are also listed separately. All REXX built-in
functions, external functions and subroutines, and any host commands are listed.
The REXX compiler is an optimizing compiler. Any program code that would prevent the compiler
from optimizing the executable code is listed in a separate section of the Cross Reference Listing.
Unless you specify the NOSOURCE option, a source code listing of the program is also included
The XREF option allows you to specify a sub-option of SHORT in parentheses. This sub-option
shortens the Cross Reference Listing by omitting all constants, host commands, and code that
would prevent optimization.
Student Notebook
Compiler listings
===> Compilation Summary TSOCH50.REXXLIB(SAYHELO1)
IBM Compiler for REXX on zSeries 4.0 LVL PK04822 Time: 09:51:50 Date:
Compilation successful
Compiler Options
NOALTERNATE
CEXEC (TSOCH50.REXCEXEC(SAYHELO1)) RECFM=FB,LRECL=80,BL
NOCOMPILE (S)
NOCONDENSE
NODDNAMES
NOIEXEC
LIBLEVEL (*)
LINECOUNT (55)
MARGINS (1 *)
OBJECT (TSOCH50.REXXOBJ(SAYHELO1)) RECFM=FB,LRECL=80,BL
OPTIMIZE
PRINT () RECFM=VBA,LRECL=125,
SYSIN (TSOCH50.REXXLIB(SAYHELO1)) RECFM=FB,LRECL=80,BL
NOTERMINAL
NOTESTHALT
NOTRACE
XREF
Minimum Library Level required: 3
===> Source Listing TSOCH50.REXXLIB(SAYHELO1)
If Do Sel Line C ----+----1----+----2----+----3----+----4----+----5----+----6
1 /* REXX */
2 Trace Off
3 Address 'TSO'
4 Say " "
5 Say "+------------------------+"
6 Say '| hello' userid() '! |'
7 Say '| hello' SYSVAR(SYSUID) '! |'
8 Say "+------------------------+"
9 Say " "
10 Exit
===> Cross Reference Listing TSOCH50.REXXLIB(SAYHELO1)
Item Attribute Line References
----- Labels, Built-in Functions, External Routines -----
SYSVAR SYSTM RTN 7(f)

USERID BUILT-IN 6(f)
----- Constants -----

Figure 10-9. Compiler listings ES52G5.0
Notes:
The Compiler produces a listing for each compilation unless the NOPRINT option was specified.
You can print the listing or store it in a z/OS data set
• The compiler listing consists of the following items:
- The compilation summary
- The source listing, if the SOURCE option was specified
- Any messages that were produced and that were not suppressed by the FLAG option
- A cross-reference listing, if the XREF option was specified
- The compilation statistics
V10.1
Student Notebook
Uempty
Methods of compiling
• Online by command: REXXC exec
– From ISPF 3.4 member listing
– From command line:
REXXC 'MY.REXX.EXEC(MYPGM)' XREF
Include
• ISPF panels Compiler
cross
reference
– Foreground or background program in listing Data set
containing
• Batch job: REXXCOMP program REXXCOMP
//COMPILE EXEC PGM=REXXCOMP,PARM=XREF

Input source code
//STEPLIB DD DSN=xxx.SFANLMD,DISP=SHR
//SYSIN DD DSN=MY.REXX.EXEC(MYPGM),DISP=SHR
//SYSCEXEC DD DSN=xxx.xxx.CEXEC(MYPGM),DISP=SHR
//SYSPRINT DD SYSOUT=*
Compiler Compiled exec code
//SYSTERM DD SYSOUT=* listing
Severe
error
msgs
Figure 10-10. Methods of compiling ES52G5.0
Notes:
The compiler may be invoked interactively by using the REXXC exec, which is supplied with the
compiler. This exec may be run from the TSO/E READY prompt, from ISPF Option 6, or from the
ISPF 3.4 member listing panel. Other ISPF panels may be installed if your site wants to add a
REXX compiler option (to ISPF Option 4, for example).
The REXX compiler may also be invoked by using the REXXCOMP program, which may be run by
using the Address LINK instruction or in a batch job, as shown in the visual above. The various DD
statements and their uses are also shown above.
Student Notebook
Source to executable
//*************************************************************
//*** COMPILE REXX
//*************************************************************
// JCLLIB ORDER=TSOCH50.REXXJCL
//S1 EXEC REXXC,COMPDSN=REXX.SFANLMD
//REXX.SYSCEXEC DD DSN=TSOCH50.REXCEXEC(SAYHELO1),DISP=SHR
//REXX.SYSPUNCH DD DSN=TSOCH50.REXXOBJ(SAYHELO1),DISP=SHR
//REXX.SYSIN DD DSN=TSOCH50.REXXLIB(SAYHELO1),DISP=SHR
//REXXC PROC OPTIONS='XREF OBJECT', REXX Compiler options

// COMPDSN='#HLQREXX.SFANLMD' REXX Compiler load lib
//*-----------------------------------------------------------------
//* Compile REXX program.
//*-----------------------------------------------------------------
//*
//REXX EXEC PGM=REXXCOMP,PARM='&OPTIONS'
//STEPLIB DD DSN=&COMPDSN,DISP=SHR
//SYSTERM DD SYSOUT=*
//*SYSIEXEC DD DUMMY
//*SYSDUMP DD DUMMY
//SYSCEXEC DD DSN=&&CEXEC(GO),DISP=(MOD,PASS),UNIT=SYSALLDA,
// SPACE=(800,(800,100,1))
//SYSPUNCH DD DSN=&&OBJECT,DISP=(MOD,PASS),UNIT=SYSALLDA,
// SPACE=(800,(800,100))
Figure 10-11. Source to executable ES52G5.0
Notes:
V10.1
Student Notebook
Uempty
Compiler options
• ALTERNATE - marks the resulting • FORMAT - listing file options
binary as capable of being run with the • IEXEC - interpretable program
alternate library. • LIBLEVEL(6) - library level required
• CEXEC(filespec) - specifies the output • LINECOUNT(55) - listing file option
is a “compiled-exec” type of file. • MARGINS(1 *) - listing file option
• COMPILE - is output binary produced. • OBJECT(filespec) - binary output is
• CONDENSE - packs binary. Unpacked TEXT
at run time by the library. • OLDDATE - date/time other than
• DLINK - TEXT file contains external compiler time
references. • OPTIMIZE - debug compiler
• DUMP - used to debug compiler • PRINT(filespec) - listing file
• FLAG - minimum severity for • SLINE - includes source lines in binary
messages • SOURCE - listing file option
• TERMINAL - quiet/verbose compile
• TESTHALT - include code for HALT
trapping
• TRACE - program uses the TRACE
command
• XREF - listing file option
Figure 10-12. Compiler options ES52G5.0
Notes:
Student Notebook
Compiler NOCONDENSE option

//***********************************************************
//*** COMPILE REXX
//***********************************************************
//S1 EXEC REXXC,COMPDSN=REXX.SFANLMD,
// OPTIONS='XREF OBJECT SLINE ALT NOCOND'
//REXX.SYSCEXEC DD DSN=TSOCH50.REXCEXEC(SAYHELLO),DISP=SHR
//REXX.SYSPUNCH DD DSN=TSOCH50.REXXOBJ(SAYHELLO),DISP=SHR
//REXX.SYSIN DD DSN=TSOCH50.REXXLIB(SAYHELLO),DISP=SHR
Figure 10-13. Compiler NOCONDENSE option ES52G5.0
Notes:
V10.1
Student Notebook
Uempty
Compiler CONDENSE option

//********************************************************
//*** COMPILE REXX
//********************************************************
//S1 EXEC REXXC,COMPDSN=REXX.SFANLMD, OPTIONS='XREF OBJECT SLINE ALT COND'
//REXX.SYSCEXEC DD DSN=TSOCH50.REXCEXEC(SAYHELLO),DISP=SHR
//REXX.SYSPUNCH DD DSN=TSOCH50.REXXOBJ(SAYHELLO),DISP=SHR
//REXX.SYSIN DD DSN=TSOCH50.REXXLIB(SAYHELLO),DISP=SHR
Figure 10-14. Compiler CONDENSE option ES52G5.0
Notes:
Student Notebook
Compiler control directives

• /*%COPYRIGHT IBM Corp. 2006 */ • MVS (calling JCL EXEC PGM=)
• /*%INCLUDE member */ – ADDRESS LINKMVS or ADDRESS
ATTACHMVS
• /*%INCLUDE ddname(member) */
• MULTI (multi-purpose stub)
• /*%Page*/
– ADDRESS LINK or ADDRESS ATTACH
• /*%Stub stubname*/
– OBJECT option must be used with • /*%Sysdate*/
compile • /*%Systime*/
• CPPL (command processor
• /*%Testhalt*/
parameter list)
– Inserts the code to support the HALT
• EFPL (external function parameter
condition.
list)
• CPPLEFPL (CPPL and EFPL)
• CALLCMD (calling TSO/E command
line using TSO/E call command or
from another Rexx exec)
Figure 10-15. Compiler control directives ES52G5.0
Notes:
While the Compiler options are specified when the Compiler is invoked, the control directives are
defined within your program as part of the REXX code.
Valid control directives are:
%COPYRIGHT
%INCLUDE
%PAGE
%STUB
%SYSDATE
%SYSTIME
%TESTHALT
The Compiler supports control directives, which are contained in comments. The interpreter treats
them as normal comments.
V10.1
Student Notebook
Uempty
Control directives
/*%COPYRIGHT (c) 2016 IBM CORP. */
– Add copyright notice to CEXEC or object header
/*%INCLUDE PGM2 */
– Pull in other REXX members
/*%PAGE */
– Insert page break in listing
/*%TESTHALT */
– Insert code to process halt condition at specific locations
• Control Directives must be placed inside comments
• Control Directives are ignored by the interpreter
Figure 10-16. Control directives ES52G5.0
Notes:
The control directives that are supported by the REXX compiler are similar to features of some
other compiled languages. These control directives are not recognized by the interpreter, so they
must be placed inside comments so that the interpreter will ignore them. Indeed, if the control
directives are not coded immediately following the slash-asterisk (/*) comment characters (with no
spaces), both the interpreter and the compiler will cause errors to occur.
The %COPYRIGHT control directive allows you to include a copyright statement in the header of
the compiled code. The %INCLUDE directive causes other REXX data set members to be pulled in,
or included in, the program being compiled. The %PAGE directive causes a hard page break to
occur in the source code listing. The %TESTHALT directive causes the system to test for an
external attempt to halt the program at specific points in the code.
Student Notebook
%COPYRIGHT
• Added to code… /*%COPYRIGHT IBM 2016*/
/* REXX */
/*%COPYRIGHT IBM Corp. 2016 */
Trace Off
Address 'TSO'
Say " "
Say "+------------------------+"
Say '| hello' userid() '! |'
Figure 10-17. %COPYRIGHT ES52G5.0
Notes:
V10.1
Student Notebook
Uempty
The REXX Compiler - %STUB

• The %STUB compiler directive provides interfaces with various
parameter-passing conventions
– CALLCMD
• When the CALL program_name command is issued from the TSO/E command line, or when
the CALL program_name host command is issued from within an EXEC executing under
TSO/E.
• In simple terms, any “Main” program invoked by:
– SELECT CMD(program_name)
• First parm will be the module name
– CPPLEFPL
• It contains the logic to determine if the REXX program is being invoked as a TSO/E command
or as a REXX external routine. Once this has been determined, the compiled REXX program is
given control with the appropriate parameters.
• In simple terms, subroutines called using the CALL statement or invoked as a function call
• See IBM Compiler and Library for REXX on System z: User's Guide and
Reference
– http://www-
01.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.rexa100/toc.htm?lang=en
Figure 10-18. The REXX Compiler - %STUB ES52G5.0
Notes:
Student Notebook
Compiler versus interpreter differences

• Slight differences between compiled and interpreted code
• If using Sourceline() function, must use compiler option SLINE
• If using Trace instruction or Trace() function, must use compiler
options TRACE and SLINE
• Parse Version instruction can be used to detect whether code
is compiled or interpreted
– Returns "REXX370" if interpreted
– Returns "REXXC370" if compiled
• Performance testing:
– SYSVAR('SYSCPU')
– SYSVAR('SYSSRV')
Figure 10-19. Compiler versus interpreter differences ES52G5.0
Notes:
There are some things that must be considered when you are compiling REXX code versus when
you are interpreting REXX code. For instance, earlier in the course it was discussed that you could
place a Signal instruction in your REXX exec and not actually code the label to handle the error
condition that this could raise. The compiler will not let you get away with that, it insists that the label
be coded.
For performance reasons the Sourceline() and Trace() features are disabled by the compiler by
default. They can be enabled by including the compiler options SLINE and TRACE.
The Interpret instruction was, at one time, not supported by the compiler. It is now supported, but
the instruction that Interpret derives will not be checked for syntax, as this only occurs at execution
time.
The SYSVAR() function is a TSO/E REXX function. It is not available in all implementations of
REXX. It is documented in the TSO/E REXX Reference manual. It accepts over 30 different
possible values as its argument, and returns information based upon which argument is passed.
V10.1
Student Notebook
Uempty
How to tell interpreted versus compiled REXX

/* REXX */
parse VERSION v ; say v
Trace Off
Address 'TSO'
Say " "
Say "+------------------------+"
Say '| hello' userid() '! |'
REXXC370 3.48 23 Dec 1999
+------------------------+
| hello TSOCH50 ! |
+------------------------+
REXX370 3.48 01 May 1992
+------------------------+
| hello TSOCH50 ! |
+------------------------+
Figure 10-20. How to tell interpreted versus compiled REXX ES52G5.0
Notes:
PARSE VERSION returns information describing the language level and the date of the language
processor.
The PARSE instruction with the VERSION option returns five tokens:
The string REXXC370 (interpreters produce REXX370).
The language level description. The language level depends on the Operating System:
Under z/OS, under z/VM (releases earlier than VM/ESA Release 2.1), and under VSE/ESA, the
language level is 3.48.
Three tokens describing the release date of the Compiler that was used to generate the code (for
example, 27 Oct 1994).
The general format of the PARSE VERSION information is the same as that provided by the
interpreter, although the values of the tokens differ.
Student Notebook
Performance: String Processing

/* REXX */
Trace Off
N = time('E')
do I = 1 to 5000000
A = 'string'
N = I || A
end
say time('E')
ex 'TSOCH50.REXXLIB(TEST2)'
REXX370 3.48 01 May 1992
3.541518
***
ex 'TSOCH50.REXCEXEC(TEST2)'
REXXC370 3.48 23 Dec 1999
0.240308
***
Figure 10-21. Performance: String Processing ES52G5.0
Notes:
The performance improvements that you can expect when you run compiled REXX programs
depend on the type of program. A program that performs large numbers of arithmetic operations of
default precision shows the greatest improvement. A program that mainly issues commands to the
host shows limited improvement, because REXX cannot decrease the time taken by the host to
process the commands.
Program performance
Approximately 30% performance gain unless you are using the REXX Alternate library
V10.1
Student Notebook
Uempty
Performance: Arithmetic Operations

/* REXX */
Trace Off
N = time('E')
do I = 1 to 5000000
N = I * I
end
say time('E')
ex 'TSOCH50.REXXLIB(TEST3)'
REXX370 3.48 01 May 1992
5.726090
***
ex 'TSOCH50.REXCEXEC(TEST3)'
REXXC370 3.48 23 Dec 1999
0.311040
***
Figure 10-22. Performance: Arithmetic Operations ES52G5.0
Notes:
Program performance
Approximately 30% performance gain unless you are using the REXX Alternate library
Student Notebook
Performance
• Arithmetic operations 6 to 10 times faster

• String and word processing
• Constants and variables 4 to 6 times faster
• References to procedures and built-in
functions
• Changes to values and variables
• Assignments 2 to 4 times faster
• Reused compound variables
• Host commands Minimal improvement
• File I/O
Figure 10-23. Performance ES52G5.0
Notes:
Note: This is true only when:
The IBM Library for REXX on zSeries is used. With the Alternate Library, the performance of
compiled REXX programs is similar to that of interpreted programs.
The program has been compiled with the NOTRACE option.
V10.1
Student Notebook
Uempty
Live example (dataset allocation)
Figure 10-24. Live example (dataset allocation) ES52G5.0
Notes:
Student Notebook
Live example (JCL) (1 of 4)

//BUILD JOB (ACCOUNT),'ES52',CLASS=A,MSGCLASS=R,LINES=999999,
// NOTIFY=TSOCH50,MSGLEVEL=(1,1),REGION=4096K,TIME=1440
//*******************************************************************
//**
//**
//*******************************************************************
//** (1) COMPILE REXX PROGRAM
//** INPUT: REXX.SYSIN = REXX SOURCE CODE
//** REXX.STEPLIB = COMPILER LIBRARY (REXXC SFANLMD)
//** OUTPUT: REXX.SYSPUNCH = OBJECT OUTPUT
//** REXX.SYSCEXEC = CEXEC OUTPUT
//**
//*******************************************************************
//COMPILE EXEC REXXC,
// OPTIONS='XREF OBJECT NOSLINE'
//REXX.SYSIN DD DSN=TSOCH50.ES52V5.REXX(MORTG),DISP=SHR SOURCE
//REXX.STEPLIB DD DSN=REXX.SFANLMD,DISP=SHR COMPILER-LIB
//REXX.SYSPUNCH DD DSN=TSOCH50.ES52V5.OBJECT(MORT),DISP=SHR OBJECT
//REXX.SYSCEXEC DD DSN=TSOCH50.ES52V5.CEXEC(MORTG),DISP=SHR
//**
Figure 10-25. Live example (JCL) ES52G5.0
Notes:
V10.1
Student Notebook
Uempty

/*******************************************************************
//** (2) CREATE OBJECT DECK WITH MULTISTUB (EAGSTMP BY USING REXX
//** EXEC REXXL, ALIAS OF EAGCML)
//** INPUT: SYSIN = OUTPUT FROM COMPILER
//** SYSEXEC = LOCATION FOR REXXL (REXX SOURCE FOR BIND)
//** OUTPUT: SYSOUT = TEMPORARY OBJECT DECK (INPUT TO LINK)
//**
//*******************************************************************
//STUB EXEC PGM=IRXJCL,PARM='REXXL MULTI'
//SYSIN DD DSN=TSOCH50.ES52V5.OBJECT(MORTG),DISP=SHR OBJECT
//SYSEXEC DD DSN=REXX.SEAGCMD,DISP=SHR REXXL
//SYSOUT DD DSN=&&SYSPUNCH(GLFTEST), STUBBED-OBJ
// DISP=(NEW,PASS,DELETE),UNIT=SYSDA,SPACE=(TRK,(2,1,2)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=3120,DSORG=PO)
//SYSTSPRT DD SYSOUT=*
//**
Notes:
Student Notebook

//*******************************************************************
//** (3) LINK THE STUB WITH COMPILED REXX
//** INPUT: SYSLIN = (INPUT FROM STUB)
//** SYSLIB = LIBRARY FOR LINK/REXX
//** OUTPUT: SYSLMOD = RESULTING END PRODUCT MODULE
//**
//*******************************************************************
//LINK EXEC PGM=HEWL,PARM='LIST,AMODE=31,RMODE=ANY,RENT,MAP'
//SYSLIN DD DSN=&&SYSPUNCH(GLFTEST),DISP=(SHR,PASS) STUBBED-OBJ
//SYSLIB DD DSN=REXX.SEAGLMD,DISP=SHR LINK-LIB
//SYSLMOD DD DSN=TSOCH50.ES52V5.MODULE(MORTG),DISP=SHR MODULE
//SYSUT1 DD UNIT=SYSDA,SPACE=(1024,(200,20))
//**
Notes:
V10.1
Student Notebook
Uempty

//*******************************************************************
//** (4) RUN COMPILED STUB
//** INPUT: STEPLIB = LOCATION OF MODULE & RUN-TIME LIBRARY
//**
//*******************************************************************
//RUN EXEC PGM=MORTG,PARM='160000 6.375 30',REGION=512K
//STEPLIB DD DSN=TSOCH50.ES52V5.MODULE,DISP=SHR MODULE
// DD DSN=RXT.V140.SEAGLPA,DISP=SHR RT-LIB
//**
//**
//*******************************************************************
//** (5) RUN CEXEC
//** INPUT: STEPLIB = LOCATION OF RUN-TIME LIBRARY
//**
//*******************************************************************
//RUNCE EXEC PGM=IKJEFT01,REGION=4M
//STEPLIB DD DSN=RXT.V140.SEAGLPA,DISP=SHR RT-LIB
//SYSTRPRT DD SYSOUT=*
//SYSTSIN DD *
EX ‘TSOCH50.ES52V5.CEXEC(MORTG)’ ‘165000 6.25 30’
/*
//**
//**
//************************* END *************************************
Notes:
Student Notebook
Live example (REXX)
/* REXX */
PARSE VERSION v1; PARSE SOURCE v2; SAY v1 v2
ARG prin rate yrs
monthly = prin * (rate/1200) *
(1+1/(((1+rate/1200)**(12*yrs)-1)))
say "Monthly payment = $" || format(monthly,,2)
EXIT 0
Figure 10-29. Live example (REXX) ES52G5.0
Notes:
V10.1
Student Notebook
Uempty
Background REXX execution

• Running an exec in the background is the same as running a CLIST in
the background.
• The program IKJEFT01 sets up a TSO/E environment from which you
can invoke execs and CLISTs and issue TSO/E commands.
• The EXEC statement defines the program as IKJEFT01.
• The REXX routine (and any called routines) must be in a PDS defined to
the SYSEXEC or SYSPROC system file.
//USERIDA JOB 'ACCOUNT,DEPT,BLDG','PROGRAMMER NAME',

// CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//*
//TMP EXEC PGM=IKJEFT01,REGION=4M
//SYSEXEC DD DISP=SHR,DSN=USERID.REXX.EXEC
//SYSTSIN DD *
%MYEXEC arg1 arg2
/*
//
Figure 10-30. Background REXX execution ES52G5.0
Notes:
When you run an exec in the foreground, you do not have use of your terminal until the exec
completes. Another way to run an exec is in the background, which allows you full use of your
terminal while the exec runs. You can run time-consuming and low priority execs in the background,
or execs that do not require terminal interaction.
Running an exec in the background is the same as running a CLIST in the background. The
program IKJEFT01 sets up a TSO/E environment from which you can invoke execs and CLISTs
and issue TSO/E commands. For example, to run an exec named MYEXEC contained in a
partitioned data set USERID.REXX.EXEC, submit the above JCL:
The EXEC statement defines the program as IKJEFT01. The REXX routine (and any called
routines) must be in a PDS defined to the SYSEXEC or SYSPROC system file. You can assign one
or more PDSs to SYSEXEC or SYSPROC. The SYSTSPRT DD allows you to print output to a
SYSOUT class or a specified data set. In the input stream, after the SYSTSIN DD, you can issue
TSO/E commands and invoke execs and CLISTs.
Any additional files needed to run the exec can be defined with the TSO ALLOCATE command
within the exec or in the SYSTSIN input stream (prior to executing the exec), or by adding additional
JCL DD statements.
Student Notebook
Running REXX in batch

• Can run REXX in batch using TSO/E in background
– IKJEFT01, IKJEFT1A, IKJEFT1B
– Runs in TSO/E address space
• Can run REXX in batch using IRXJCL
– Runs in MVS address space
– TSO host command environment not available
• Required ddnames
– SYSEXEC: Concatenated list of REXX libraries
– SYSTSPRT: Exec output, like Say instructions
– SYSTSIN: Input to TSO/E in background or REXX exec
• Optional ddnames
– SYSPRINT: System messages
– Others as needed by programs
Figure 10-31. Running REXX in batch ES52G5.0
Notes:
It is fairly common to run batch jobs that run REXX execs. If you are only running one exec in your
batch job, you may specify it in the PARM parameter on the EXEC statement. If you want to run
multiple execs, you may specify them in the //SYSTSIN DD input stream statement.
Note that you have a choice of three program names to run TSO/E in the background. They are
IKJEFT01, IKJEFT1A, and IKJEFT1B. The difference is that IKJEFT1A and IKJEFT1B provide
additional return code and abend support, which may be more suitable to a batch job than
IKJEFT01, which is designed more for interactive use. Indeed, IKJEFT01 is the program that is
executed when you logon to TSO/E.
For more information, see the z/OS TSO/E User’s Guide.
V10.1
Student Notebook
Uempty
REXX in batch using IRXJCL

• Another way to run REXX execs in batch is to use the IRXJCL
program.
– Cannot use TSO/E services, such as TSO/E commands (like
ALLOCATE) and most of the TSO/E external functions.
– Any additional files needed to run the exec must be defined by adding
JCL DD statements.
//USERIDA JOB 'ACCOUNT,DEPT,BLDG','PROGRAMMER NAME',
// CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//*
//* RUN REXX EXEC IN BATCH
//*
//* PARM VALUE IS THE CLIST AND ARGUMENTS TO BE EXECUTED
//* SYSEXEC DD POINTS TO THE EXEC PDS
//*
//S1 EXEC PGM=IRXJCL,PARM='MYEXEC arg1 arg2'
//SYSTSIN DD DUMMY
//SYSEXEC DD DISP=SHR,DSN=USERID.REXX.EXEC
Figure 10-32. REXX in batch using IRXJCL ES52G5.0
Notes:
Running an exec in batch using IRXJCL is similar in many ways to running an exec in the TSO/E
background using IKJEFT01, however, there are differences.
One major difference is that the exec running in batch by using IRXJCL cannot use TSO/E
services, such as TSO/E commands (like ALLOCATE) and most of the TSO/E external functions.
Since execs running in batch by using IRXJCL cannot use TSO/E services, any additional files
needed to run the exec must be defined by adding JCL DD statements.
Student Notebook
REXX in batch using TSO/E: an example

//TSO1 EXEC PGM=IKJEFT1A,PARM=MATH3
//SYSEXEC DD DSN=TSOCH27.REXX.EXEC,DISP=SHR
//SYSTSIN DD *
39 84
297 643
exit
/*
//TSO2 EXEC PGM=IKJEFT1A
//SYSTSIN DD *
MATH1 24 97
MATH2
13 76
LISTCAT
/*
Figure 10-33. REXX in batch using TSO/E: an example ES52G5.0
Notes:
The example in the visual shows two job steps, both running the program IKJEFT1A, so they are
running TSO/E in batch. In the first step only one REXX exec is running, MATH3. It is being
provided by using the PARM parameter on the EXEC statement. The MATH3 program will prompt us
for the two numbers on which to perform arithmetic, and that input is provided by using the
SYSTSIN DD statement. Notice that when MATH3 requests the next set of numbers, the next line
from SYSTSIN will be read. At the next prompt from MATH3, the line containing the word ‘exit’ is
passed to the exec, and will cause MATH3 to terminate.
In the second job step there is no PARM parameter, so IKJEFT1A simply reads from SYSTSIN. This
DD statement can be thought of as almost like the TSO READY prompt. Each line will be read in
succession, and may include REXX execs to run, input to those execs as responses to Parse Pull
or Parse External, and even TSO/E commands, like LISTCAT. When the last line from SYSTSIN
has been processed, the TSO/E program ends. The SYSTSPRT DD will contain all of the output
that was generated.
V10.1
Student Notebook
Uempty
REXX in batch using IRXJCL: An example

//TSO1 EXEC PGM=IRXJCL
//INPUT DD DSN=MY.INPUT.DATA,DISP=SHR
//SYSTSIN DD *
MATH3
39 84
297 643
exit
REXXTRY
'EXECIO * DISKR INPUT (STEM rec.'
Do i = 1 To rec.0; Say rec.i; End i
exit
/*
Figure 10-34. REXX in batch using IRXJCL: An example ES52G5.0
Notes:
The example in the visual is running the program IRXJCL, so it is running in an MVS address space
with a default host command environment of MVS. Again, there is no PARM parameter, so the
program looks to the SYSTSIN DD statement for the work it is to perform. Each line is read again,
one at a time, until there is no more work to do.
Note the INPUT DD statement in the JCL, which is referenced by the EXECIO command that is
executed under the control of REXXTRY. In this example the ddname INPUT must be provided by
using the DD statement and not by using an ALLOCATE command, as that command is not
executable in an MVS host command environment.
Student Notebook
Console session security requirements

• TSO/E users may activate operator console mode from their
TSO session
• Must have security system authority to do this
– RACF Facility classes are:
• CLASS(CONSOLE) to activate a console
• CLASS(OPERCMDS) to issue the commands
Figure 10-35. Console session security requirements ES52G5.0
Notes:
A TSO/E user could have the ability to start an MVS MCS (Multiple Console Support) operator
console session from their TSO/E terminal session. Typically your security product (RACF, ACF2,
or Top Secret) must have specifications defined to allow you to do this. In RACF there are two
facility class profiles involved, CONSOLE and OPERCMDS.
The CONSOLE facility class profile allows you to start an MCS console session. This allows you to
issue the TSO/E CONSOLE command. RACF can maintain precise control over the commands you
are authorized to issue by using the OPERCMDS profile. A user may be authorized to issue only
one command, a group of commands, or all operator commands. In this course, your exercise user
ID is authorized to issue MVS DISPLAY commands.
V10.1
Student Notebook
Uempty
The CONSPROF command

• Syntax:
CONSPROF
SOLDISPLAY( YES ) UNSOLDISPLAY( YES )
NO NO
SOLNUM(nnnn) UNSOLNUM(nnnn)
where:
SOLDISPLAY determines whether solicited messages are to be displayed at
the terminal
UNSOLDISPLAY determines whether unsolicited messages are to be displayed
at the terminal
SOLNUM defines the maximum number of solicited
messages held in a message table
UNSOLNUM defines the maximum number of unsolicited
messages held in a message table
Figure 10-36. The CONSPROF command ES52G5.0
Notes:
The TSO/E CONSPROF command sets up your console profile. While it is not strictly necessary to
define a console profile in order to issue MVS operator commands, it is recommended that you do
so, especially in REXX execs where you plan to capture and process the messages issued in
response to these commands, and do not want them to be displayed on the console screen.
The profile defines whether or not solicited and unsolicited messages are to be displayed on the
console. Solicited messages are messages generated by the system in response to MVS
commands that have been entered. Unsolicited messages are system messages not in response to
MVS commands. These could be messages sent to you by another user or messages generated
automatically by the system as various system events occur.
If messages are not to be displayed at the console, they will be stored in a message table. The
number of solicited or unsolicited messages that may be stored can be defined by the profile.
Student Notebook
The CONSOLE command

• Syntax:
CONSOLE
ACTIVATE
DEACTIVATE
SYSCMD(command)
CART(cartvalue)
where:
ACTIVATE activates an MCS console session
DEACTIVATE terminates the console session and returns to TSO
SYSCMD(command) executes the specified MVS operator command
CART(cartvalue) sets the specified CART value
Figure 10-37. The CONSOLE command ES52G5.0
Notes:
The TSO/E CONSOLE command allows you to activate or deactivate an MCS console session,
issue an MVS operator command, and set a CART value. This command, like CONSPROF, requires
authorization to use.
The CONSOLE command must set a return code of zero. If it does not, then your MCS console
session was not properly started, and your MVS operator commands may not work correctly.
The CART will be discussed soon.
V10.1
Student Notebook
Uempty
The GETMSG() function

• Syntax:
GETMSG(stem. )
,
type ,
cart ,
mask ,
time
where:
stem. is the stem name of a compound variable
type is one of SOL, UNSOL, or EITHER
cart is the CART value of the messages you wish to retrieve
mask is a mask value which is ANDed with the CART
time is the number of seconds GETMSG() should wait for the
messages to be routed to the console
Figure 10-38. The GETMSG() function ES52G5.0
Notes:
The GETMSG() function is a TSO/E REXX function. It is implemented as part of TSO/E, but is only
usable inside a REXX exec. It is also not available in all REXX implementations. This function
allows us to capture messages that would otherwise be displayed on an operator console, but are
instead being stored in a message table, because the CONSPROF command defined SOLDISPLAY
or UNSOLDISPLAY with a value of NO.
The first argument to GETMSG defines a stem which is used to create compound variables with the
messages. The variables will be called stem.1, stem.2, and so forth, with each variable holding
one line of message output, much like the OUTTRAP() function does with TSO/E command output.
Also, the variable stem.0 is created, holding the number of compound variables that were created
(again, much like the OUTTRAP() function).
The second argument defines which type of messages are to be retrieved from the message table.
SOL will only retrieve solicited messages. UNSOL only retrieves unsolicited messages. EITHER
will retrieve both solicited and unsolicited messages. EITHER is the default.
Student Notebook
The CART
• Command and Response Token
• Used to track messages issued in response to operator
commands
• Useful when issuing more than one operator command
• Useful in multiprogramming environment
Address CONSOLE
'CART EXEC0001'
opercmd1
'CART EXEC0002'
opercmd2
...
getcode = GETMSG('msg1.','SOL','EXEC0001',,5)
getcode = GETMSG('msg2.','SOL','EXEC0002',,5)
Figure 10-39. The CART ES52G5.0
Notes:
CART stands for Command And Response Token. It is used to associate a value with one or more
MVS commands and the messages issued in response to those commands. The CART allows the
GETMSG() function to retrieve messages in direct response to a particular command by specifying
the same CART value in the GETMSG() function as was associated with the command itself. The
GETMSG() function only recognizes the use of a CART if the type of message being retrieved is
SOL.
The CART value may be from one to eight characters or from one to sixteen hexadecimal digits
long. If you specify a value less than 8 characters or 16 hexadecimal digits, it is padded on the right
with blanks. If no CART is established for a command, a default value of 16 hexadecimal zeroes will
be used.
V10.1
Student Notebook
Uempty
How it is done
• Set up your console profile defaults:
'CONSPROF SOLDISPLAY(NO) SOLNUM(400)'
• Activate your console session:
'CONSOLE ACTIVATE'
• Change addressing environment:
Address CONSOLE
• Set a CART
'CART APP001'
• Issue your z/OS operator command(s):
'DISPLAY IPLINFO'
• Get the responses back:
getcode = GETMSG('msg.','SOL','APP001',,30)
• Switch back to TSO host command environment:
Address TSO
• Deactivate console session:
'CONSOLE DEACTIVATE'
Figure 10-40. How it is done ES52G5.0
Notes:
This visual shows a typical flow of logic for issuing MVS operator commands and retrieving their
responses from within a REXX exec.
Student Notebook
References
• z/OS MVS System Commands (SA22-7627)
• z/OS TSO/E System Programming Command Reference
(SA22-7793)
– CONSOLE command
– CONSPROF command
– OPERATOR command
• z/OS TSO/E REXX Reference (SA22-7790)
– Activating console sessions
– CONSOLE host command environment
– Processing messages
– GETMSG() function
Figure 10-41. References ES52G5.0
Notes:
Refer to the manuals listed in the visual for more information about utilizing MCS console services
from TSO/E and REXX.
V10.1
Student Notebook
Uempty
Checkpoint (1 of 3)
1. True or False: The REXX interpreter detects syntax errors in
all parts of a REXX program.
2. In order to execute compiled exec code, the data set

containing the compiled code should be allocated to the
(blank) ddname.
3. Can the REXX compiler create both compiled exec code and
object code at the same time?
4. True or False: The cross reference listing is included in the

compiler listing by default.
Notes:
Student Notebook
Checkpoint (2 of 3)
5. When running REXX execs in batch jobs, what is the purpose
of the following ddnames:
SYSTSPRT
SYSPRINT
SYSTSIN
SYSEXEC
6. True or False: Anyone can issue the TSO/E CONSPROF

command.
7. True or False: You do not have to define a console profile in

order to execute MVS operator commands from within a
REXX exec.
Notes:
V10.1
Student Notebook
Uempty
Checkpoint (3 of 3)
8. In order to execute MVS operator commands from within a
REXX exec and capture the responses to those commands,
you must define a console profile. Why?
9. What is the purpose of the CART?
10. What function would you use to retrieve system messages

from the message table in memory?
Notes:
Student Notebook
Unit summary
Notes:
V10.1
Student Notebook
Uempty
Unit 11. System REXX

This unit describes a new component called System REXX. System REXX is
a z/OS component (z/OS 1.9 and higher) that allows REXX programs to be
executed outside of conventional TSO/E and batch environments, such as
from an operator console. The role of SYSREXX in “New Face of z/OS” is to
provide an infrastructure through which REXX execs can be run outside the
normal TSO/E or Batch environments, by using a simple programming
interface. This enables the leveraging of base operating system components
by new style applications that will, over time, lead to simplified interaction and
more intuitive system management capabilities on z/OS.

• Describe the benefit of System REXX
• Describe the different execution environments of SYSREXX
• Plan for and implement System REXX support
• Create System REXX exec routines
• Invoke System REXX exec routines
• Use the console Interface for System REXX Execs
• List the major SYSREXX Functions

Accountability:
• Exercises
References
© Copyright IBM Corp. 1999, 2016 Unit 11. System REXX 11-1
Student Notebook

SH19-8179 IBM Compiler and Library for REXX on System z:
Diagnosis Guide
SH19-8160 IBM Compiler and Library for REXX on System z: User's
Guide and Reference
V10.1
Student Notebook
Uempty
Unit objectives
• Use the console interface for System REXX execs
• List the major SYSREXX functions
Notes:
Student Notebook
System REXX overview

• Need addressed:
– Required an infrastructure to support web based initiatives interacting
with z/OS components
• New face of z/OS
– z/OS Simplification and Management
• Solution:
– SYSREXX allows execs to be run simply and independently from
traditional TSO/E and Batch
• Invocation uses a single program interface (AXREXX)
• Operator exploitation directly from a console
• Benefit:
– Enables rapid development and deployment of system programmer
tools and operator assists
– Can be exploited by new and old style applications
– Health checks may be written in REXX
Figure 11-2. System REXX overview ES52G5.0
Notes:
The role of SYSREXX in “New Face of z/OS” is to provide an infrastructure through which REXX
execs can be run outside the normal TSO/E or Batch environments, by using a simple programming
interface. This enables the leveraging of base operating system components by new style
applications that will, over time, lead to simplified interaction and more intuitive system
management capabilities on z/OS.
The ability to initiate REXX execs directly from an operator console has been long overdue on z/OS
and is a drag along benefit of this initiative.
The possibilities for exploiting existing REXX code through the use of SYSREXX are vast, whether
to provide operator assists or to provide routines that can be leveraged by new strategic initiatives.
• System REXX provides a gateway for new style applications to interface with z/OS components
• System REXX adds real value today through exploitation possibilities for operator assists and
also certain system management processes
• The AXREXX macro allows REXX execs to be easily run from assembler programs.
• The MODIFY AXR command allows operations to benefit from running REXX execs from the
console.
V10.1
Student Notebook
Uempty
System REXX
• A function that allows REXX EXECs to be executed outside of
conventional TSO/E and Batch environments
• Can be invoked using assembler macro interface AXREXX or through
an operator command
• Easy way for web based servers to run commands/functions and get
back pertinent details
• EXEC runs in problem state, key 8, in an APF authorized address space
under the MASTER subsystem
• Two modes of execution
– TSO=NO runs in MVS host environment
address space shared with up to 64 other EXECs
limited data set support
– TSO=YES runs isolated in a single address space
can safely allocate data sets
does not support all TSO functionality
Figure 11-3. System REXX ES52G5.0
Notes:
System REXX is a z/OS component (z/OS 1.9 and higher) that allows REXX programs to be
executed outside of conventional TSO/E and batch environments, such as from an operator
console. This now allows automation products to issue console commands to directly run REXX
programs without the need for a JCL “wrapper” or by using another subsystem such as NetView.
System REXX has the following uses:
• A straightforward mechanism for Common Information Model (CIM) Server Indication, Instance
and Method Providers to request execution of REXX routines and z/OS System Commands and
for the return of parsed operational information in support of the Business Resiliency effort.
• A way for system and application components to leverage the parsing strengths of REXX.
• Because REXX coding skills are relatively abundant and span the primary operating systems
there is the possibility that code developed on one platform might be shared on others with
minimal change.
• Faster and simpler development of new Health Checker routines.
• Can be leveraged to provide simplified operator assist functions and quick fixes to niggling
problems.
Student Notebook
SYSREXX logical overview

•Convert ARG/VAR to string format for REXX
1 •Pass request to appropriate AXR Server
•Return for SYNC=Y pass output ARGs back
PC
AXREXX TSO=N
SYSREXX (AXR) R-SRB
AXREXX TSO=Y
MGCR(E) JobStepTASK
•Initialize AXR Environment - Read AXR00 PC
•Allocate REXXLIB D/Set – SYS1.SAXREXEC
•Initialize XMS – LX/ET -> PC #
1
MPF U/EXITs •CB Structures – Work Queue
•Initialize Component Trace
•Attach Server Sub-Tasks
•Stack/Linkage Control
PARMLIB(AXR00)
AXR Listener CPF

•Initialize ESTAE & RESMGR
•No Work Wait AXR01 AXR08
S
S
F AXR •Termination
REXXLIB D/Sets
4 TSO WkAsid1 TSO WkAsid8
I
1 •Initialize AXR Environment
•MCSOPER (EMCS)
•MGCRE & MCSOPMSG
•Allocate REXXLIB D/Set
•Attach Worker Subtasks
… Convert ARGs / VARs to string
•Stack/Linkage Control format for REXX & pass request

HARDCOPY •No Work Wait to appropriate server
2 2 3 2
CONSOLES
REXX SERVER CMD SERVER
•CIB Control
TSO SERVER 5 TSO WkD1 TSO WkD8
•Queue Control •Queue Control
•PC Entry (API) •Process MODIFY Cmd •PC Entry (API)
•Schedule Task
•No work wait
SYSREXX STATUS[,DETAIL]
RexxExec ‘Args/Vars’
•No work wait
•Schedule Task
•No work wait
•Key8 Storage
•IRXINIT/LOAD/EXEC …
SYNOPSIS:
STORAGE CELLPOOL •AXR is a sub-system, started during MSI.
•Reads PARMLIB member AXR00 & allocates REXXIN data set.
•REXX work requests originate from operator console (detected
by AXR SSI Listener) or program interface (AXREXX).
4
3 REXX WkT1 REXX 3 TSO WkT1 TSO WkT8
•REXX work arrives via PC directly into the appropriate Server.
•SYSREXX or console initiated REXX execs are detected by the AXR SSI
Listener, converted to MODIFY AXR format and queued to the Command
WkT64 •Convert & Buffer Results
•Convert & Buffer Results
•Marshall ARGs/VARs etc.
•MCSOPER (EMCS)
… 6 •Marshall ARGs/VARs etc.
•Resume Requestor|Done
… Server’s CIB. In turn they are selected and scheduled for processing
•REXX Server controls a group of worker subtasks that attach daughter
•MGCRE & MCSOPMSG •Cleanup REXX CB Fields subtasks to process TSO=N requests. Initially 4 are started. Up to 64 as
•Resume Requestor|Done •Mark Task Available required.
•Cleanup REXX CB Fields •Back To REXX Server •TSO Server controls a group of worker subtasks that start between 1-8
•Mark Task Available
•Back To REXX Server R-SRB 5 R-SRB 7 address spaces to process TSO=Y requests.
•Extended MCS consoles are associated with every REXX worker task and
TSO worker address space for z/OS command/response processing.
4 REXX WkD1 REXX •Output Arg/Var results are returned by writing into the storage locations
indicated by the caller & for synchronous requests, resuming the
•Key8 Storage WkD64 suspended Task in the caller’s AS.
•IRXINIT/LOAD/EXEC … •Results from asynchronous requests (SYNC=N) in nature fire & forget.
They will usually cause other processes, watching for specific events to be
triggered.
Figure 11-4. SYSREXX logical overview ES52G5.0
Notes:
Overview
System REXX execs can be initiated through an assembler macro interface called AXREXX or
through an operator command.
Two different execution environments are supported: TSO=NO and TSO=YES. In both
environments the exec runs in problem state, key 8, in an APF authorized address space; thus any
modules that are loaded, linked or attached from the exec must reside in an APF authorized library.
Also in both cases, the REXX exec runs under the WLM enclave of the AXREXX invoker.
When TSO=NO is specified on the AXREXX invocation, the exec is executed in an MVS host
command environment, sharing the address space where it is executing with up to 63 other
concurrently running TSO=NO execs. The exec runs under a task in the AXR address space which
runs under the MASTER subsystem.
Besides MVS, the following host command environments are supported:
• LINK, LINKMVS, ATTACH, ATTCHMVS, ATTCHPGM, CPICOMM, LU62, APPCMVS
Dataset allocation, other than provided by the AXREXX macro, is not supported in this environment.
V10.1
Student Notebook
Uempty Applications that perform input/output to datasets other than those specified on the REXXINDSN
and REXXOUTDSN AXREXX keywords should use TSO=YES.
The TSO=YES environment supports all of the host commands that TSO=NO supports, along with
some of the host commands supported by TSO.
If TSO=YES is specified on the AXREXX invocation, the exec will run isolated in a single address
space, and can safely allocate datasets without concern of a DDNAME conflict with a concurrently
running exec. If the exec were to exit with datasets allocated, System REXX will free the
allocations.
The TSO environment is established by the Dynamic TSO Service (IKJTSOEV) and does not
support all of the TSO functionality. The TSO=YES environment supports UNIX System Services
host commands, assuming that the invoker of AXREXX specifies (or defaults to) a valid security
environment. Additionally, execs running in this environment will run under the primary subsystem
(that is, JES) if it is available.
Below is a list of TSO host commands that are intended to be supported:
ALLOCATE (excludes the SYSOUT operand), FREE, ALTLIB, ATTRIB, CALL, DELETE, EXEC,
HELP, PROFILE, SMCOPY, TIME, WHEN. In R11 the STORAGE external function is enabled, but only
for reading storage; writing storage is prohibited due to the potential risk of inadvertently modifying
system storage.
There can be up to 64 REXX worker tasks, running TSO=NO execs and up to 8 TSO Server
address spaces running TSO=YES execs. If a worker task is not available for an inbound TSO=NO
request or a TSO Server address space is not available for a TSO=YES request, the request is
queued and the requestor is suspended if SYNC=YES is specified. AXREXX invokers who use
SYNC=YES should be careful when a potentially long wait time is unacceptable. At most 5000
active and waiting requests are allowed to exist at any time. Once this threshold is reached,
subsequent AXREXX requests are rejected until the number of active and waiting requests drops to
4000. ENF signals (65) are issued when the threshold is exceeded (qualifier of 20000000x), when
the total number of requests is getting close to the threshold (qualifier of 08000000x) and when
acceptance of inbound requests is resumed (qualifier of 10000000x).
Student Notebook
REXX server versus TSO server

• REXX server • TSO server
• Execs run in AXR AS • Execs run in AXRnn AS
– 1-64 Worker Subtasks – 1-8 TSO Server Address
– EMCS for each subtask Spaces
– Detach after 100 execs – EMCS for each AS
– Default HCE - MVS – Detach after 200 execs
– Recommend no Data Set – All Allocation capabilities
Allocation here – Default HCE - TSO
• Availability impact if • IKJTSOEV - Dynamic TSO
something serious breaks environment
• SYSCALL supported
• Better availability should
something serious break..
just cancel AXRnn AS
Figure 11-5. REXX server versus TSO server ES52G5.0
Notes:
HCE host command environment:
Two modes of execution
TSO=NO runs in MVS host environment
- Address space shared with up to 64 other EXECs
- Limited data set support
TSO=YES runs isolated in a single address space
- Can safely allocate data sets
- Does not support all TSO functionality
V10.1
Student Notebook
Uempty
Migration and Coexistence considerations

• No hardware dependencies
• Software dependencies
– To Process Compiled REXX Code
• IBM Library for REXX on zSeries OR
• IBM Library for REXX on zSeries Alternate Library
• Exploiters
– CIM Server .. Cluster Instrumentation
– Health Checker, SDSF REXX
– Open to exploitation by IBM, ISV and Customer Code
• As SYSREXX is a new element there are no migration considerations
• Be aware that not every command, function or service that runs under
the TSO/E Terminal Monitor Program is supported in the SYSREXX
TSO=Y environment
• Only commands documented will be supported
Figure 11-6. Migration and Coexistence considerations ES52G5.0
Notes:
Failure to correctly set up the REXX Run Time Library or the Alternate Library causes failure to run
compiled REXX execs
- Return/reason code 0C/xxxx0C08, message IRX0157E
There is a loosely coupled software prerequisite when compiled REXX code is to be processed;
IBM Library for REXX on zSeries Alternate Library (5695014/HWJ9143) will automatically be
included on z/OS ServerPacs, should the installation not be licensed for IBM Library for REXX on
zSeries (5695014/HWJ9140).
This Alternate Library is entitled and provides a basic runtime processor capable of interpreting
compiled REXX execs.
Its inclusion is necessary as some IBM REXX code is shipped only in compiled format.
Student Notebook
Installation
• Parmlib support
– SYSREXX customization: AXR00
• IEASYSxx can specify an AXRxx parmlib concatenation
– AXR=(xx,yy,…)
– First valid instance of option used
• CPF(‘cpfvalue’,SYSTEM|SYSPLEX)
• AXRUSER(userid)
– Optional
Figure 11-7. Installation ES52G5.0
Notes:
CPF defines command prefix or action character and scope of prefix
AXRUSER defines the default users if AXREXX is invoked
Implementation and Customization – SAXREXEC
• SYS1.SAXREXEC shipped by IBM
- Contains IBM provided REXX‘s (starting with A through I)
- User defined REXX must reside in SYS1.SAXREXEC
- REXX can placed either compiled or as script
Do not rename this library
• REXXLIB support
- Up to 255 data sets are supported
- SYS1.SAXREXEC concatenated as the last data set unless specified
- Data sets must have the same characteristics as SYS1.SAXREXEC (that is, variable length
records of size 255)
V10.1
Student Notebook
Uempty Here are some examples of REXXLIB statements:

REXXLIB ADD DSN(HMORGEN.MYREXX) VOL(PEVTST)
REXXLIB ADD DSN(hmorgen.pds2)
System REXX - basics
1. SA22-7608-11 z/OS V1R9.0 MVS Authorized Assembler Services Guide
2. *.PARMLIB(AXR00) has the command prefix (CPF), which is really a subsystem recognition
character (SRC). What you type to fire off System REXX code from the console. Default CPU is
REXX&sysclone Default AXRUSER is AXRUSER
3. Console commands F AXR,SYSREXX,STATUS F AXR,SYSREXX,STATUS,DETAIL F
AXR,rexx_exec_name{,TIMEINT=30} arg(1) arg(2) ... CPU rexx_exec_name arg(1) arg(2) ...
4. Datasets SYS1.SAXREXEC - for now, only one and on the SYSRES
5. Security - RACF RDEFINE SURROGAT SYSREXX.AXRUSER UACC(NONE) SETROPTS
GENERIC (SURROGAT) REFRESH PERMIT SYSREXX.AXRUSER CL(SURROGAT)
ACCESS(ALTER) ID(<userid>) RDEFINE MVS.SYSREXX.EXECUTE.* RDEFINE
MVS.SYSREXX.STATUS
6. Stopping F AXR,ARM
7. Starting/restarting SYS1.PROCLIB(AXRPSTRT) S AXRPSTRT
Student Notebook
Implementation and customization: Startup

• AXR AS
up and
running
• AXR01
TSO=YES
AS active
Figure 11-8. Implementation and customization: Startup ES52G5.0
Notes:
V10.1
Student Notebook
Uempty
TSO/E command support

• TSO=YES requires an isolated address space to avail itself of
TSO/E services and POSIX host commands.
– Authorized … jscbauth = 1
– Address spaces called AXR01-08
– Within a dynamic TSO/E environment … ikjtsoev service
• We restrict the number of commands that Sysrexx officially
supports because the Dynamic TSO environment does not set
up all the features of the Terminal Monitor Program (TMP).
• Supported commands:
– allocate attrib
– call delete exec
– free help profile
– rmm smcopy time
Figure 11-9. TSO/E command support ES52G5.0
Notes:
Two modes of execution:
TSO=NO runs in MVS host environment
Address space shared with up to 64 other EXECs
Limited data set support
TSO=YES runs isolated in a single address space
Can safely allocate data sets
Does not support all TSO functionality
Student Notebook
Usage and invocation

• Major SYSREXX functions :
– AXRCMD
• Issue a console command and return command responses
– AXRWTO
• Issue a single line message to a console
– AXRMLWTO
• Issue a multiline line message to a console
– AXRWAIT
• Waits for a specified number of seconds
• Similar to SLEEP host command (available in TSO=YES environment)
– AXRINFO
• Obtains environmental information
Figure 11-10. Usage and invocation ES52G5.0
Notes:
Functions
These functions are provided: AXRCMD, AXRWTO, AXRMLWTO, AXRWAIT and AXRINFO
V10.1
Student Notebook
Uempty
AXRCMD
• AXRCMD
– Issue a console command and return command responses
• The AXRCMD function
– Issue a system command from an exec and obtain the command
responses
– Responses are returned similar to those for GETMSG
– This function is coded as follows:
• CALL AXRCMD(“command text”,msgstem,timelimit)
• Result=AXRCMD (“command text”,msgstem,timelimit)
– msgstem is a stem variable for command responses
> msgstem.0 contains the number of msgstem.nn variables
– timelimit is the timeout interval set for completion
Figure 11-11. AXRCMD ES52G5.0
Notes:
AXRCMD is used to issue a system command from within the exec and obtain one or more
command responses.
The arguments that can be specified are listed below:
• Command text: The system command to be invoked. This is an optional argument. If it is
omitted, no command will be issued, but a response from the last command issuance will be
returned if one exists.
• Msgstem: The stem of a list of variables into which AXRCMD places the command response
message text. This is an optional argument. If it is omitted, Command text must be specified. To
place the message text into compound variables which allows for indexing, msgstem should
end with a period (for example, “messg.”). AXRCMD places each line of the retrieved message
into successive variables. For example, if the command response is a 3 line message, messg.1
contains line 1, messg.2 contains line 2 and messg.3 contains line 3. messg.0 will contain the
number of lines. If msgstem does not end with a period, the variable names are appended with
consecutive numbers. For example, suppose you specify msgstem as “conmsg” (without a
period). If AXRCMD retrieves a message that has two lines of message text, AXRCMD place
Student Notebook
the text in the variables consmsg1 and consmsg2. The variable consmsg0 contains the
number of lines in the message text, which is 2.
• Time: The amount of time in seconds that AXRCMD should wait for a command response. This
is an optional argument. If it is omitted, AXRCMD will not wait before attempting to determine
whether a command response was returned. A value of 0 – 21474535 seconds may be
specified.
Users of AXRCMD can initiate another REXX exec by either specifying the MODIFY AXR command
or CPF prefix, but should be careful not to recursively invoke the same exec using AXRCMD.
Some examples of the invocation of AXRCMD follow:
Example 1:
CmdResult=AXRCMD('D U,,,480',’OUTPUTVAR.’,40); /* Issue the D U
command */
DO I = 1 TO OUTPUTVAR.0 /* Iterate for the number

of lines returned */
SAY OutputVar.I /* Say the line */
END;
Example 2:
MyResult=AXRCMD('D T'); /* Issue the D T command but don’t wait for
a command response */
MyResult=AXRCMD(, ‘OUTPUTVAR.’,10); /* Obtain the command response
from
the last command issued and wait up to 10
seconds if it has not arrived */
Example 3:
ARG InCmdText /* Reteive command to be issued. */
/* Issue the cmd String containing the command to be executed */
/* via AXRCMD Stem variable name for the output */
/* Time to wait for respons (secs) */
/* */
AxrCmdRc = AXRCMD(InCmdText,Msg.,4);
IF AxrCmdRc = 0 THEN
DO /* Write result to console using AXRMLWTO */
...
...
V10.1
Student Notebook
Uempty
AXRWTO
• AXRWTO
– Issue a single line message to a console
• Issue a WTO from an exec
– As a command response when CONSDATA=YES is coded on the
AXREXX macro
– Otherwise the “text” is directed to the system log
• AXRWTO is coded as follows:
– CALL AXRWTO “text”
– Result = AXRWTO(“text”)
Figure 11-12. AXRWTO ES52G5.0
Notes:
Functions continued…
WTORESULT=AXRWTO('HELLO ES52 student FROM A REXX EXEC UNDER SYSREXX')
CALL AXRWTO 'GOT ANY SYSTEM CLASS REQUIREMENTS? .. irlphelp@us.ibm.com
00000210 @TESTWTO
00000010 HELLO ES52 student FROM A REXX EXEC UNDER SYSREXX
00000010 GOT ANY SYSTEM CLASS REQUIREMENTS? .. irlphelp@us.ibm.com
AXRWTO is a function that issues the WTO macro containing the specified text, using the
CONSNAME and CART provided on the AXREXX invocation.
If CONSDATA is not specified the message text is sent to the system log.
There is one required argument for AXRWTO:
• Message text - containing the message text to be issued by using the WTO macro. The text must
be from 1-126 characters in length.
The return codes from AXRWTO are:
• 0 – AXRWTO was successful
Student Notebook
• 4 – Input message text was too long. WTO is truncated.

• 8 – Input message text was a 0 length string. WTO not issued.
• 12 – Too many arguments were passed. WTO not issued
• 16 – The WTO macro returned a bad code. The REXX variable AXRDIAG contains the return
code from WTO (in hexadecimal)
• 20 – Required argument was omitted. WTO not issued.
The following are examples of AXRWTO:
WTOResult=AXRWTO('Hello from a REXX Exec');
CALL AXRWTO ‘Hello from a REXX Exec’; /* The return code from
AXRWTO is set in the variable “Result” */
V10.1
Student Notebook
Uempty
AXRMLWTO
• AXRMLWTO
– Issue a multiline line message to a console
• Issue a multiline WTO from an EXEC
– As a command response when CONSDATA=YES is coded on the
AXREXX macro
• AXRMLWTO is coded as follows:
– CALL AXRMLWTO(“text”,”<ConnectIdVar>”,<LineType>)
– Result=AXRMLWTO (“text”,”<ConnectIdVar>”,<LineType>)
– ConnectIdVar
• Must be to FirstLine prior to the first invocation
• Must appear in quotes
– ConnectIdVar=‘FirstLine’
– LineType corresponds to the five different WTO line types
Figure 11-13. AXRMLWTO ES52G5.0
Notes:
AXRMLWTO is similar to AXRWTO, except instead of issuing a single line WTO, a multi-line WTO
is issued instead.
There are three required arguments for AXRMLWTO:
• Message Text – containing the text of the message, the length of which depends on the line
type.
• Name of connect id variable - for the first invocation of the multi-line WTO, the variable should
be set to FIRSTLINE. After the first call, the variable will contain the connect id and should not
be altered by the application until the multi-line WTO is completed.
• Line type – there are five different line types. For details, see the description of the WTO macro in
z/OS Authorized Assembler Services Guide.
- C – Control line. The message text must be from 1-35 characters. If used, this must be the
first line of the multi-line.
- L – Label line. The message text must be from 1-71 characters.
- D – Data line. The message text must be from 1-71 characters.
Student Notebook
- DE – Data end line. The message text must be from 1-71 characters.
- E – End line. The message text must be omitted.
AXRMLWTO has the following return codes:
• 0 – AXRMLWTO was successful
• 4 – Message text was too long. Message is truncated.
• 8 – Text length was 0. WTO not issued.
• 12 – Too many arguments were passed. WTO not issued.
• 16 – WTO macro returned a bad code. The REXX variable AXRDIAG contains the return code
from WTO in hexadecimal.
• 20 – A required argument was omitted. WTO not issued.
• 24 – Invalid line type. WTO not issued.
• 28 – Invalid connect id. WTO is not issued
• 32 – Unable to set connect id variable. The variable name is bad.
V10.1
Student Notebook
Uempty
AXRMLWTO: An example
• AXRMLWTO
– Issue a multiline line message to a console
ARG InCmdText
AxrCmdRc = AXRCMD(InCmdText,stem.,4)
IF AxrCmdRc = 0 THEN do
ConnectId = 'MYMLWTO'
CALL AXRMLWTO '----Start of cmd output---
','ConnectId','L'
DO I = 1 TO stem.0
CALL AXRMLWTO stem.i,'ConnectId','D'
END
CALL AXRMLWTO '----End of cmd output----
','ConnectId','DE'
END
Figure 11-14. AXRMLWTO: An example ES52G5.0
Notes:
ConnectId = 'firstline';
MyResult=AXRMLWTO('Line 1 from a REXX Exec', 'Connectid','c'); /* Issue
the 1st line of the multiline */
IF MyResult^=0 THEN EXIT 1;
MyResult=AXRMLWTO('Line 2 from a REXX Exec', 'Connectid','d'); /* Issue
the 2nd line of the multiline */
IF MyResult ^=0 THEN
EXIT 2;
CALL AXRMLWTO ,'ConnectId','e'; /* End the multiline. In this case,
return code from AXRMLWTO is set in the
variable “result” */
Result:
@MLWTO
Line 1 from a REXX Exec 975
Line 2 from a REXX Exec
Student Notebook
Other SYSREXX functions

• AXRWAIT
– Waits for a specified number of seconds
– Similar to SLEEP host command (available in TSO=YES environment)
• AXRINFO
– Obtains environmental information
Figure 11-15. Other SYSREXX functions ES52G5.0
Notes:
Functions continued…
AXRWAIT:
CALL AXRWAIT 5 /* Wait for 5 seconds */
AXRINFO:
MySubsystem = AXRINFO(‘SUBSYSTEM’); /* Obtain the subsystem we are running under
*/
V10.1
Student Notebook
Uempty
Invoke System REXX execs

• Extends the console.
• 'F AXR,rexxname,TIMEINT=30 arg(1) ... arg(n).
• Use 'F AXR,SYSREXX,STATUS' to get cpf.
• cpf rexxname arg(1) arg(2) ... arg(n).
• Operator Command Support
– Detected by System REXX SSI Listener
• Uses a customizable Command Prefix (cpf)
– Administrative Support
• cpfSYSREXX STATUS[,DETAIL]
• cpfSYSREXX REXXLIB
– Seamless operator interface for REXX execs
• cpfRexxExecName Arg1 Arg2 … Argn
• REXX Execs Read From SYS1.SAXREXEC
– Or other data set in REXXLIB
Figure 11-16. Invoke System REXX execs ES52G5.0
Notes:
The Console Interface is the MODIFY AXR command
• Can be replaced by the CPF value defined in AXR00
Provides a seamless operator interface for REXX execs
• MODIFY AXR,<execname>[,TIMEINT=<seconds> <argument>]
• CPU<execname[,TIMEINT=<seconds> <argument>]
REXX execs are run with the AXREXX macro CONSDATA keyword in effect
• AXRWTO and AXRMLWTO functions send messages to the invoking console as command
responses
• Note that TIMEINT defaults to 30 seconds and may be abbreviated as T=
Student Notebook
Requests can be issued to System REXX by using the MODIFY AXR command. This can be used to
either gather status information or to invoke a REXX exec. For example, F
AXR,SYSREXX,STATUS returns status information on the System REXX environment:
F AXR,SYSREXX,STATUS
AXR0200I SYSREXX STATUS DISPLAY 877
SYSTEM REXX STARTED AT 12.45.08 ON 04/01/2010
PARMLIB MEMBERS: AXR00
CPF: REXXCB (SYSPLEX) AXRUSER: *NONE*
TIMEINT: 30
SUBSYSTEM: AXR
REQUESTS QUEUED: 0 ACCEPTING NEW WORK
REXX WORKER TASKS: ACTIVE: 0 TOTAL: 4
IDLE: 4 MAX: 64
ASYNC: 0 SYNC: 0
UNTIMED: 0
TSO SERVER SPACES: ACTIVE: 0 TOTAL: 1
IDLE: 1 MAX: 8
ASYNC: 0 SYNC: 0
UNTIMED: 0
A command prefix is defined in AXRxx as an easy way to issue the SYSREXX STATUS command or
to invoke a REXX program. The default command prefix is REXX&SYSCLONE, where
&SYSCLONE is a z/OS variable that represents the system name. For example, a REXX program
HELLO can be executed in the following manner, on a system whose &SYSCLONE value is ‘CB’:
REXXCB HELLO
The command execution result can be seen on the z/OS SYSLOG:
AXR0500I AXREXX OUTPUT DISPLAY 773
EXECNAME=HELLO REQTOKEN=0000400000000000C5F795A8A897D920
Hello From System REXX
System REXX retrieves the requested REXX programs by default from SYS1.SAXREXEC. You
have the ability to specify additional datasets in the AXRxx parmlib member(s) from which System
REXX will look for REXX programs.
There are additional security and programming considerations that are outside of the scope of this
unit, but are covered in the z/OS System REXX documentation.
When REXX programs are run under System REXX, by default any output from “say” commands
will appear on the SYSLOG and operator consoles. REXX programs run by System REXX should
minimize the amount of information output in this manner, as to not add to the current console
traffic.
V10.1
Student Notebook
Uempty
Console interface for REXX execs

• MODIFY AXR,SYREXX STATUS
– Provides overall status of System REXX
• MODIFY AXR,SYSREXX STATUS,DETAIL

– Provides detailed information about actively running execs
• MODIFY AXR,SYSREXX REXXLIB

– Displays the REXXLIB concatenation
Figure 11-17. Console interface for REXX execs ES52G5.0
Notes:
MODIFY AXR,SYSREXX may be replaced by <cpf>SYSREXX
SYSREXX may be abbreviated as SR
STATUS – ST
DETAIL – D
REXXLIB – R
Output from MODIFY AXR,SR R:
SY1 AXR0202I SYSREXX REXXLIB DISPLAY 792
ENTRY VOLUME DATA SET
1 PEVTST HMORGEN.MYREXX
2 PEVTST HMORGEN.AXRR11.REXX
3 BCPSV1 SYS1.SAXREXEC
4 ZD113B SYS1.SAXREXEC
Student Notebook
Output from MODIFY AXR,SR ST:

SY1 AXR0200I SYSREXX STATUS DISPLAY 770
PARMLIB MEMBERS: AXRHM
CPF: @ (SYSTEM) AXRUSER: IBMUSER
TIMEINT: 30
SUBSYSTEM: AXR
IDLE: 4 MAX: 32
ASYNC: 0 SYNC: 0
UNTIMED: 0
IDLE: 1 MAX: 8
ASYNC: 0 SYNC: 0
UNTIMED: 0
Output from MODIFY AXR,SR ST,D:
SY1 AXR0201I SYSREXX STATUS DETAIL 786
EXEC=JUNK2 CJBN=AXR CASID=0015 TSO=Y T/L=00.01.40
REQTOKEN=0000400000000000C6F6BF142A45D603
EJBN=AXR04 EASID=002C TCB=006E4668 CPU=000.009S TIME=003.328S
V10.1
Student Notebook
Uempty
Console interface for REXX execs: Considerations

• Command Authority determines which commands may be
entered from a console.
• A userid logging onto a console has all permissions associated
with the userid.
• Console initiated REXX Execs run TSO=YES.
• A blank separates arguments from one another and from the
other command keywords.
• The <argument> is a CHAR string consisting of the remainder
of the command line.
• SAY, TRACE and REXX messages are directed to the invoking
console as multi-line message AXR0500I.
Figure 11-18. Console interface for REXX execs: Considerations ES52G5.0
Notes:
Student Notebook
TSO/E command support

• Problems encountered:
– Some authorized commands do not tolerate a dynamic environment
• TSO/E control blocks are unavailable or incomplete
– CONSOLE host command environment is not supported
• Userid function does not return a valid userid
– Would be in the case where the AXREXX invoker does not specify (or default
to) a valid security environment.
– Link, Load, or Attach unauthorized modules … ABEND306
– Resources not cleaned up, may influence subsequent execs
• Data sets left allocated are freed (but execs should clean up)
• EXECs by default use Invoker’s Security Environment
– Alternatively may use:
• Authority of a 3rd party - a surrogat
• Special userid which is assigned to AXRUSER
Figure 11-19. TSO/E command support ES52G5.0
Notes:
AXRUSER has NOTHING to do with the Console Interface for REXX execs
• Common misconception
• Security environment is that of the user logged on to the console
RACF profile MVS.SYSREXX.EXECUTE.
• Resource used to determine whether the invoker is authorized to execute the exec
MVS.SYSREXX.
• Resource used to determine whether the invoker is authorized to issue F AXR,SYSREXX
STATUS and other MODIFY AXR commands
V10.1
Student Notebook
Uempty Security
The SECURITY and UTOKEN parameters on the AXREXX macro determine the security environment
that the exec runs in. If omitted, the exec will run under the same security environment as its
invoker. The security environment determines the datasets that may be accessed and the
commands and programs that may be invoked. When SECURITY=BYUTOKEN is specified, the
invoker can provide a UTOKEN to define the specific security environment that the exec should run
under (see z/OS Security Server RACROUTE Macro Reference). When SECURITY=BYAXRUSER
is specified, the exec will run under the security environment associated with the value (surrogat
user ID) of the AXRUSER parameter specified in the AXR00 parmlib member. This might be useful if
the installation wants to invoke AXREXX in an address space that does not have a security
environment such as the MASTER address space. The exec should not invoke any services that
alter the security environment of the task running the exec.
Controlling use of the surrogat user ID may be restricted through universal access control and
limiting the user IDs or groups in the permission's list.
ADDUSER siteuserid DFLTGRP(sitegroupid)
RDEFINE SURROGAT SYSREXX.* UACC(NONE)
PERMIT SYSREXX.* CL(SURROGAT) ID(siteuserid) ACCESS(READ)
SETROPTS RACLIST (SURROGAT) REFRESH
By default the AXREXX macro invocation uses SECURITY=BYUTOKEN. In this situation a security
token always accompanies the request. It is used to establish the security environment of the
invoker under which the exec will be run and is limited to whatever permission's are applicable to
the invoker. Additionally, if the REXX exec uses the AXRCMD function to issue a system command,
the security token will be passed to MGCRE ensuring the identical security information is used. The
security token value may be explicitly provided using the optional parameter UTOKEN, on the
AXREXX macro. If omitted, this value will be implicitly set to that of the invoker’s security
environment.
In all cases, the REXX exec runs under the WLM enclave of the AXREXX invoker.
Student Notebook
Usage: REXX API‘s example
Figure 11-20. Usage: REXX API‘s example ES52G5.0
Notes:
V10.1
Student Notebook
Uempty
Usage: REXX API‘s example USS?
Figure 11-21. Usage: REXX API‘s example USS? ES52G5.0
Notes:
Student Notebook
Usage: AXREXX service

• New API is AXREXX
– Caller must be authorized
– Two modes of execution
• TSO=NO limited data set support
• TSO=YES full data set support permitted (no sysout)
– Two operations are supported
• REQUEST=EXECUTE | CANCEL
– Arguments and variables are used to pass input to and receive output
from the REXX exec
– Parameter list is mapped by the AXRZARG macro
– REXX execs read from SYS1.SAXREXEC
Figure 11-22. Usage: AXREXX service ES52G5.0
Notes:
New API is AXREXX
• Data Types supported:
- Input is converted to strings
- Output is returned as signed/unsigned, char, binary, hex
• Security Environment of Requester is used
• Time Limitations are Applied to Execs
- Default is 30 seconds
• Cancellation of REXX Exec using API
- OREQTOKEN parameter
• REXX Execs Read From SYS1.SAXREXEC
V10.1
Student Notebook
Uempty
System REXX: A simple example

• The new AXR started task is now started for System REXX. It
requires a dataset called SYS1.SAXREXEC.
• I created a member in SYS1.SAXRXEC called Hello:
/* Rexx */
Say "hello world"
exit 0
• It was executed with the command F AXR,HELLO
EXECNAME=HELLO
REQTOKEN=0000400000000000C0F981C84B341D0C
hello world
Figure 11-23. System REXX: A simple example ES52G5.0
Notes:
/* REXX */
say "ADDRESS() returns '"address()"'"
say " "
PARSE VERSION lang ver dated datem datey
say "VERSION: Lang("lang") Version("ver") Date("dated datem datey")"
say " "
PARSE SOURCE s1 s2 s3 s4 s5 s6 s7 s8 s9
say "SOURCE: Env("s1")"
say " source2("s2") source3("s3") source4("s4")"
say " source5("s5") source6("s6") source7("s7")"
say " source8("s8") source9("s9")"
say " "
say "RexxVer executed on "translate(date(),'-',' ')
exit 0
Student Notebook
F AXR,REXXVER
EXECNAME=REXXVER REQTOKEN=0000400000000000D09CF395EF42505B
ADDRESS() returns 'TSO'
VERSION: Lang(REXX370) Version(3.48) Date(01 May 1992)
SOURCE: Env(TSO)
source2(COMMAND) source3(REXXVER) source4(REXXLIB)
source5(?) source6(REXXVER) source7(TSO)
source8(AXR) source9(?)
RexxVer executed on 18-Apr-2016
V10.1
Student Notebook
Uempty
Exploiting SYSREXX: AXREXX macro

• Invocation from the AXREXX macro
– SAY/TRACE output goes to the output data set specified by REXXOUTDSN on
the AXREXX invocation
• If not specified output goes to the console specified by CONSDATA (this is the
invoking console when the exec is initiated from an operator console)
– If CONSDATA is not specified, SAY/TRACE output is dropped
– AXRWTO/AXRMLWTO output goes to the Console specified by CONSDATA
Goes to the System Log if CONSDATA is not specified
• Invocation from the AXREXX macro
– Errors converted into return/reason codes
• More information is needed to debug problems
• REXX communicates with messages NOT codes
– Use of REXXDIAG keyword essential for SYNC=YES
• System REXX processing interrogates REXX messages and returns REXX and TSO
message ids
• In the case of a Syntax/Run-time error, returns the line where the error occurred
• Contents of REXXDIAG are reason code specific
Figure 11-24. Exploiting SYSREXX: AXREXX macro ES52G5.0
Notes:
Invocation from the AXREXX macro
- Diagnostics when failing to process an input/output argument or variable
• For example, in the REXXVARS AXREXX parm, MyVar is an output variable of type
AXRARGTypeUnSigned, but the variable contains non-numeric data
• Bad argument/variable number is stored in AXRARGLstEntryInError
- SYNC=YES option will suspend invoker until exec completes
• Do not use if the invoker cannot tolerate a delay (for example, in an MPF exit)
System REXX keeps track of IRX (REXX) and IKJ (TSO) messages.
In the event of a syntax error SYSREXX is able to return the message id corresponding to the
syntax error, the line number and possibly other REXX/TSO issued messages.
xxxx0828 Name: AXRExecSyntaxError
Meaning: A syntax error or some other run time error was encountered during the execution of a
REXX exec.
Student Notebook
Exploiting SYSREXX: An example with AXREXX

IEE115I 14.45.42 2010.347 ACTIVITY FRAME 1 F E SYS=SY1
JOBS M/S TS USERS SYSAS INITS ACTIVE/MAX VTAM OAS
00000 00005 00000 00026 00009 00000/00300 00003
CONSOLE CONSOLE NSW * A=0009 PER=NO SMC=000
PGN=N/A DMN=N/A AFF=NONE
CT=000.152S ET=132.523S
WKL=SYSTEM SCL=SYSTEM P=1
RGP=N/A SRVR=NO QSC=NO
ADDR SPACE ASTE=0F255240
DSPNAME=IEAM0015 ASTE=0C032780
Sample output for the Display JOBS,<jobname> command
Figure 11-25. Exploiting SYSREXX: An example with AXREXX ES52G5.0
Notes:
Sample invocation of AXREXX macro:
• Takes a jobname as input and issues the DISPLAY JOBS command to obtain the ASTE address
of the job (REXX exec name is the example below is called ‘GETASTE’)
- Typical of some applications that have been written in support of z/OSMF
• Invoke a command to fetch some piece of data to return to the invoker
• Many execs also invoke utility programs to obtain data in other ways for example, generating
data sets
V10.1
Student Notebook
Uempty • For example EREP can easily be invoked from an exec to format SYS1.LOGREG
GETASTE CSECT ,
GETASTE AMODE 31
GETASTE RMODE 31
*
* TITLE: GETASTE
*
* FUNCTION: OBTAIN THE ADDRESS OF MASTER'S ASTE BY INVOKING
* AN EXEC TO PARSE THE OUTPUT OF DISPLAY JOBS,*MASTER*.
* THE FOLLOWING EXEC TAKES A JOBNAME AS AN INPUT ARGUMENT
* AND SETS THE VARIABLE OUTASTE@.
* INPUT: InJobname (argument)
* OUTPUT: OutAste@ (Output variable)
*
* NUMERIC DIGITS 25
* ARG INJOBNAME
* MYCMD = 'D JOBS,' || STRIP(INJOBNAME);
* RESULT = AXRCMD(MYCMD,OUTPUTVAR.,10); /* Issue the
cmd to obtain info about the address space*/
* IF RESULT = 0 THEN
* DO;
* OUTASTE@ = ' '
* DO LINENUM = 1 TO OUTPUTVAR.0 WHILE(OUTASTE@=' ');
* PARSE VAR OUTPUTVAR.LINENUM 'ASTE=' OUTASTE@
* END;
* IF OUTASTE@ = ' ' THEN
* DO;
* MYRETCODE = 8;
* OUTASTE@ = 0;
* END;
* ELSE
* MYRETCODE = 0;
* END;
* ELSE
* DO;
* MYRETCODE = 12;
* OUTASTE@ = 0;
* END;
* EXIT MYRETCODE;
********************************************************************
BAKR 14,0
USING GETASTE,12
LR 12,15
MODID BR=YES
XC MYARGLST,MYARGLST CLEAR THE ARGLST HEADER
XC MYVARLST,MYVARLST CLEAR THE VARLST HEADER
XC MYARGEN1,MYARGEN1 CLEAR THE ARG ENTRY
Student Notebook
XC MYVAREN1,MYVAREN1 CLEAR THE VAR ENTRY

LA 2,MYARGLST
USING AXRARGLST,2
MVC AXRARGLSTID,MYAXRARGLSTACRO
LA 5,AXRARGLSTCURVER
ST 5,AXRARGLSTVER INITIALIZE THE VERSION
LA 5,KNUMARGS OBTAIN THE NUMBER OF ARGUMENTS
STH 5,AXRARGLSTNUMBER STORE THE NUMBER OF ARGUMENTS
DROP 2
USING AXRARGENTRY,2
LA 2,MYARGEN1 ADDRESSABILITY TO FIRST ARG ENTRY
LA 5,KMASTER
ST 5,AXRARGADDRLOW STORE ADDRESS OF JOBNAME (*MASTER*)
OI AXRARGINPUTFLGS1,AXRARGINPUT INDICATE INPUT ARG
LA 5,L'KMASTER OBTAIN LENGTH OF ARG
ST 5,AXRARGLENGTH STORE LENGTH OF ARG IN ENTRY
MVI AXRARGTYPE,AXRARGTYPECHAR STORE TYPE OF ARG
DROP 2
LA 2,MYVARLST
USING AXRARGLST,2
MVC AXRARGLSTID,MYAXRVARLSTACRO
LA 5,KNUMVARS OBTAIN THE NUMBER OF VARIABLES
STH 5,AXRARGLSTNUMBER STORE THE NUMBER OF VARIABLES
DROP 2
USING AXRARGENTRY,2
LA 2,MYVAREN1 ADDRESSABILITY TO 1ST VAR ENTRY
LA 5,OUTASTE@
ST 5,AXRARGADDRLOW STORE OUTPUT ARGUMENT
LA 5,OUTARGNAME
ST 5,AXRARGNAMEADDRLOW STORE ADDRESS OF NAME OF OUTPUT VAR
MVI AXRARGNAMELENGTH,L'OUTARGNAME
OI AXRARGINPUTFLGS1,AXRARGOUTPUT INDICATE OUTPUT VAR
MVI AXRARGTYPE,AXRARGTYPEHEXSTRING INDICATE HEX STRING
LA 5,L'OUTASTE@ OBTAIN LENGTH (IN BYTES)
SLL 5,1 MULT BY 2 - LENGTH IS IN HEX DIGITS (NOT BYTES)
ST 5,AXRARGLENGTH STORE LENGTH IN VAR ENTRY
DROP 2
AXREXX REQUEST=EXECUTE,NAME=KEXECNAME,REXXARGS=MYARGLST, *
REXXVARS=MYVARLST,REXXDIAG=MYAXRDIAG, *
REXXOUTDSN=KOUTDSN
LTR 15,15
JNZ FAILLABEL
USING AXRDIAG,2
V10.1
Student Notebook
Uempty LA 2,MYAXRDIAG
TM AXRDIAGFLGS1,AXRDIAGNOEXECRETCODE
JNZ FAILLABEL
L 15,AXRDIAGEXECRETCODE
LTR 15,15
JNZ FAILLABEL
* EVERYTHING LOOKS GOOD. PROCESS OUTASTE@ HERE
FAILLABEL DS 0H
* PERFORM ERROR CHECKING
* OUTASTE@ SHOULD CONTAIN MASTER'S ASTE ADDRESS
PR
KOUTDSN DC CL44'RONN.REXXLOG'
KNUMARGS EQU 1
KNUMVARS EQU 1
DS 0D
MYAXRARGLSTACRO DC C'ARGL'
MYAXRVARLSTACRO DC AL4(AXRVARLSTACRO)
KEXECNAME DC CL8'GETASTE '
KMASTER DC CL8'*MASTER*'
OUTARGNAME DC CL8'OUTASTE@'
MYARGLST DS CL(AXRARGLST_LEN)
MYARGEN1 DS CL(AXRARGENTRY_LEN)
MYVARLST DS CL(AXRARGLST_LEN)
MYVAREN1 DS CL(AXRARGENTRY_LEN)
MYAXRDIAG DS CL(AXRDIAG_LEN)
OUTASTE@ DS A
AXRZARG DSECT=YES,AXRARGLST=YES,AXRARGENTRY=YES,AXRDIAG=YES
END
Student Notebook
Best practices
• Create a REXXLIB concatenation and do NOT modify
SYS1.SAXREXEC
– Ensure your exec names do not start with the letters A-I
• Use the TSO=NO environment if possible
– Benefits: Use of a shared address space
– Downside: NO TSO Host commands, NO SYSCALL (POSIX) Host
commands.
• Single point of failure - a serious problem could cause a disruption to the
AXREXX service
• Coding conventions
– Use PROCEDURE/EXPOSE to ensure that changes made by a
procedure only affect variables introduced within the procedure
– Prefix global variables with a lower case g and constants with a k
Input and Ouput Args/Vars can be prefixed with In, Out or INOUT
• Variable naming conventions critical to program understanding
Figure 11-26. Best practices ES52G5.0
Notes:
Execs should free any obtained resources
• Since AXREXX is an authorized API, a level of trust is assumed since the REXX environments
are reused unless the request fails (AXREXX non-zero retcode)
• For TSO=YES requests, SYSREXX detects data sets left allocated by the exec and deallocates
them
• Use Signal Handles: NOVALUE, SYNTAX, HALT
- Return the value of SIGL and the return code to the AXREXX invoker
• Provide a consistent diagnostic strategy
- Pass back return codes and reason codes of the failing API to the AXREXX invoker and any
relevant messages
• Always specify the DIAG parm on AXREXX invocations
- Provides valuable diagnostic information
• Provide an argument to the exec to run with some level of REXX tracing active
- Specify RexxOutDsn or CONSDATA on AXREXX invocation to provide a destination for the
trace output
V10.1
Student Notebook
Uempty
SYSREXX ST command
• The STATUS sub-function results in a summary display of System REXX
environmental information:
@1SYSREXX ST
CPF: @1 (SYSPLEX) AXRUSER: AXR
TIMEINT: 30 TMP: NOT ENABLED
SUBSYSTEM: AXR TSO=YES ENABLED
IDLE: 4 MAX: 32
ASYNC: 0 SYNC: 0
UNTIMED: 0
IDLE: 1 MAX: 8
ASYNC: 0 SYNC: 0
UNTIMED: 0
Figure 11-27. SYSREXX ST command ES52G5.0
Notes:
Status function provides the following information:
• Time and date the AXR address space was started
• Parmlib member/s used at startup
• Command prefix used to identify console initiated REXX execs
• Scope of the command prefix
• Special user ID against which SYSREXX requests may be invoked
• Default timeout interval
• Number of queued REXX execs requests
• REXX worker tasks available to process REXX execs
- Number of tasks actively processing requests
- Number of idle tasks
- Total number of tasks (active+idle)
Student Notebook
- Maximum number of tasks that may be started

- Number of synchronous and asynchronous requests
- Number of untimed requests
• TSO server address spaces available to process REXX execs
- Number of address spaces actively processing requests
- Number of idle address spaces
- Total number of address spaces (active+idle)
- Maximum number of address spaces that may be started
- Number of synchronous and asynchronous requests
- Number of untimed requests
V10.1
Student Notebook
Uempty
SYSREXX ST Detail command

• The DETAIL parameter causes detailed information about executing REXX execs to
be displayed:
@1SYSREXX ST D
CPF: @1 (SYSPLEX) AXRUSER: AXR
TIMEINT: 30 TMP: NOT ENABLED
SUBSYSTEM: AXR TSO=YES ENABLED
IDLE: 4 MAX: 32
ASYNC: 0 SYNC: 0
UNTIMED: 0
IDLE: 0 MAX: 8
ASYNC: 1 SYNC: 0
UNTIMED: 0
Figure 11-28. SYSREXX ST Detail command ES52G5.0
Notes:
SYSREXX ST Detail command rerturns the following information:
• Name of the REXX exec
• Requester Jobname and ASID
• Type of request - TSO=N or TSO=Y
• Time limit for the request
• Unique request token associated with the request
• Execution Jobname, ASID and TCB address for TSO=Y requests
• CPU seconds currently used
• Current elapse time seconds
Student Notebook
REXX enhancements in z/OS V2.1 and later

• EXECIO enhanced to support I/O with RECFM=U, VS, VBS
• RECFM=U,VS,VBS support also added to callable I/O interface
• New TRAPMSG function allows IRX... messages, if issued from a
command invoked by the EXEC, to be captured by using OUTTRAP
• STORAGE function now supports 64-bit addresses for both reading
from and writing to storage
• Empty sequential data set can be part of a concatenation accessed by
EXECIO,CLIST I/O, PRINTDS if it is SMS managed
• LISTDSI enhanced (REXX and CLIST)
• RACF/NORACF operand
• Multi volume support
• Handles data sets with extended attributes
• Other smaller requirements
Figure 11-29. REXX enhancements in z/OS V2.1 and later ES52G5.0
Notes:
This chart describes the latest enhancements introduced in REXX since z/OS 2.1.
V10.1
Student Notebook
Uempty
References
• SH19-8160, Compiler and Library for REXX • ISPF Services Guide
User’s Guide and Reference – z/OS V1, SC19-3626
• SC24-6222, REXX/VM User’s Guide – z/OS V2, SC34-4819
• SC24-6221, REXX/VM Reference • ISPF Dialog Developer’s Guide and
• SA22-7790, TSO/E REXX Reference Reference
• SA22-7781-08, z/OS TSO/E CLISTs – z/OS V1, SC19-3619
• SA22-7786-12, z/OS TSO/E Messages – z/OS V2, SC34-4821
• SA22-7806, Using REXX and z/OS UNIX • ISPF Edit and Edit Macros
System Services – z/OS V1, SC19-3621
• SA22-7670, SDSF Operation and – z/OS V2, SC28-1312
Customization
• SC19-4051, DB2 Application Programming and
SQL Guide
• SA22-7594, MVS IPCS Commands
• SA22-7605, MVS Programming Authorized
Assembler Services Guide
• SA22-7682, Security Server RACF Macros and
Interfaces
Figure 11-30. References ES52G5.0
Notes:
Student Notebook
Checkpoint
1. Under which environment can you run a System REXX exec?
a. TSO/E
b. BATCH
c. CONSOLE
d. In a program, by using macro interface
2. A SYSREXX exec running isolated in a single address space, which can allocate
data sets, and does not support all TSO functionality, runs in which mode?
a. TSO=NO
b. TSO=YES
3. Name three SYSREXX major functions.
4. What is the name of the SYSREXX PARMLIB member?
5. True or False: EXECs by default run under AXRUSER ’s Security Environment.
Notes:
V10.1
Student Notebook
Uempty
Unit summary
• Use the console interface for System REXX execs
• List the major SYSREXX functions
Notes:
Student Notebook
V10.1
Student Notebook
AP
Appendix A. Checkpoint solutions
Unit 1, "Introduction"
Solutions for Figure 1-10, "Checkpoint," on page 1-11
Checkpoint solutions
1. True or False: REXX is available on all of IBM’s platforms.
The answer is true.
2. True or False: The REXX interpreter supports indentation, but the REXX compiler
does not.
The answer is False. REXX does not care about indentation.
3. True or False: REXX programs must be compiled, just like other languages.
The answer is False. REXX was originally designed as an interpreted language. The
compiler came later, and is optional.
4. A REXX exec is sometimes called a REXX program.

The answer is program.
5. True or False: Mike Cowlishaw named REXX after his dog.

The answer is False. Nice story, but it is not true. Cowlishaw originally called the
language Rex (with one ‘x’) because he liked the name. The second ‘x’ was added
later when it became an IBM product.
© Copyright IBM Corp. 1999, 2016 Appendix A. Checkpoint solutions A-1

Student Notebook
Unit 2, "Getting started with REXX"
Solutions for Figure 2-22, "Checkpoint (1 of 3)," on page 2-26
Checkpoint solutions (1 of 3)
1. True or False: In order to explicitly execute a REXX exec, it must be a
member of a data set concatenated to the //SYSPROC DD
concatenation.
The answer is false. In explicit execution you name the data set directly. It does
not have to be allocated to any DD concatenation.
2. In order to implicitly execute a REXX exec, it must be a member of a

data set concatenated to the //SYSEXEC DD or //SYSPROC DD
concatenation.
The answers are //SYSEXEC and //SYSPROC.
3. You can place your execs in a CLIST library in the //SYSPROC DD

concatenation.
The answer is //SYSEXEC, only supports REXX libraries.
4. Comments begin with /* and end with */.

The answers are /* and */.
A-2 z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016
V10.1
Student Notebook
AP Solutions for Figure 2-23, "Checkpoint (2 of 3)," on page 2-27
5. True or False: Indentation is required by the REXX compiler, but is not
required by the REXX interpreter.
The answer is False. REXX does not care about indentation.
Indentation is strictly to make execs more readable for us.
6. True or False: Variable names in REXX are case sensitive and are of
unlimited length.
The answer is False. Variable names are not case sensitive, and can
be up to 250 characters long.
7. True or False: Unlike languages like C, COBOL, and PL/1, REXX has
no concept of data types.
The answer is true.
8. True or False: Literals must be enclosed within single quotes.

The answer is False. Literals can be enclosed within single or double
quotes.

Student Notebook
9. What will the following code fragment produce?
var1 = ‘Mon’
var2 = ‘day’
Say var1var2
The answer is VAR1VAR2. Uppercase. The interpreter cannot tell where the
variable var1 ends and var2 begins, so var1var2 is a separate uninitialized
variable.
10. The Parse Pull instruction reads input data from the keyboard.
The answer is keyboard.
11. The Parse Arg instruction reads input data from the command line.
The answer is command line.
V10.1
Student Notebook
AP Unit 3, "Programming in REXX"
1. What are the four “not equal” comparison operators?
The answers are \= ¬= <> >< .
2. What are the five types of loop control?

The answers are Do While, Do Until, Do with a loop control variable,
Do a specific number of times, and Do Forever.
3. True or False: In REXX, 0 means True, and 1 means False.

The answer is False. In REXX, 1 means True and 0 means False.
4. True or False: In REXX, string comparisons are always strict

comparisons.
The answer is False. Strict comparisons are always string
comparisons, but the converse is not true.

Student Notebook
5. Numeric comparisons are performed when both terms being
compared are recognized by REXX as numbers, and the comparison
type is normal (not strict).
The answer is both terms being compared are recognized by REXX as
numbers, and the comparison type is normal (not strict).
6. The comparison operator >= or ¬< or \< means Greater Than or Equal
To.
The answer is >= or ¬< or \< .
7. The Do Until loop is always executed at least one time.

The answer is at least one time.
8. True or False: Logical operators are evaluated after comparison

operators.
The answer is true.
V10.1
Student Notebook
Do i = 0.1 To 5 By 0.4
Say “Hello”
End i
The answer is The loop will execute 13 times. The variable will increment
through the values 0.1, 0.5, 0.9, 1.3, 1.7, 2.1, 2.5, 2.9, 3.3, 3.7, 4.1, 4.5, and 4.9.
When the value becomes 5.3, the loop will end.
10. In a Select construct, if no logical expression is found to be true, what

will happen?
The answer is the instructions following the Otherwise keyword will be
executed. If no Otherwise keyword exists, a run time error will occur and the
exec will fail.

Do i = 1
...some instructions...
End i
The answer is we have no way of knowing. It depends on the instructions inside
the loop.

Student Notebook
Unit 4, "Functions and subroutines"
1. What is the purpose of a function?
The answer is to return a value to the calling program.
2. An internal subprocedure should be preceded by a Return

or Exit keyword instruction.
The answers are Return and Exit.
3. Internal subprocedures can use REXX naming rules, but

external ones must conform to PDS member naming rules.
The answers are REXX and PDS member.
4. True or False: When returning from a function, control is

returned to the next instruction following the function call.
The answer is False. Control is returned to the same instruction that
contained the function call.
V10.1
Student Notebook
5. True or False: Subroutines do not have to return a value to the calling
program.
The answer is true.
6. True or False: All functions can be called as subroutines.

The answer is true.
7. True or False: All subroutines can be called as functions.

The answer is False. A subroutine that does not return a value to the caller
cannot be called as a function.
8. You can pass up to 20 arguments to a subprocedure.

The answer is 20.
9. REXX searches for internal subprocedures first.

The answer is internal.

Student Notebook
Unit 5, "Debugging and error handling"
1. True or False: REXX instructions set return codes.
The answer is false. Host commands set return codes, not REXX instructions.
2. Every exec should begin with a comment, containing the word REXX.
The answer is comment, containing the word REXX.
3. True or False: If you code a Signal instruction, you must code a label for the
condition trap.
The answer is false. The Signal instruction does not require a label to be coded. If the
error condition occurs, then REXX will search for the label, and produce an error
message if the label is not found.
4. The REXX special variable rc contains the return code from the last host
command that was issued.
The answer is the return code from the last host command that was issued.
5. The REXX special variable sigl contains the line number where the condition
trap was sprung.
The answer is the line number where the condition trap was sprung.
6. What does Trace ?R do?

The answer is places the exec into interactive Trace Results mode.
V10.1
Student Notebook
AP Unit 6, "Executing host commands"
1. What is a host command environment?
The answer is a host command environment is the external execution
environment to which REXX will pass instructions that it does not recognize.
2. True or False: The default host command environment for every

address space is TSO.
The answer is false. The host command environment for an MVS address space
is MVS.
3. The instruction used to change host command environments is called

address.
The answer is address.
4. True or False: If you attempt to switch to a nonexistent host command

environment, your REXX program will abend.
The answer is true.

Student Notebook
5. True or False: ISPF provides a very useful set of services for
both batch and online REXX execs.
The answer is true.
6. True or False: You can use REXX to write your own ISPF edit
commands.
The answer is true.
7. True or False: Anyone can use the CONSOLE host

command environment.
The answer is false. Only those with proper security system
authority can use the CONSOLE host command environment.
V10.1
Student Notebook
AP Unit 7, "Compound variables and the data stack"
1. Compound variables consist of two components, the stem and the tail.
The answers are stem and tail.
2. True or False: Each compound variable can have only one tail.
The answer is true.
3. A compound variable tail may be one of three items: a constant, a

simple variable, or a null.
The answers are constant, simple variable, and null.
4. True or False: If you do not initialize the stem, then an uninitialized

compound variable will assume as its value its own name in
uppercase.
The answer is true.

Student Notebook
5. In the following OUTTRAP() function, which variable will hold
the number of records of command output?
X = OUTTRAP(‘line.’,’*’,’NOCONCAT’)
The answer is Line.0.
6. True or False: Data records can be removed from either the

top or the bottom of the data stack.
The answer is false. Data records can only be removed from the top
of the data stack.
7. The instruction to remove one record from the top of the

stack is Parse Pull.
The answer is Parse Pull.
V10.1
Student Notebook
8. True or False: When the QELEM command sets a return
code of zero, you know the data stack is empty.
The answer is false. When the Queued() function returns a value of
zero, then the stack is empty.
9. The Push instruction stacks records LIFO (Last In First Out).

The answer is LIFO (Last In First Out).
10. The Queue instruction stacks records FIFO (First In First

Out).
The answer is FIFO (First In First Out).

Student Notebook
Unit 8, "Reading and writing data sets in REXX"
1. True or False: The EXECIO command will work with sequential data
sets, members of partitioned data sets, and VSAM data sets.
The answer is false. EXECIO will not work with VSAM data sets.
2. True or False: You can write to whatever line you wish with the
Lineout() function.
The answer is false. Lineout() will only write to the current write position.
3. The default EXECIO read parameter is FIFO.

The answer is FIFO.
4. How many characters can you write to a persistent stream with a

single Charout() function?
The answer is 32760.
V10.1
Student Notebook
5. True or False: You can read from whatever character position you
wish with the Charin() function.
The answer is false. The Charin() function reads from the next read position by
default, or you can reset the read pointer to the beginning of the input stream.
6. True or False: A stream must be opened in order to read from it or

write to it.
The answer is true.
7. Is the Stream() function required in order to open a stream?

The answer is no. The Stream() function is used to name and open a stream,
but the Charin(), Charout(), Linein(), and Lineout() functions will open streams
themselves.
8. Can you use an asterisk to represent the number of lines to be written

with EXECIO?
The answer is technically yes, but you should avoid it.

Student Notebook
Unit 9, "The parse instruction"
1. Which source of input to the parse instruction requires the
keyword “With”?
The answer is Parse Value.
2. True or False: The Arg instruction is shorthand for Parse Arg.

The answer is false. Arg is shorthand for Parse Upper Arg.
3. True or False: The Var instruction is shorthand for Parse

Upper Var.
The answer is false. There is no “Var” instruction.
4. How can I find out how my REXX program was invoked?

The answer is Parse Source.
V10.1
Student Notebook
fragment?
Parse Var input 6 var1 var2 ' d'
var1 = ’is’
var2 = ’the’
The answers are var1 = ’is’ and var2 = ’the’.

fragment?
Parse Var input var1 'is' var2 . 13 var3 +4
var1 = ’Th’
var2 = ’is’
var3 = ’data’
The answers are var1 = ’Th’, var2 = ’is’, and var3 = ’data’.

Student Notebook
fragment?
Parse Var input var1 var2 var3 8 . 'a' var4 '.' -4 ,
var5 +2
var1 = ’This’
var2 = ’is’
var3 = ’’
var4 = ’ta’
var5 = ’da’
The answers are var1 = ’This’, var2 = ’is’, var3 = ’’, var4 = ’ta’, and
var5 = ’da’.
V10.1
Student Notebook
AP Unit 10, " Using REXX: REXX compiler, REXX in batch, MVS
console commands"
1. True or False: The REXX interpreter detects syntax errors in all parts
of a REXX program.
The answer is false. The interpreter will stop as soon as an error is detected. It
also does not check instructions that are not executed.
2. In order to execute compiled exec code, the data set containing the
compiled code should be allocated to the SYSEXEC ddname.
The answer is SYSEXEC.
3. Can the REXX compiler create both compiled exec code and object
code at the same time?
The answer is yes, it can.
4. True or False: The cross reference listing is included in the compiler

listing by default.
The answer is false. You must specify the XREF or XREF(S) option to include
the cross reference listing.

Student Notebook
5. When running REXX execs in batch jobs, what is the purpose of the
following ddnames:
SYSTSPRT
SYSPRINT
SYSTSIN
SYSEXEC
The answers are SYSTSPRT is where program output is sent (like REXX Say
instructions), SYSPRINT is where system messages are sent, SYSTSIN is the
input stream, where input to the program comes from (like REXX Parse Pulls),
and SYSEXEC is the REXX library concatenation.
6. True or False: Anyone can issue the TSO/E CONSPROF command.

The answer is false. The CONSPROF command requires security system
authorization.
7. True or False: You do not have to define a console profile in order to

execute MVS operator commands from within a REXX exec.
The answer is true. But it is more common to do so.
V10.1
Student Notebook
8. In order to execute MVS operator commands from within a
REXX exec and capture the responses to those commands,
you must define a console profile. Why?
The answer is because otherwise the responses from the commands
will be displayed at the console screen, and will not be available to
the GETMSG() function.
9. What is the purpose of the CART?

The answer is to associate a token (or value) with the commands
being executed and the responses to those commands.
10. What function would you use to retrieve system messages

from the message table in memory?
The answer is GETMSG().

Student Notebook
Unit 11, "System REXX"
1. Under which environment can you run a System REXX exec?
a. TSO/E
b. BATCH
c. CONSOLE
d. In a program, by using macro interface
The answers are CONSOLE and in a program, by using macro interface.
2. A SYSREXX exec running isolated in a single address space, which can allocate data
sets, and does not support all TSO functionality, runs in which mode?
a. TSO=NO
b. TSO=YES
The answer is TSO=YES.
3. Name three SYSREXX major functions.

The answers are AXRCMD, AXRWTO, AXRMLWTO, AXRWAIT, and AXRINFO.
4. What is the name of the SYSREXX PARMLIB member?

The answer is AXR00.
5. True or False: EXECs by default run under AXRUSER ’s Security Environment.

The answer is false.
V10.1
Student Notebook
AP
Appendix B. REXX taxonomy and REXX built-in
functions
Expressions
Expressions in REXX are a general way to combine data in different ways to produce some result.
They consist of one or more of the following:
• Variables
- Symbols which represent some other value
• Literals
- Strings delimited by quotation marks, taken at face value. In other words, constants.
• Functions
- A string immediately followed by a left parenthesis, with zero or more arguments contained
within the parentheses, like function(arg1, arg2,…)
• Other operator characters
- Arithmetic, concatenation, comparison, or logical operators
REXX statement types

There are five types of instructions found in REXX execs. Their types and order of precedence is:
• Null clause
- Blank lines or comments
• Labels
- Symbol followed by a colon used as a location marker in the program
• Assignment instructions
- Clause of the form variable = expression
• Keyword instructions
- Clause whose first keyword is one of the recognized REXX instruction names, such as Say,
Do, If, Select, Exit, and so on.
• Commands
- Clause whose first keyword is not recognized by REXX, therefore the evaluated expression
is passed by REXX to an external execution environment
© Copyright IBM Corp. 1999, 2016 Appendix B. REXX taxonomy and REXX built-in functions B-1
Student Notebook
REXX operator order of precedence

Operators are evaluated left to right, in the following order:
Prefix operators
+ -¬\
Parenthetical sub-expressions
(sub-expression)
Exponentiation
**
Multiplication and division
* / % //
Addition and subtraction
+ -
Concatenation
(blank) || (abuttal)
Comparison
= ¬= \= <> >< > < >= ¬< \< <= ¬> \>
== ¬== \== >> << >>= ¬<< \<< <<= ¬>> \>>
Logical and
&
Logical or, exclusive or
| &&
REXX built-in functions

ABBREV (Abbreviation) Determines whether a substring begins a string
ABS (Absolute Value) Returns the absolute value of a number
ADDRESS Returns the name of the current command environment
ARG (Argument) Returns an argument string or information about argument strings
BITAND (Bit by Bit AND) Returns the result of logically ANDing string1 and string2
BITOR (Bit by Bit OR) Returns the result of logically inclusive ORing string1 and string2
BITXOR(Bit by Bit Exclusive OR)
Returns the result of logically excl. ORing string1 and string2
B2X (Binary to Hexadecimal)
Returns the hexadecimal equivalent of a binary string
CENTER/CENTRE Returns a string with its string argument centered in it
B-2 z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016
V10.1
Student Notebook
AP COMPARE Compares to strings for equality or returns first column they differ
CONDITION Returns information about a trapped condition
COPIES Returns specified number of copies of its string argument
C2D (Character to Decimal)
Returns the decimal value of a string's binary representation
C2X (Character to Hex) Returns, in character format, a hexadecimal representation of a string
DATATYPE Returns the data type of its string argument
DATE Returns the system date in the format specified
DELSTR (Delete String) Returns a substring from a string
DELWORD (Delete Word) Removes a blank-delimited string (word) from a string
DIGITS Returns the current setting of NUMERIC DIGITS
D2C (Decimal to Character)
Returns, in character format, a decimal number converted to binary
D2X (Decimal to Hexadecimal)
Returns the hexadecimal equivalent of a decimal number
ERRORTEXT Returns the REXX error message associated with an error number
FORM Returns the current setting of NUMERIC FORM
FORMAT Returns a rounded and formatted number
FUZZ Returns the current setting of NUMERIC FUZZ
INSERT Inserts one string into another
LASTPOS (Last Position) Returns the position of the last occurrence of a string in another string
LEFT Returns a string of a specified length containing the leftmost portion
of a string
LENGTH Returns the length of a string
MAX (Maximum) Returns the largest number from a list of numbers
MIN (Minimum) Returns the smallest number from a list of numbers
OVERLAY Writes a string onto another string starting at a specified position
POS (Position) Returns the position of one string within another string
QUEUED Returns the number of lines in the external data queue (TSO/E data
stack)
RANDOM Returns a random whole number
REVERSE Returns the reverse of a string
RIGHT Returns a string of a specified length containing the rightmost portion
of a string
SIGN Returns a number that indicates a number's sign (1/positive,
-1/negative, or 0/zero).
Student Notebook
SOURCELINE Returns the source of a line number within the program

SPACE Formats blank-delimited words in a string
STRIP Removes leading and / or trailing characters from a string (usually
blanks)
SUBSTR (Substring) Returns a substring of specified length and position from within a
string
SUBWORD Returns a substring of words from within a string of words
SYMBOL Returns information about a specified symbol
TIME Returns the system time in the format specified
TRACE Returns trace settings currently in effect and, optionally, alters the
setting
TRANSLATE Returns a string with translated characters from an input string
TRUNC (Truncate) Returns the integer part of number and a specified number of decimal
places
VALUE Returns the value of a specified symbol and, optionally, assigns it a
new value
VERIFY Compares two strings to see whether they contain the same
characters
WORD Returns the specified blank-delimited string (word) within a string
WORDINDEX Returns the position of a specified blank-delimited string (word)
WORDLENGTH Returns the length of a specified blank-delimited string (word) within a
string
WORDPOS (Word Position) Returns the word number of a substring in its string
WORDS Returns the number of blank-delimited strings (words) within a string
XRANGE (Hexadecimal Range)
Returns a string that spans all hex values in a specified range
X2B (Hexadecimal to Binary)
Returns the binary string equivalent of a hexadecimal string
X2C (Hexadecimal to Character)
Returns the character equivalent of a hexadecimal string
X2D (Hexadecimal to Decimal)
Returns the decimal equivalent of a hexadecimal string
There are six other non-SAA built-in functions that TSO/E provides: EXTERNALS, FIND, INDEX,
JUSTIFY, LINESIZE, and USERID. If you plan to write REXX programs that run on other SAA
environments, note that these functions are not available to all the environments.
EXTERNALS Returns the number of elements in the terminal input buffer (always 0
for TSO/E)
V10.1
Student Notebook
AP FIND Returns the word number of a substring in its string (for SAA use
WORDPOS)
INDEX Returns the position of one string within another string (for SAA use
POS)
JUSTIFY Returns a formatted string from blank-delimited words to justify both
margins
LINESIZE Returns the current terminal line width minus 1
USERID Returns the TSO/E user ID
TSO/E external functions

GETMSG Used to retrieve messages from a TSO/E CONSOLE session into
variables
LISTDSI Returns information about a data set into variables
MSG Returns / sets the current value of displaying TSO/E messages
MVSVAR Returns information about a specified MVS system variable
OUTTRAP Used to trap TSO/E command output and store that output into
variables
PROMPT Returns / sets the current value of TSO/E command prompting within
an exec
SETLANG Returns / sets a code that indicates the language of displayed REXX
messages
STORAGE Returns data of a specified length from a specified address in storage
SYSCPUS Returns information in a stem variable about online CPUs
SYSDSN Returns information indicating whether a data set exists and is
available for use
SYSVAR Returns information about a specified system variable
You can use the MVSVAR, SETLANG, STORAGE, and SYSCPUS external functions in REXX
execs that run in any address space, TSO/E and non-TSO/E.
You can use the other external functions only in REXX execs that run in the TSO/E address space.
Student Notebook
V10.1
backpg
Back page

REXX

Uploaded by

Document Information

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

Uploaded by

Copyright:

Available Formats

V10.

IBM Training Front cover

z/OS REXX Programming Workshop

June 2016 edition

© Copyright International Business Machines Corporation 1999, 2016.

Course description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Unit 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Unit 2. Getting started with REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

© Copyright IBM Corp. 1999, 2016 Contents iii

Unit 3. Programming in REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1

Unit 4. Functions and subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1

iv z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016

TOC Why should we code functions/subroutines? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19

Unit 5. Debugging and error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Unit 6. Executing host commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

© Copyright IBM Corp. 1999, 2016 Contents v

CONSOLE host command environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-26

Unit 7. Compound variables and the data stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1

vi z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016

TOC DROPBUF command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-32

Unit 8. Reading and writing data sets in REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Unit 9. The parse instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

© Copyright IBM Corp. 1999, 2016 Contents vii

Period place holder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-11

TOC Console session security requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38

Unit 11. System REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

Appendix A. Checkpoint solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Appendix B. REXX taxonomy and REXX built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . B-1

© Copyright IBM Corp. 1999, 2016 Contents ix

x z/OS REXX Programming Workshop © Copyright IBM Corp. 1999, 2016

© Copyright IBM Corp. 1999, 2016 Trademarks xi

Duration: 4.5 days

© Copyright IBM Corp. 1999, 2016 Course description xiii

© Copyright IBM Corp. 1999, 2016 Agenda xv

What this unit is about

What you should be able to do

How you will check your progress

© Copyright IBM Corp. 1999, 2016 Unit 1. Introduction 1-1

© Copyright IBM Corporation 1999, 2016

Figure 1-1. Unit objectives ES52G5.0

Origins and history of REXX

© Copyright IBM Corporation 1999, 2016

Figure 1-2. Origins and history of REXX ES52G5.0

© Copyright IBM Corp. 1999, 2016 Unit 1. Introduction 1-3

© Copyright IBM Corporation 1999, 2016

Figure 1-3. Platforms ES52G5.0

© Copyright IBM Corporation 1999, 2016

Figure 1-4. Concepts of REXX ES52G5.0

© Copyright IBM Corp. 1999, 2016 Unit 1. Introduction 1-5

© Copyright IBM Corporation 1999, 2016

Figure 1-5. Features of REXX ES52G5.0

Uses for REXX on z/OS

© Copyright IBM Corporation 1999, 2016

Figure 1-6. Uses for REXX on z/OS ES52G5.0

© Copyright IBM Corp. 1999, 2016 Unit 1. Introduction 1-7

Interpreted versus compiled

© Copyright IBM Corporation 1999, 2016

Figure 1-7. Interpreted versus compiled ES52G5.0

© Copyright IBM Corporation 1999, 2016

Figure 1-8. Learning REXX ES52G5.0

© Copyright IBM Corp. 1999, 2016 Unit 1. Introduction 1-9

Simple REXX program

/* Rexx exec to introduce Rexx */

© Copyright IBM Corporation 1999, 2016