IBM ^

z/VM Module 7: Advanced REXX Programming Topics

2004 IBM Corporation

IBM ^

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

2004 IBM Corporation

IBM ^

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

2004 IBM Corporation

IBM ^

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

2004 IBM Corporation

IBM ^

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

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

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

2004 IBM Corporation

IBM ^

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

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

An Example of Formatting Numerical Data

2004 IBM Corporation

IBM ^

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

2004 IBM Corporation

IBM ^

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

2004 IBM Corporation

IBM ^

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!

2004 IBM Corporation

IBM ^

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) */

2004 IBM Corporation

IBM ^

Getting Data from the Command Line

2004 IBM Corporation

IBM ^

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).

2004 IBM Corporation

IBM ^

How to Use the Program Stack

1. 2. 3. 4. 5. 6. Begin the stack-processing portion of your program with the CMS command MAKEBUF Find out how many entries are already on the stack using the QUEUED( ) function Use the QUEUE instruction to put data onto the program stack Use the PULL instruction to take data off the stack It is important to avoid removing items that your program did not place on the program stack Be sure that you have removed all your data from the program stack before you return to CMS

2004 IBM Corporation

IBM ^

Example: A CMS Command That Puts Data onto the Program Stack

2004 IBM Corporation

IBM ^

The EXTRACT Subcommand

2004 IBM Corporation

IBM ^

EXTRACT Example: PARA XEDIT

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

Subroutines

2004 IBM Corporation

IBM ^

The CALL and ARG Instructions

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

Subroutines and Functions

Subroutines:
In

Functions:
To

Similarities: a subroutine, you use a CALL instruction to start the subroutine. Both use the ARG and PARSE ARG instructions to obtain the values A subroutine does not need to return of their arguments. a result, but it can. A subroutine sets the value of the Both can be either internal or special variable RESULT. external.
run a function, you use a function
Both

call. A function must return a result, using the return instruction. A function uses a return instruction to pass a variable to the main program.

use the same search order to allow users to store external functions and subroutines on other minidisks.
When

functions are internal, they can use the PROCEDURE instruction just like subroutines.

2004 IBM Corporation

IBM ^

External Subroutines

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

Conditions and Condition Traps

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

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

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

File Processing LINEIN & CHARIN

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

The STREAM Function

The STREAM function can:
Determine Determine Get

if a stream exists

if a stream is ready for input or output the characters of the stream

The stream function is for more intricate and specialized input and output tasks.

2004 IBM Corporation

IBM ^

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

2004 IBM Corporation

IBM ^

INTERPRET and ITERATE Instructions

INTERPRET:
Is

used to execute instructions that have been built dynamically by evaluating an expression
Is

ITERATE:
Alters The

the flow of control within a repetitive DO loop control variable steps (iterates) the instruction list and is executed again, unless the DO loop is terminated by its conditions
ITERATE

usually required only in special cases such as when more than one instruction is to be interpreted at once
INTERPRET

expr ;

[name] ;

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

Glossary
Condition traps are enabled or disabled using the ON or OFF sub-keywords 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.

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

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.

2004 IBM Corporation

IBM ^

References
Cowlishaw, Michael, The REXX language: A Practical Approach to Programming 2nd ed. ISBN:0-13-780851-5 z/VM: REXX/VM Users Guide (Version 3 Release 1.0) The REXX language: http://www2.hursley.ibm.com/rexx/ The REXX Language Association: http://www.rexxla.org/

2004 IBM Corporation