IBM TSO/E REXX User Manual

z/OS

TSO/E
REXX User’s Guide



SA22-7791-00

z/OS

TSO/E
REXX User’s Guide



SA22-7791-00

Note

Before using this information and the product it supports, be sure to read the general information under “Appendix D.
Notices” on page 205.

First Edition, March 2001

This edition applies to Version 1 Release 1 of z/OS (5694-A01) and to all subsequent releases and modifications
until otherwise indicated in new editions.

Order publications through your IBM representative or the IBM branch office serving your locality. Publications are
not stocked at the address below.

IBM welcomes your comments. A form for readers’ comments may be provided at the back of this publication, or you
may address your comments to the following address:

International Business Machines Corporation
Department 55JA, Mail Station P384
2455 South Road
Poughkeepsie, NY 12601-5400
United States of America

FAX (United States & Canada): 1+845+432-9405
FAX (Other Countries):

Your International Access Code +1+845+432-9405

IBMLink (United States customers only): IBMUSM10(MHVRCFS)
Internet e-mail: [e-mail]
World Wide Web: http://www.ibm.com/servers/eserver/zseries/zos/webqs.html

If you would like a reply, be sure to include your name, address, telephone number, or FAX number.

Make sure to include the following in your comment or note:

v Title and order number of this book
v Page number or topic related to your comment

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.

© Copyright International Business Machines Corporation 1988, 2001. All rights reserved.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents

Figures............................ix

Tables ............................xi

About This Book .......................xiii

Who Should Use This Book ....................xiii

How This Book Is Organized ....................xiii

Terminology .........................xiii

Purpose of Each Chapter ....................xiv

Examples ..........................xiv

Exercises ..........................xiv

Where to Find More Information ..................xiv

Accessing Licensed Books on the Web ...............xiv

Using LookAt to Look Up Message Explanations ...........xv

Part 1. Learning the REXX Language......................1

Chapter 1. Introduction ......................3

What is REXX? .........................3

Features of REXX ........................3

Ease of use .........................3

Free format .........................3

Convenient built-in functions ...................4

Debugging capabilities .....................4

Interpreted language ......................4

Extensive parsing capabilities ...................4

Components of REXX.......................4

The SAA Solution ........................4

Benefits of Using a Compiler ....................5

Improved Performance .....................5

Reduced System Load .....................5

Protection for Source Code and Programs ..............6

Improved Productivity and Quality .................6

Portability of Compiled Programs..................6

SAA Compliance Checking ....................6

Chapter 2. Writing and Running a REXX Exec .............7

Before You Begin ........................7

What is a REXX Exec? ......................8

Syntax of REXX Instructions ....................9

The Character Type of REXX Instructions ..............9

The Format of REXX Instructions .................10

Types of REXX Instructions ...................12

Execs Using Double-Byte Character Set Names ............14

Running an Exec ........................16

Running an Exec Explicitly ...................16

Running an Exec Implicitly ...................17

Interpreting Error Messages ....................19

Preventing Translation to Uppercase .................20

From Within an Exec......................20

As Input to an Exec ......................20

Passing Information to an Exec ...................21

Using Terminal Interaction ....................21

© Copyright IBM Corp. 1988, 2001 iii

Specifying Values when Invoking an Exec ..............22

Preventing Translation of Input to Uppercase .............23

Passing Arguments ......................24

Chapter 3. Using Variables and Expressions .............25

Using Variables.........................25

Variable Names .......................26

Variable Values........................27

Exercises - Identifying Valid Variable Names .............27

Using Expressions .......................28

Arithmetic Operators ......................28

Comparison Operators .....................30

Logical (Boolean) Operators ...................32

Concatenation Operators ....................34

Priority of Operators ......................35

Tracing Expressions with the TRACE Instruction ............37

Tracing Operations ......................37

Tracing Results........................38

Chapter 4. Controlling the Flow Within an Exec............41

Using Conditional Instructions ...................42

IF/THEN/ELSE Instructions ...................42

Nested IF/THEN/ELSE Instructions ................43

SELECT/WHEN/OTHERWISE/END Instruction ............44

Using Looping Instructions ....................47

Repetitive Loops .......................47

Conditional Loops .......................52

Combining Types of Loops ...................55

Nested DO Loops .......................55

Using Interrupt Instructions ....................56

EXIT Instruction .......................57

CALL/RETURN Instructions ...................57

SIGNAL Instruction ......................58

Chapter 5. Using Functions ...................61

What is a Function? .......................61

Example of a Function .....................62

Built-In Functions ........................63

Arithmetic Functions ......................63

Comparison Functions .....................63

Conversion Functions .....................64

Formatting Functions......................64

String Manipulating Functions ..................64

Miscellaneous Functions ....................65

Testing Input with Built-In Functions ................66

Chapter 6. Writing Subroutines and Functions ............69

What are Subroutines and Functions? ................69

When to Write Subroutines vs. Functions ...............70

Writing a Subroutine .......................70

Passing Information to a Subroutine ................72

Receiving Information from a Subroutine ..............75

Writing a Function ........................77

Passing Information to a Function .................79

Receiving Information from a Function ...............83

Summary of Subroutines and Functions................83

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

Chapter 7. Manipulating Data ...................85

Using Compound Variables and Stems ................85

What is a Compound Variable? ..................85

Using Stems .........................86

Parsing Data..........................87

Instructions that Parse .....................88

Ways of Parsing .......................89

Parsing Multiple Strings as Arguments ...............92

Part 2. Using REXX .............................95

Chapter 8. Entering Commands from an Exec ............97

Types of Commands .......................97

Issuing TSO/E Commands from an Exec ...............98

Using Quotations Marks in Commands ...............98

Using Variables in Commands ..................99

Causing Interactive Commands to Prompt the User ..........100

Invoking Another Exec as a Command...............100

Issuing Other Types of Commands from an Exec ............101

What is a Host Command Environment? ..............101

Changing the Host Command Environment .............106

Chapter 9. Diagnosing Problems Within an Exec ...........111

Debugging Execs .......................111

Tracing Commands with the TRACE Instruction ...........111

Using REXX Special Variables RC and SIGL ............112

Tracing with the Interactive Debug Facility .............113

Chapter 10. Using TSO/E External Functions ............119

TSO/E External Functions ....................119

Using the GETMSG Function ..................120

Using the LISTDSI Function ..................120

Using the MSG Function ....................122

Using the MVSVAR Function ..................123

Using the OUTTRAP Function ..................123

Using the PROMPT Function ..................124

Using the SETLANG Function ..................125

Using the STORAGE Function..................126

Using the SYSCPUS Function ..................126

Using the SYSDSN Function ..................126

Using the SYSVAR Function ..................127

Additional Examples ......................130

Function Packages .......................133

Search Order for Functions ...................134

Chapter 11. Storing Information in the Data Stack ..........135

What is a Data Stack? .....................135

Manipulating the Data Stack ...................136

Adding Elements to the Data Stack ................136

Removing Elements from the Stack ................137

Determining the Number of Elements on the Stack ..........137

Processing of the Data Stack ...................139

Using the Data Stack ......................140

Passing Information Between a Routine and the Main Exec .......140

Passing Information to Interactive Commands ............142

Issuing Subcommands of TSO/E Commands ............142

Contents v

Creating a Buffer on the Data Stack.................142

Creating a Buffer with the MAKEBUF Command ...........143

Dropping a Buffer with the DROPBUF Command ...........144

Finding the Number of Buffers with the QBUF Command ........144

Finding the Number of Elements In a Buffer .............145

Protecting Elements in the Data Stack ................147

Creating a New Data Stack with the NEWSTACK Command ......148

Deleting a Private Stack with the DELSTACK Command ........149

Finding the Number of Stacks ..................149

Chapter 12. Processing Data and Input/Output Processing .......153

Types of Processing ......................153

Dynamic Modification of a Single REXX Expression ...........153

Using the INTERPRET Instruction ................153

Using EXECIO to Process Information to and from Data Sets .......154

When to Use the EXECIO Command ...............154

Using the EXECIO Command ..................154

Return Codes from EXECIO ..................159

When to Use the EXECIO Command ...............159

Chapter 13. Using REXX in TSO/E and Other MVS Address Spaces ...171

Services Available to REXX Execs .................171

Running Execs in a TSO/E Address Space ..............173

Running an Exec in the Foreground................173

Running an Exec in the Background ...............176

Running Execs in a Non-TSO/E Address Space ............177

Using an Exec Processing Routine to Invoke an Exec from a Program 177

Using IRXJCL to Run an Exec in MVS Batch ............178

Using the Data Stack in TSO/E Background and MVS Batch ......180

Summary of TSO/E Background and MVS Batch ............180

CAPABILITIES .......................180

REQUIREMENTS ......................181

Defining Language Processor Environments .............181

What is a Language Processor Environment? ............181

Customizing a Language Processor Environment ...........182

Part 3. Appendixes .............................183

Appendix A. Allocating Data Sets .................185

What is Allocation? .......................185

Where to Begin ........................186

Preliminary Checklist ......................186

Checklist #1: Creating and Editing a Data Set Using ISPF/PDF ......187

Checklist #2: Creating a Data Set with the ALLOCATE Command......190

Checklist #3: Writing an Exec that Sets up Allocation to SYSEXEC .....191

Checklist #4: Writing an Exec that Sets up Allocation to SYSPROC .....192

Appendix B. Specifying Alternate Libraries with the ALTLIB Command 195

Specifying Alternative Exec Libraries with the ALTLIB Command ......195

Using the ALTLIB Command ..................195

Stacking ALTLIB Requests ...................196

Using ALTLIB with ISPF ....................196

Examples of the ALTLIB Command .................196

Appendix C. Comparisons Between CLIST and REXX .........197

Accessing System Information ...................198

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

Controlling Program Flow ....................199

Debugging ..........................200

Execution ..........................200

Interactive Communication ....................201

Passing Information.......................201

Performing File I/O .......................202

Syntax ...........................202

Using Functions ........................203

Using Variables ........................203

Appendix D. Notices ......................205

Programming Interface Information .................207

Trademarks..........................207

Bibliography .........................209

TSO/E Publications .......................209

Related Publications ......................209

Index ............................211

Contents vii

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

Figures

1. EXECIO Example 1 .............................164

2. EXECIO Example 2 .............................164

3. EXECIO Example 3 .............................165

4. EXECIO Example 4 .............................165

5. EXECIO Example 5 .............................166

6. EXECIO Example 5 (continued) .........................167

7. EXECIO Example 6 .............................168

8. EXECIO Example 6 (continued) .........................169

9. EXECIO Example 6 (continued) .........................170

© Copyright IBM Corp. 1988, 2001 ix

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

Tables

1. Language Codes for SETLANG Function That Replace the Function Call .........125

© Copyright IBM Corp. 1988, 2001 xi

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

About This Book

This book describes how to use the TSO/E Procedures Language MVS/REXX
processor (called the language processor) and the REstructured eXtended eXecutor
(REXX) language. Together, the language processor and the REXX language are
known as TSO/E REXX. TSO/E REXX is the implementation of the Systems
Application Architecture (SAA) Procedures Language on the MVS system.

Who Should Use This Book

This book is intended for anyone who wants to learn how to write REXX programs.
More specifically, the audience is programmers who may range from the
inexperienced to those with extensive programming experience, particularly in
writing CLISTs for TSO/E. Because of the broad range of experience in readers,
this book is divided into two parts.

v Part 1. Learning the REXX Language is for inexperienced programmers who are

somewhat familiar with TSO/E commands and have used the Interactive System

Productivity Facility/Program Development Facility (ISPF/PDF) in TSO/E.

Programmers unfamiliar with TSO/E should first read the z/OS TSO/E Primer.

Experienced programmers new to REXX can also read this section to learn the

basics of the REXX language.
v Part 2. Using REXX is for programmers already familiar with the REXX language

and experienced with the workings of TSO/E. It describes more complex aspects

of the REXX language and how they work in TSO/E as well as in other MVS

address spaces.

If you are a new programmer, you might want to concentrate on the first part. If you
are an experienced TSO/E programmer, you might want to read the first part and
concentrate on the second part.

How This Book Is Organized

In addition to the two parts described in the preceding paragraphs, there are three
appendixes at the end of the book.

v “Appendix A. Allocating Data Sets” on page 185 contains checklists for the tasks

of creating and editing a data set and for allocating a data set to a system file.
v “Appendix B. Specifying Alternate Libraries with the ALTLIB Command” on

page 195 describes using the ALTLIB command.
v “Appendix C. Comparisons Between CLIST and REXX” on page 197 contains

tables that compare the CLIST language with the REXX language.

Terminology

Throughout this book a REXX program is called an exec to differentiate it from
other programs you might write, such as CLISTs. The command to run an exec in
TSO/E is the EXEC command. To avoid confusion between the two, this book uses
lowercase and uppercase to distinguish between the two uses of the term "exec".
References to the REXX program appear as exec and references to the TSO/E
command appear as EXEC.

© Copyright IBM Corp. 1988, 2001 xiii

Purpose of Each Chapter

At the beginning of each chapter is a statement about the purpose of the chapter.
Following that are headings and page numbers where you can find specific
information.

Examples

Throughout the book, you will find examples that you can try as you read. If the
example is a REXX keyword instruction, the REXX keyword is in uppercase.
Information that you can provide is in lowercase. The following REXX keyword
instruction contains the REXX keyword SAY, which is fixed, and a phrase, which
can vary.

SAY 'This is an example of an instruction.'

Similarly, if the example is a TSO/E command, the command name and keyword
operands, which are fixed, are in uppercase. Information that can vary, such as a
data set name, is in lowercase. The following ALLOCATE command and its
operands are in uppercase and the data set and file name are in lowercase.

"ALLOCATE DATASET(rexx.exec) FILE(sysexec) SHR REUSE"

This use of uppercase and lowercase is intended to make a distinction between
words that are fixed and words that can vary. It does not mean that you must type
REXX instructions and TSO/E commands with certain words in uppercase and
others in lowercase.

Exercises

Periodically, you will find sections with exercises you can do to test your
understanding of the information. Answers to the exercises are included when
appropriate.

Where to Find More Information

Please see z/OS Information Roadmap for an overview of the documentation
associated with z/OS, including the documentation available for z/OS TSO/E.

Accessing Licensed Books on the Web

z/OS licensed documentation in PDF format is available on the Internet at the IBM
Resource Link Web site at:

http://www.ibm.com/servers/resourcelink

Licensed books are available only to customers with a z/OS license. Access to
these books requires an IBM Resource Link Web userid and password, and a key
code. With your z/OS order you received a memo that includes this key code.

To obtain your IBM Resource Link Web userid and password log on to:

http://www.ibm.com/servers/resourcelink

To register for access to the z/OS licensed books:

1. Log on to Resource Link using your Resource Link userid and password.

2. Click on User Profiles located on the left-hand navigation bar.

3. Click on Access Profile.

4. Click on Request Access to Licensed books.

5. Supply your key code where requested and click on the Submit button.

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

If you supplied the correct key code you will receive confirmation that your request
is being processed. After your request is processed you will receive an e-mail
confirmation.

Note: You cannot access the z/OS licensed books unless you have registered for

access to them and received an e-mail confirmation informing you that your
request has been processed.

To access the licensed books:

1. Log on to Resource Link using your Resource Link userid and password.

2. Click on Library.

3. Click on zSeries.

4. Click on Software.

5. Click on z/OS.

6. Access the licensed book by selecting the appropriate element.

Using LookAt to Look Up Message Explanations

LookAt is an online facility that allows you to look up explanations for z/OS
messages and system abends.

Using LookAt to find information is faster than a conventional search because
LookAt goes directly to the explanation.

LookAt can be accessed from the Internet or from a TSO command line.

You can use LookAt on the Internet at:

http://www.ibm.com/servers/eserver/zseries/zos/bkserv/lookat/lookat.html

To use LookAt as a TSO command, LookAt must be installed on your host system.
You can obtain the LookAt code for TSO from the LookAt Web site by clicking on
News and Help or from the z/OS Collection, SK3T-4269 .

To find a message explanation from a TSO command line, simply enter: lookat
message-id as in the following example:

lookat iec192i

This results in direct access to the message explanation for message IEC192I.

To find a message explanation from the LookAt Web site, simply enter the message
ID. You can select the release if needed.

Note: Some messages have information in more than one book. For example,

IEC192I has routing and descriptor codes listed in z/OS MVS Routing and
Descriptor Codes. For such messages, LookAt prompts you to choose which
book to open.

About This Book xv

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

Part 1. Learning the REXX Language

The REXX language is a versatile general-purpose programming language that can
be used by new and experienced programmers. This part of the book is for
programmers who want to learn the REXX language. The chapters in this part
cover the following topics.

v “Chapter 1. Introduction” on page 3 — The REXX language has many features

that make it a powerful programming tool.
v “Chapter 2. Writing and Running a REXX Exec” on page 7 — Execs are easy to

write and have few syntax rules.
v “Chapter 3. Using Variables and Expressions” on page 25 — Variables,

expressions, and operators are essential when writing execs that do arithmetic

and comparisons.
v “Chapter 4. Controlling the Flow Within an Exec” on page 41 — You can use

instructions to branch, loop, or interrupt the flow of an exec.
v “Chapter 5. Using Functions” on page 61 — A function is a sequence of

instructions that can perform a specific task and must return a value.
v “Chapter 6. Writing Subroutines and Functions” on page 69 — You can write

internal and external routines that are called by an exec.
v “Chapter 7. Manipulating Data” on page 85 — Compound variables and parsing

are two ways to manipulate data.

Note: Although you can write a REXX exec to run in a non-TSO/E address space

in MVS, the chapters and examples in this part assume the exec will run in a
TSO/E address space. If you want to write execs that run outside of a
TSO/E address space, keep in mind the following exceptions to information
in Part 1:

v An exec that runs outside of TSO/E cannot include TSO/E commands,

unless you use the TSO/E environment service (see note).

v In TSO/E, several REXX instructions either display information on the

terminal or retrieve information that the user enters at the terminal. In a
non-TSO/E address space, these instructions get information from the
input stream and write information to the output stream.
– SAY — this instruction sends information to the output DD whose

default is SYSTSPRT.

– PULL — this instruction gets information from the input DD whose

default is SYSTSIN.

– TRACE — this instruction sends information to the output DD whose

default is SYSTSPRT.

– PARSE EXTERNAL — this instruction gets information from the input

DD whose default is SYSTSIN.

v The USERID built-in function, instead of returning a user identifier, might

return a stepname or jobname.

Note: You can use the TSO/E environment service, IKJTSOEV, to create a TSO/E

environment in a non-TSO/E address space. If you run a REXX exec in the
TSO/E environment you created, the exec can contain TSO/E commands,
external functions, and services that an exec running in a TSO/E address
space can use. That is, the TSO host command environment (ADDRESS
TSO) is available to the exec. For more information about the TSO/E
environment service and the different considerations for running REXX execs
within the environment, see z/OS TSO/E Programming Services.

© Copyright IBM Corp. 1988, 2001 1

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

Chapter 1. Introduction

What is REXX? .........................3

Features of REXX ........................3

Ease of use .........................3

Free format .........................3

Convenient built-in functions ...................4

Debugging capabilities .....................4

Interpreted language ......................4

Extensive parsing capabilities ...................4

Components of REXX.......................4

The SAA Solution ........................4

Benefits of Using a Compiler ....................5

Improved Performance .....................5

Reduced System Load .....................5

Protection for Source Code and Programs ..............6

Improved Productivity and Quality .................6

Portability of Compiled Programs..................6

SAA Compliance Checking ....................6

This chapter describes the REXX programming language and some of its features.

What is REXX?

REXX is a programming language that is extremely versatile. Aspects such as
common programming structure, readability, and free format make it a good
language for beginners and general users. Yet because the REXX language can be
intermixed with commands to different host environments, provides powerful
functions and has extensive mathematical capabilities, it is also suitable for more
experienced computer professionals.

The TSO/E implementation of the REXX language allows REXX execs to run in any
MVS address space. You can write a REXX exec that includes TSO/E services and
run it in a TSO/E address space, or you can write an application in REXX to run
outside of a TSO/E address space. For more information, see “Chapter 13. Using
REXX in TSO/E and Other MVS Address Spaces” on page 171.

Features of REXX

In addition to its versatility, REXX has many other features, some of which are:

Ease of use

The REXX language is easy to read and write because many instructions are
meaningful English words. Unlike some lower-level programming languages that
use abbreviations, REXX instructions are common words, such as SAY, PULL, IF...
THEN... ELSE..., DO... END, and EXIT.

Free format

There are few rules about REXX format. You need not start an instruction in a
particular column, you can skip spaces in a line or skip entire lines, you can have
an instruction span many lines or have multiple instructions on one line, variables

© Copyright IBM Corp. 1988, 2001 3

Features of REXX

do not need to be predefined, and you can type instructions in upper, lower, or
mixed case. The few rules about REXX format are covered in “Syntax of REXX
Instructions” on page 9.

Convenient built-in functions

REXX supplies built-in functions that perform various processing, searching, and
comparison operations for both text and numbers. Other built-in functions provide
formatting capabilities and arithmetic calculations.

Debugging capabilities

When a REXX exec running in TSO/E encounters an error, messages describing
the error are displayed on the screen. In addition, you can use the REXX TRACE
instruction and the interactive debug facility to locate errors in execs.

Interpreted language

TSO/E implements the REXX language as an interpreted language. When a REXX
exec runs, the language processor directly processes each language statement.
Languages that are not interpreted must be compiled into machine language and
possibly link-edited before they are run. You can use the IBM licensed product, IBM
Compiler and Library for REXX/370, to provide this function.

Extensive parsing capabilities

REXX includes extensive parsing capabilities for character manipulation. This
parsing capability allows you to set up a pattern to separate characters, numbers,
and mixed input.

Components of REXX

The various components of REXX are what make it a powerful tool for
programmers. REXX is made up of:

v Instructions — There are five types of instructions. All but commands are

processed by the language processor.

– Keyword
– Assignment
– Label
– Null
– Command (both TSO/E REXX commands and host commands)

v Built-in functions — These functions are built into the language processor and

provide convenient processing options.

v TSO/E external functions — These functions are provided by TSO/E and interact

with the system to do specific tasks for REXX.

v Data stack functions — A data stack can store data for I/O and other types of

processing.

The SAA Solution

The SAA solution is based on a set of software interfaces, conventions, and
protocols that provide a framework for designing and developing applications.

The SAA Procedures Language has been defined as a subset of the REXX
language. Its purpose is to define a common subset of the language that can be
used in several environments. TSO/E REXX is the implementation of the SAA
Procedures Language on the MVS system.

4

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

The SAA Solution

The SAA solution:
v Defines a common programming interface you can use to develop applications

that can be integrated with each other and transported to run in multiple SAA

environments.
v Defines common communications support that you can use to connect

applications, systems, networks, and devices.
v Defines a common user access that you can use to achieve consistency in

panel layout and user interaction techniques.
v Offers some applications and application development tools written by IBM.

Several combinations of IBM hardware and software have been selected as SAA
environments. These are environments in which IBM will manage the availability of
support for applicable SAA elements, and the conformance of those elements to
SAA specifications. The SAA environments are the following:

v MVS

– TSO/E

– CICS

– IMS

v VM CMS
v Operating System/400 (OS/400)
v Operating System/2 (OS/2)

Benefits of Using a Compiler

The IBM Compiler for REXX/370 (Program Number 5695-013) and the IBM Library
for REXX/370 (Program Number 5695-014) provide significant benefits for
programmers during program development and for users when a program is run.
The benefits are:

v Improved performance
v Reduced system load
v Protection for source code and programs
v Improved productivity and quality
v Portability of compiled programs
v Checking for compliance to SAA

Improved Performance

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 enters commands to the host shows minimal improvement
because REXX cannot decrease the time taken by the host to process the
commands.

Reduced System Load

Compiled REXX programs run faster than interpreted programs. Because a
program has to be compiled only once, system load is reduced and response time
is improved when the program is run frequently.

For example, a REXX program that performs many arithmetic operations might take
12 seconds to run interpreted. If the program is run 60 times, it uses about 12
minutes of processor time. The same program when compiled might run six times
faster, using only about 2 minutes of processor time.

Chapter 1. Introduction 5

Benefits of Using a Compiler

Protection for Source Code and Programs

Your REXX programs and algorithms are assets that you want to protect.

The Compiler produces object code, which helps you protect these assets by
discouraging people from making unauthorized changes to your programs. You can
distribute your REXX programs in object code only.

Load modules can be further protected by using a security server, such as RACF.

Improved Productivity and Quality

The Compiler can produce source listings, cross-reference listings, and messages,
which help you more easily develop and maintain your REXX programs.

The Compiler identifies syntax errors in a program before you start testing it. You
can then focus on correcting errors in logic during testing with the REXX interpreter.

Portability of Compiled Programs

A REXX program compiled under MVS/ESA can run under CMS. Similarly, a REXX
program compiled under CMS can run under MVS/ESA.

SAA Compliance Checking

The Systems Application Architecture (SAA) definitions of software interfaces,
conventions, and protocols provide a framework for designing and developing
applications that are consistent within and across several operating systems.

The SAA Procedures Language is a subset of the REXX language supported by the
interpreter under TSO/E, and can be used in this operating environment.

To help you write programs for use in all SAA environments, the Compiler can
optionally check for SAA compliance. With this option in effect, a warning message
is issued for each non-SAA item found in a program.

For more information, see IBM Compiler and Library for REXX/370; Introducing the
Next Step in REXX Programming.

6

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

Chapter 2. Writing and Running a REXX Exec

Before You Begin ........................7

What is a REXX Exec? ......................8

Syntax of REXX Instructions ....................9

The Character Type of REXX Instructions ..............9

Using Quotation Marks in an Instruction ..............9

The Format of REXX Instructions .................10

Beginning an instruction ...................10

Continuing an instruction ...................10

Continuing a literal string without adding a space ..........11

Ending an instruction.....................11

Types of REXX Instructions ...................12

Keyword .........................13

Assignment ........................13

Label ..........................14

Null ...........................14

Command.........................14

Execs Using Double-Byte Character Set Names ............14

Running an Exec ........................16

Running an Exec Explicitly ...................16

Running an Exec Implicitly ...................17

Allocating a PDS to a System File ................17

Exercises - Running the Example Execs .............18

Interpreting Error Messages ....................19

Preventing Translation to Uppercase .................20

From Within an Exec......................20

As Input to an Exec ......................20

Exercises - Running and Modifying the Example Execs ........21

Passing Information to an Exec ...................21

Using Terminal Interaction ....................21

Specifying Values when Invoking an Exec ..............22

Specifying Too Few Values ..................22

Specifying Too Many Values ..................22

Preventing Translation of Input to Uppercase .............23

Exercises - Using the ARG Instruction ..............23

Passing Arguments ......................24

Passing Arguments Using the CALL Instruction or REXX Function Call 24

Passing Arguments Using the EXEC Command ...........24

This chapter introduces execs and their syntax, describes the steps involved in
writing and running an exec, and explains concepts you need to understand to
avoid common problems.

Before You Begin

Before you can write a REXX program, called an exec, you need to create a data
set to contain the exec. The data set can be either sequential or partitioned, but if
you plan to create more than one exec, it is easier to create a REXX library as a
partitioned data set (PDS) with execs as members.

To create a PDS, allocate a data set with your prefix (usually your user ID) as the
first qualifier, any name as the second qualifier, and preferably "exec" as the third
qualifier. You can allocate the PDS with the Utilities option in ISPF/PDF or with the

© Copyright IBM Corp. 1988, 2001 7

Before You Begin

TSO/E ALLOCATE command. For specific information about allocating a data set
for an exec, see “Appendix A. Allocating Data Sets” on page 185.

What is a REXX Exec?

A REXX exec consists of REXX language instructions that are interpreted directly
by the REXX interpreter or compiled directly by a REXX language compiler and
executed by a Compiler Runtime Processor. An exec can also contain commands
that are executed by the host environment.

An advantage of the REXX language is its similarity to ordinary English. This
similarity makes it easy to read and write a REXX exec. For example, an exec to
display a sentence on the screen uses the REXX instruction SAY followed by the
sentence to be displayed.

Example of a Simple Exec

/**************************** REXX *********************************/

SAY 'This is a REXX exec.'

Note that this simple exec starts with a comment line to identify the program as a
REXX exec. A comment begins with /* and ends with */. To prevent

incompatibilities with CLISTs, IBM recommends that all REXX execs start with
a comment that includes the characters “REXX” within the first line (line 1) of
the exec. Failure to do so can lead to unexpected or unintended results in
your REXX exec. More about comments and why you might need a REXX exec

identifier appears later 14.

When you run the exec, you see on your screen the sentence:

This is a REXX exec.

Even in a longer exec, the instructions flow like ordinary English and are easy to
understand.

Example of a Longer Exec

/**************************** REXX *********************************/
/* This exec adds two numbers and displays their sum. */
/*******************************************************************/

SAY 'Please enter a number.'
PULL number1
SAY 'Now enter a number to add to the first number.'
PULL number2
sum = number1 + number2
SAY 'The sum of the two numbers is' sum'.'

When you run the example, the exec interacts with you at the terminal. First you
see on your screen:

Please enter a number.

8

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

When you type a number, for example 42, and press the Enter key, the variable

number1 is assigned the value 42. You then see another sentence on the screen.

Now enter a number to add to the first number.

When you enter another number, for example 21, the variable number2 is assigned
the value 21. Then the values in number1 and number2 are added and the total is
assigned to sum. You see a final sentence on the screen displaying the sum.

The sum of the two numbers is 63.

Before you actually try these examples, please read the next two sections:

v “Syntax of REXX Instructions”
v “Running an Exec” on page 16

Syntax of REXX Instructions

Some programming languages have rigid rules about how and where characters
are entered on each line. For example, CLIST statements must be entered in
uppercase, and assembler statements must begin in a particular column. REXX, on
the other hand, has simple syntax rules. There is no restriction on how characters
are entered and generally one line is an instruction regardless of where it begins or
where it ends.

What is a REXX Exec?

The Character Type of REXX Instructions

You can enter a REXX instruction in lowercase, uppercase, or mixed case.
However, alphabetic characters are changed to uppercase, unless you enclose
them in single or double quotation marks.

Using Quotation Marks in an Instruction

A series of characters enclosed in matching quotation marks is called a literal string.
The following examples both contain literal strings.

SAY 'This is a REXX literal string.' /* Using single quotes */

SAY "This is a REXX literal string." /* Using double quotes */

You cannot enclose a literal string with one each of the two types of quotation
marks. The following is not a correct example of an enclosed literal string.

SAY 'This is a REXX literal string." /* Using mismatched quotes */

When you omit the quotation marks from a SAY instruction as follows:

SAY This is a REXX string.

you see the statement in uppercase on your screen.

THIS IS A REXX STRING.

Note: If any word in the statement is the name of a variable that has already been

assigned a value, REXX substitutes the value. For information about
variables, see “Using Variables” on page 25.

Chapter 2. Writing and Running a REXX Exec 9

Syntax of REXX Instructions

If a string contains an apostrophe, you can enclose the literal string in double
quotation marks.

SAY "This isn't a CLIST instruction."

You can also use two single quotation marks in place of the apostrophe, because a
pair of single quotation marks is processed as one.

SAY 'This isn't a CLIST instruction.'

Either way, the outcome is the same.

This isn't a CLIST instruction.

The Format of REXX Instructions

The REXX language uses a free format. This means you can insert extra spaces
between words and blank lines freely throughout the exec without causing an error.
A line usually contains one instruction except when it ends with a comma (,) or
contains a semicolon (;). A comma is the continuation character and indicates that
the instruction continues to the next line. The comma, when used in this manner,
also adds a space when the lines are concatenated. A semicolon indicates the end
of the instruction and is used to separate multiple instructions on one line.

Beginning an instruction

An instruction can begin in any column on any line. The following are all valid
instructions.

SAY 'This is a literal string.'

SAY 'This is a literal string.'

SAY 'This is a literal string.'

This example appears on the screen as follows:

This is a literal string.
This is a literal string.
This is a literal string.

Continuing an instruction

A comma indicates that the instruction continues to the next line. Note that a space
is added between “extended” and “REXX” when it appears on the screen.

SAY 'This is an extended',

'REXX literal string.'

This example appears on the screen as one line.

This is an extended REXX literal string.

Also note that the following two instructions are identical and yield the same result
when displayed on the screen:

SAY 'This is',

'a string.'

is functionally identical to:

SAY 'This is' 'a string.'

These examples appear on the screen as:

10

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

Syntax of REXX Instructions

This is a string.

In the first example, the comma at the end of line 1 adds a space when the two
lines are concatenated for display. In the second example, the space between the
two separate strings is preserved when the line is displayed.

Continuing a literal string without adding a space

If you need to continue an instruction to a second or more lines but do not want
REXX to add spaces when the line appears on the screen, use the concatenation
operand (two single OR bars, ||).

SAY 'This is an extended literal string that is bro'||,

'ken in an awkward place.'

This example appears on the screen as one line without adding a space within the
word “broken”.

This is an extended literal string that is broken in an awkward place.

Also note that the following two instructions are identical and yield the same result
when displayed on the screen:

SAY 'This is' ||,

'a string.'

is functionally identical to:

SAY 'This is' || 'a string.'

These examples appear on the screen as:

This isa string.

In the first example, the concatenation operator at the end of line 1 causes the
deletion of any spaces when the two lines are concatenated for display. In the
second example, the concatenation operator also concatenates the two strings
without space when the line is displayed.

Ending an instruction

The end of the line or a semicolon indicates the end of an instruction. If you put
more than one instruction on a line, you must separate each instruction with a
semicolon. If you put one instruction on a line, it is best to let the end of the line
delineate the end of the instruction.

SAY 'Hi!'; say 'Hi again!'; say 'Hi for the last time!'

This example appears on the screen as three lines.

Hi!
Hi again!
Hi for the last time!

The following example demonstrates the free format of REXX.

Chapter 2. Writing and Running a REXX Exec 11

Syntax of REXX Instructions

Example of Free Format

/************************* REXX ************************************/
SAY 'This is a REXX literal string.'
SAY 'This is a REXX literal string.'

SAY 'This is a REXX literal string.'
SAY,
'This',
'is',
'a',
'REXX',
'literal',
'string.'

SAY'This is a REXX literal string.';SAY'This is a REXX literal string.'
SAY ' This is a REXX literal string.'

When the example runs, you see six lines of identical output on your screen
followed by one indented line.

This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.

This is a REXX literal string.

Thus you can begin an instruction anywhere on a line, you can insert blank lines,
and you can insert extra spaces between words in an instruction because the
language processor ignores blank lines and spaces that are greater than one. This
flexibility of format allows you to insert blank lines and spaces to make an exec
easier to read.

Only when words are parsed do blanks and spaces take on significance. More
about parsing is covered in “Parsing Data” on page 87.

Types of REXX Instructions

There are five types of REXX instructions: keyword, assignment, label, null, and
command. The following example is an ISPF/PDF Edit panel that shows an exec
with various types of instructions. A description of each type of instruction appears
after the example. In most of the descriptions, you will see an edit line number
(without the prefixed zeroes) to help you locate the instruction in the example.

12

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