Advanced REXX

Programming Topics
Objectives

 Describe the difference between constants and variables

 Demonstrate and describe the parts of a compound symbol
and how they can be used to create an array
 Explain the importance of user defined functions and how
they are created
 Describe the uses of the FORMAT( ) function and its
manipulation of numerical output
Objectives continued

 List and explain string functions:

 POS( )
 WORDPOS( )
 COMPARE( )
 ABBREV( )
 Explain the program stack and demonstrate its practical uses
with REXX
 Explain the uses of the EXTRACT subcommand
Objectives continued

 Describe the DO loop and when to use compound DO loops

 Explain subroutines and their most important language
constructs:
 CALL
 ARG
 PROCEDURE
 Discuss the differences and similarities of subroutines and
functions
 State the conditions needed for a condition trap to take place
Objectives continued

 Explain what streaming information can do in a REXX

program, using:
 LINEOUT, CHAROUT, LINEIN, CHAROUT, External Data
Queue, LINES, and CHARS
 Describe the uses of the STREAM function, with examples
 List the functions of the commands:
 ADDRESS
 INTERPRET
 ITERATE
Constants and Variables

 Constants are values that begin with a digit, decimal point,

or sign, such as:
8700
.00069
-34000
 The default value for a variable is set by the equals operator
in an assignment statement. The variable name is translated
into uppercase letters by the REXX language.
Compound Symbols

 A compound symbol is a variable containing a period:

name = stem.tail[.tail2.tail3……..]
 The portion up to and including the first period is referred to
as the stem.
 The stem is followed by a tail comprising one or more valid
symbols, separated by periods.
 You can use compound symbols to create an array of
variables that can be processed by their derived names.
Creating a REXX Array

 Some array examples are:

 Stem = Total
 Tail = name
 So the array will be structured as:
 Total.name
 Stem = Names
 Tail = first
 Tail = last
 So there is an array with two fields:
 Address.Names.first = Larry
 Address.Names.last = Vergas
User-Defined Functions

 If a function you need is not available in REXX, it is easy to

create your own.
 You need two instructions to create your own functions
effectively:
 ARG instruction
 Is used to obtain the arguments of an expression
 RETURN instruction
 Allows you to return the results from the function call to the main
program
Formatting Numeric Output

 The FORMAT( ) function formats numbers so that you can

create tables that line up all columns, making information
easier to read and understand.
 The FORMAT( ) function contains three arguments:
 The number or variable to be formatted
 The number of character positions before the decimal point
 The number of character positions after the decimal point
 The number to be formatted should always be small enough
to fit into the space you have reserved.
An Example of Formatting Numerical Data
POS( ) Function

 POS( ) – is used to find the position of a string in another

string

 STR = “Hi, how are you this evening?”

say POS(“eve”, STR)
What do you think the answer is? HINT: 22

How about:
say POS(“is even”, STR)
answer: 19
WORDPOS( ) Function

 WORDPOS( ) – is used to find a phrase in a string

 STR = “Hi, how are you this evening?”

say WORDPOS(“this”, STR)
What do you think the answer is? HINT: 5

How about:
say WORDPOS(“are you”, STR)
answer: 3
COMPARE( ) Function
 COMPARE( ) – is used to compare two strings and find the position of the
first character in the string that does not match the second string
 STR = “Hi, how are you this evening?”
 CMP = “Hi, how are you?”
 CMP2 = “Hi how are you this morning?”

say COMPARE(CMP, STR)

What do you think the answer is? HINT: 16

How about:
say COMPARE(CMP2, STR)
answer: 3  Look out for the missing comma!
ABBREV( ) Function

 ABBREV( ) – is used to accept abbreviations that a user

might enter as input
 The ABBREV( ) function is a friendly environment
function, to allow users to use abbreviations in a REXX
program

 Two examples are:

 abbrev(“YES”, answer, 1) /* accepts “YES”, “YE”, or “Y” */
 abbrev(“NO”, choice) /* accepts “NO”, “N”, or (blank) */
Getting Data from the Command Line
Defining the CMS Program Stack

 The program stack is used to pass

data to certain CMS commands, or
to obtain data from them.
 The program stack used in z/VM
and CMS is a FIFO stack (first in
first out).
How to Use the Program Stack
1. Begin the stack-processing portion of your program with the CMS command
MAKEBUF
2. Find out how many entries are already on the stack using the QUEUED( )
function
3. Use the QUEUE instruction to put data onto the program stack
4. Use the PULL instruction to take data off the stack
5. It is important to avoid removing items that your program did not place on
the program stack
6. Be sure that you have removed all your data from the program stack before
you return to CMS
Example: A CMS Command That Puts Data onto the
Program Stack
The EXTRACT Subcommand
EXTRACT Example: PARA XEDIT
Control Feature: The Compound DO Instruction
 You can combine one repetitive
phrase and one conditional phrase
in a single DO instruction.
 Some programs are constructed of
loops within loops.
Using loop names, you can specify
commands to exit the loops from
those names.
Subroutines
The CALL and ARG
Instructions
The PROCEDURE Instruction
 This instruction is used to make the
language processor temporarily forget
all the variables it knows.
 Within the PROCEDURE area you
can create new variables and some of
them can even have the same name.
 This instruction can only be used
within an internal routine.
Subroutines and Functions
 Subroutines:
In a subroutine, you use a CALL
instruction to start the subroutine.  Similarities:
A subroutine does not need to return a Both use the ARG and
result, but it can. PARSE ARG instructions to
A subroutine sets the value of the special obtain the values of their
variable RESULT. arguments.
Both can be either internal or
 Functions:
external.
To run a function, you use a function
call. Both use the same search
A order to allow users to store
function must return a result, using the external functions and
return instruction.
subroutines on other minidisks.
A function uses a return instruction to
When functions are internal,
pass a variable to the main program.
they can use the PROCEDURE
instruction just like subroutines.
External Subroutines
Using the SIGNAL Instruction

 A program can jump or transfer control to another part of

itself using the SIGNAL instruction:
 SIGNAL label
 SIGNAL can be used for error detection and program
debugging.
 You are not able to jump back into or jump around within a
DO loop, but you can SIGNAL to exit a DO loop.
Conditions and Condition Traps
When a Condition is Trapped

 When the specified condition occurs, control is passed to

the label corresponding to the trapped condition.
 If an explicit TRAPNAME was specified, control is passed
to that name. If no explicit TRAPNAME was specified,
control is passed to the label or routine that matches the
name of the condition.
 On RETURN from the CALL, the original flow of
execution is resumed.
The Condition Function

 The CONDITION function returns the condition

information associated with the current trapped condition.
 The information that can be retrieved is:
 The name of the current trapped condition
 Any descriptive string associated with that condition
 The instruction executed as a result of the condition trap
 The status of the trapped condition
Input and Output: Streaming Information

 In computing, the form of the information is often as important as its content.

 The goal of the REXX language is to keep things as simple as possible.
 The simplest way to look at information is one line at a time.
File Processing – LINEOUT

 You enter a file name, which the pull instruction then parses and stores in the variable fileid.
 As each line is typed:
The PARSE PULL instruction stores it as a string in the variable line
The LINEOUT function writes the string contained in line to the file name stored in
the variable fileid
The DO loop continues until you press Enter twice, thereby entering a NULL string
The program then calls LINEOUT with only the file name and exits.
File Processing - CHAROUT

 The CHAROUT function writes single-byte characters.

 The first time a program uses CHAROUT, the named stream is opened for
writing and the characters are written to the end of the stream.
File Processing – LINEIN & CHARIN
File Processing – External Data Queue

 The external data queue is a queue of character strings that

can only be accessed by line operations.
 The queue forms a language-defined channel of
communication between programs.
 Lines can be removed from the queue using the PULL or
PARSE PULL instructions.
 Lines can be added to the head of the queue using the PUSH
instruction.
 Lines can also be added to the tail of the queue using the
QUEUE instruction.
File Processing – LINES & CHARS
 The LINES function is used to find
out if any lines remain between the
read position and the end of a stream.
 The CHARS function finds out if any
characters remain in the input stream.
 Streams can be made up of minidisk
files, SFS files, spool files, or the
program stack.
The STREAM Function
 The STREAM function can:
Determine if a stream exists
Determine if a stream is ready for
input or output
Get the characters of the stream
 The stream function is for more
intricate and specialized input and
output tasks.
The ADDRESS Instruction

 ADDRESS – is used to effect a temporary or permanent

change to the destination of commands.
 When the expression is evaluated, the environment
specified is introduced as the new destination for
commands.
 Example:
 address CMS
 ‘STATE PROFILE EXEC’
 IF RC = 0 then ‘COPY PROFILE EXEC A TEMP = =‘
 address XEDIT
INTERPRET and ITERATE Instructions

 INTERPRET:
Is used to execute instructions that ITERATE:
have been built dynamically by
evaluating an expression Alters the flow of control
within a repetitive DO loop
Is usually required only in special
cases such as when more than one The control variable steps
instruction is to be interpreted at (iterates) the instruction list
once and is executed again,
unless the DO loop is
INTERPRET expr ;
terminated by its conditions
ITERATE [name] ;
Conclusion

 You should now be familiar with REXX programming and

syntax.
 You should be able to create your own REXX programs.
 Major topics within this module are stacks, subroutines,
functions, and stream information.
 REXX is an important component of z/VM and can be used
in many environments.
Glossary

Condition traps – are enabled or disabled using the ON or OFF

sub-key-words of the CALL and SIGNAL instructions, and
can be used to trap a variety of conditions, such as errors in
commands, input, or output.
External routine – A function or subroutine that is neither a
built-in routine nor is in the same program as the CALL
instruction or function call that invokes it.
Glossary

Function – An internal, built-in, or external routine that returns

a single result string and is invoked by a function call.
Function Call – A term in an expression that invokes a routine
that carries out some procedure and then returns a string;
then replaces the function call for the continuing evaluation
of the expression.
Internal Routine – A function or subroutine that is in the same
program as the CALL instruction or function call that is
invokes.
Glossary

Read position – The position in a character input stream from

which the next character or line will be read.
Return code – A string, typically a number, passed in an
implementation-dependent way, that conveys some
information about the command that has been executed; it
usually indicates the success or failure of the command but
can also be used to convey other information.
Glossary

Subroutine – An internal, built-in, or external routine that may

or may not return a result string and is invoked by the
CALL instruction. If it returns a result string, a subroutine
can also be invoked by a function call.
Trace – A description of some or all of the clauses in a
program, produced as each is executed; it is the simplest
form of debugging aid.
Write position – The position in a character output stream at
which the next character or line will be written.
References
 Cowlishaw, Michael, “The REXX language: A Practical Approach to
Programming” 2nd ed. ISBN:0-13-780851-5
 z/VM: REXX/VM User’s Guide (Version 3 Release 1.0)
 The REXX language: http://www2.hursley.ibm.com/rexx/
 The REXX Language Association:  http://www.rexxla.org/