You are on page 1of 114

REXX

Revision List

TABLE OF CONTENTS

1. REXX .............................................................................................................. 1
1.1 INTRODUCTION TO REXX............................................................................ 1
1.1.1 What is REXX ? ................................................................................ 1
1.1.2 Brief History Of REXX....................................................................... 1
1.2 GENERAL FORMAT OF REXX STATEMENTS ................................................. 4
1.3 CREATE AND EXECUTE A REXX PROGRAM ................................................. 6
1.4 OPERATORS .............................................................................................. 7
1.4.1 Arithmetic Operators......................................................................... 7
1.4.2 Concatenation Operators.................................................................. 7
1.4.3 Operator Precedence ....................................................................... 7
1.4.4 Logical Operators ............................................................................. 8
1.4.5 Comparison Operators ..................................................................... 8
2. FUNCTIONS, COMMANDS AND INSTRUCTIONS ..................................... 11
2.1 TERMINAL INPUT AND OUTPUT .................................................................. 11
2.2 CONDITIONAL INSTRUCTIONS ..................................................................... 14
2.3 LOOPING INSTRUCTIONS ........................................................................... 19
2.4 SUBROUTINES AND FUNCTIONS ................................................................. 25
2.5 BUILT-IN FUNCTIONS ................................................................................. 33
2.5.1 String Manipulating Functions ........................................................ 33
2.5.2 Arithmetic Functions ....................................................................... 41
2.5.3 Comparison Functions .................................................................... 43
2.5.4 Conversion functions ...................................................................... 45
2.5.5 Formatting Functions ...................................................................... 48
2.5.6 Miscellaneous Functions ................................................................ 51
2.6 TSO/E EXTERNAL FUNCTIONS .................................................................. 55
2.7 TSO/E REXX COMMANDS ....................................................................... 60
2.8 DEBUGGING EXECS ................................................................................ 68
2.8.1 Tracing Commands with the TRACE Instruction ............................ 68
2.8.2 Using REXX Special Variables RC and SIGL................................. 69
2.9 COMPOUND VARIABLES AND STEM........................................................... 71
2.10 SAMPLE REXX PROGRAM ........................................................................ 72
2.11 REXX CODING STANDARDS ...................................................................... 74
3. ISREDIT MACROS ....................................................................................... 75
3.1 ISPF/PDF MACRO COMMAND DESCRIPTIONS INDEX .................................. 77
3.2 ISPF/PDF EDIT MACRO COMMANDS ......................................................... 80
3.3 SAMPLE ISREDIT MACRO...................................................................... 99
4. ISPF SERVICES ......................................................................................... 100
4.1 ISPF SERVICES INDEX ........................................................................... 100
1. REXX

1.1 Introduction to REXX

1.1.1 What is REXX ?

TSO/REXX (Restructured EXtended eXecutor) is a powerful interactive


programming language that can execute system commands, such as TSO, ISPF
etc. It allows you to :

♦ Request input from the terminal and Display output on the terminal
♦ Execute TSO commands under program control
♦ Read and Write files

REXX is more modern, powerful language, and is the procedural language for
IBM’s System Application Architecture (SAA), which means REXX is implemented
across IBM’s product line.

REXX is a procedural language that allows programs and algorithms to be written


in a clear and structured way. It is easy to use by experts and casual users alike.
REXX has been designed to make manipulation of the kinds of symbolic objects
people normally deal with such as words and numbers. Although REXX has the
capability to issue commands to its host environment and to call programs and
function written in other languages, REXX is also designed to be independent of
its supporting system software when such commands are kept to minimum.

1.1.2 Brief History Of REXX

In the 1970’ s C. J. Stephenson and others at the IBM T. J Watson Research


center realized that, if applied consistently, this concept of command
programming language was extraordinary powerful: a single language could
provide the extension language -or “macro” language- for wide variety of
applications. They took the EXEC language and generalized and improved it for
this enhanced role; the new language was called EXEC 2.

EXEC 2 proved the concept of a general macro language. It was used mostly for
writing system commands and macros for wide variety of editors. Its interpreter
was provably, still is, fewest example of efficient robust system/370 assembler
code. However, EXEC2 (like its predecessor and most other macro languages of
1970 ‘s and even early 1980 s) assumed that macro programs would be mostly
commands with relatively little “glue” of logic and variables. Accordingly, it was
designed to allows commands ( literal strings, usually upper case) to be written
plainly, where as language keywords and variables were identified by prefix of an
ampersand.

1
This style, while adequate for simple commands, proved cumbersome for large
and complex programs and macros that were soon being written in EXEC 2. It
became clear that new language was needed, one based on classical syntax and
semantic used by languages in tradition of ALGOL, Pascal, and PL/I yet including
command and string programming facilities that EXEC 2 had proven to be so
effective and powerful. This new language initially called Rex (because the name
sounded nice) was very much driven by the desire to make programming easy. It
borrows most of its features from other languages, especially PL/I and EXEC 2,
but these features are modified or expressed in ways that make them easy to use
(but not necessary easy to implement!).

The first specification for the language is dated 29 March 1979. This was written
before any implementation was designed, and it was circulated to number of
people for comment: this began the tradition of documentation before
implementation the characterized development of REXX. Its name gained an “x”
to avoid any confusion with other products.

REXX was included the third release of IBM’s VM / System product shipped in
1983. It was soon discovered that IBM’s customers liked the language just as
much as did the “internal” users. Only 2 years later, the first non-IBM
implementation ( by the Mansfield Software Group, for PC-DOS ) became
available.

In 1987 IBM announced that REXX was to be the Procedures language for its
Systems Application Architecture (SAA), which was followed by implementations
for a number of operating systems including MVS/TSO, AS/400, and (in 1989),
the Extended Edition of OS/2 1.2. The first REXX compiler was developed at
IBM’s Vienna laboratory, following research by the IBM Haifa Scientific Center,
and was delivered to customers in 1989. By 1990 there was sufficient interest in
the language to justify the first international REXX Symposium for developers and
users, organised by the Stanford linear accelator center in California. This
symposium has been held annually since then.

Recent version of REXX from IBM include REXX for the AIX/6000 Operating
System, REXX for Netware, and REXX for CICS transaction Monitor. REXX is
now available for the most significant operating systems, and from several
vendors, not just IBM. Freeware or Shareware version, often excellent, are also
available for PC-DOS, UNIX, and other systems.

REXX is also a player in Java environment, too. A new dialect of REXX, called
Net REXX , works seamlessly within Java environment: Net REXX programs can
use any Java class; this Java security and performance to REXX programs , and
REXX arithmetic and simplicity to Java. A single language Net REXX, may be
used for scripting and application development.

2
REXX (Restructured Extended eXecutor)

IT ALLOWS YOU TO :

♦ EXECUTE SYSTEM COMMANDS, TSO, ISPF

♦ REQUEST INPUT FROM THE TERMINAL

♦ DISPLAY OUTPUT ON THE TERMINAL

♦ EXECUTE TSO COMMANDS UNDER PROGRAM


CONTROL

♦ DO FILE MANIPULATIONS

3
1.2 General Format Of REXX Statements

REXX Supports free-format statements, which can appear anywhere between


columns 1 and 72. A statement can have any number of embedded blanks and
can be terminated with either an end-of-line character or a semicolon(;).

More than one statement can appear on one line, separated from each other with
semicolons. Also, one statement can span more than one line, in which case a
comma at the end of the line indicates a continuation of the statement.

Comments appear between the delimiters /* and */ and can span one or more
lines. Variables do not need to be predefined, and you can type instructions in
upper, lower, or mixed case. A comma is the continuation character and indicates
that the instruction continues to then next line. A semicolon indicates the end of
the instruction and is used to separate multiple instructions on one line.

The general form of a REXX statement is


[Label:] term [;]
where term is either a comment or an expression.

4
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.'

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

The result is as follows

This is an extended REXX literal string.

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

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


'ken in an awkward place.'

Results

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

Ending an instruction:

If you put more than one instruction on a line, you must separate each instruction
with a semicolon.
SAY 'Hi!'; say 'Hi again!'; say 'Hi for the last time!'

5
1.3 Create And Execute A REXX Program

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. You can allocate the PDS with
the Utilities option in ISPF/PDF or with the TSO/E ALLOCATE command. It is
recommended that allocate a data set with your prefix as the first qualifier, any
name as the second qualifier, and preferably "exec" as the third qualifier.

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 */. This program displays
the line

This is a REXX exec

After you have placed REXX instructions in a data set, you can run the exec
explicitly by using the EXEC command followed by the data set name or implicitly
by entering the member name. You can run an exec implicitly only if the PDS that
contains the exec was allocated to a system file (SYSEXEC OR SYSPROC) or it
is allocated to an application CLIST OR EXEC.

Explicit execution
=è TSO EX ‘CCI.TST.EXEC(compile)’

Implicit Execution
=èTSO compile

Implicit execution can be done only if the PDS containing the REXX program is
allocated to system files ( SYSEXEC or SYSPROC ) using the tso alloc command
or the the PDS is allocated to a application CLIST or EXEC using TSO ALTLIB
command.

6
1.4 Operators

1.4.1 Arithmetic Operators

The arithmetic operators used in REXX numeric expressions are as follows

Operator Operation
+ Addition
- Subtraction
* Multiplication
/ Division, returning decimal quotient
% Division, returning integer
quotient
// Division, returning remainder
** Exponential
-n Negation
+n Addition

1.4.2 Concatenation Operators

The following concatenation operators are supported by REXX.

Operator Operation
blank Concatenate two strings with a blank character
in between.
!! Concatenate two strings without a blank character in between.

1.4.3 Operator Precedence

Operations are performed according to the following order of precedence:

Order Operation Operators


1 Expressions in parentheses ()
2 Prefix operators -+\
3 Exponential operator **
4 Multiplication and division * / % //
5 Addition and subtraction +-
6 Concatenation !!
7 Comparison == = \== < > >< >= <= \< \>
8 Logical AND &
9 Logical OR and EXCLUSIVE OR ! &&

7
1.4.4 Logical Operators

A logical operator is used when a Boolean operation is performed on two binary


operands. The following is a list of logical operators, including the operation and
return code.

Operator Operation Returns


& AND 1 if both comparisons are true;
otherwise 0.
! OR 1 if one of several comparisons is true;
Otherwise 0.
&& XOR 1 if only one of a group of comparisons
is true; otherwise 0.
\ NOT Reverses the logical value of the expression.

1.4.5 Comparison Operators

A comparison operator is used when two operands are compared with each
other. After a comparison expression is processed, from left to right, it yields 1 if
the comparison condition is true and 0 if the comparison condition is false. The
following is a list of REXX comparison operators.

Operator Operation
== Strictly equal
= Equal
\== Not strictly equal
\= Not equal
> Greater than
< Less than
>< Greater than or less than
>= Greater than or equal to
<= Less than or equal to
\< Not less than
\> Not greater than
>>= Strictly greater than or equal to
<<= Strictly less than or equal to
<> Less or greater than
>> strictly greater than
<< Strictly less than

8
OPERATORS

♦ ARITHMETIC OPERATORS

USED FOR ARITHMETIC OPERATIONS


E.G.:- + FOR ADDITION
% FOR DIVISION RETURNING INTEGER
QUOTIENT
** FOR EXPONENTIATION

♦ CONCATENATION OPERATORS

FOR THE CONCATENATION OF STRING


E.G.:- !! CONCATENATES TWO STRINGS

♦ LOGICAL OPERATORS

FOR LOGICAL OPERATIONS OF EXPRESSIONS


E.G.:- & FOR LOGICAL AND
! FOR OR

♦ COMPARISON OPERATORS

FOR COMPARISONS
E.G.:- = FOR EQUAL TO
> FOR GREATER THAN

9
Variable Names

VARIABLES ARE NOT PRE-DEFINED-REXX DEFINES THEM ON


THE FLY THE FIRST TIME THEY APPEAR IN A STATEMENT.
VARIABLES HAVE A DEFAULT VALUE OF NULL. THEY CAN BE
USED IN ARITHMETIC EXPRESSIONS IF THEY CONTAIN VALID
NUMERIC VALUES. A NULL IS A VALID NUMERIC VALUE.

THE RULES FOR VARIABLE NAMES ARE

♦ FIRST CHARACTER NOT 0-9 OR PERIOD.


♦ REMAINING CHARACTERS ANYTHING EXCEPT BLANK.
♦ CAN BE 250 CHARACTERS LONG
♦ UPPER AND LOWER CASE CHARACTERS ASSUMED BE THE
SAME.

VARIABLES CAN ASSIGN THE VALUE USING SIMPLE


ASSIGNMENT STATEMENT OF THE FORM
<VARIABLE> = EXPRESSION

E.g.;-
MYSTRING = “THIS IS THE CONTENT OF MYSTRING”
NUMBER1 = 10
NUMBER2 = 20
NUMBER3 = NUMBER1 + NUMBER2

10
2. Functions, Commands And Instructions

Different commands, functions and instructions in REXX can be divided into


following categories.

♦ Terminal Input and Output


E.g.:- SAY, PULL

♦ Instructions for program control and conditional logic


E.g.:- IF, SELECT, DO, LEAVE, ITERATE

♦ String Handling Functions


E.g.:- INSERT, COMPARE, MIDSTR, STRIP

♦ Data Conversion Functions


Eg;-X2C, X2D, C2D

♦ Stacks and Related commands


E.g.:- NEWSTACK, DELSTACK, PUSH

♦ Numeric Functions
E.g.:- Max, Min, BITXOR

♦ TSO Commands and REXX external functions


E.g.:- ALLOCATE, ADDRESS, OUTTRAP, SYSDSN

♦ File Handling Instructions


E.g.:- EXECIO

2.1 Terminal Input And Output

Terminal instructions Say and Put is used display output and receive input from
the terminal.

11
TERMINAL INPUT AND OUTPUT

♦ SAY DISPLAYING A LINE ON THE TERMINAL

♦ PULL OPENS A INPUT FIELD ON THE TERMINAL AND


WAITS FOR YOU TO PRESS ENTER

EXAMPLE

SAY “ENTER YOUR AGE”


PULL AGE /*What ever the person types is converted
into upper case and stored in AGE */

PARSE PULL AGE /* Same as above, but input is not


converted to Uppercase */

SAY ‘ENTER YOUR FIRST AND LAST NAME ‘


PULL FNAME LNAME /*REXX assumes variables are
delimited by space */

12
Pull And Say - Terminal Input And Output

SAY Instruction

♦ General Format

SAY expression

♦ Description

The Say instruction sends a line of data to a terminal SYSTSPRT DD statement


in batch mode.

♦ Example

SAY ‘SAY what?’

PULL Instruction

♦ General format

PULL template

♦ Description

The pull instruction reads the top element of a data stack and uses it as source
data. If the data stack is empty, then PULL will read from the terminal. The
PULL instruction is the same as REXX instruction PARSE UPPER PULL
[template].
Template consists of alternating patterns and variable names.

♦ Example

SAY ‘Please enter your first name: ‘


PULL name

13
2.2 Conditional Instructions

There are two types of conditional instructions. IF/THEN/ELSE can direct the
execution of an exec to one of two choices. SELECT/WHEN/OTHERWISE/END
can direct the execution to one of many choices.

14
IF/THEN/ELSE INSTRUCTIONS

IF logical-expression THEN
statement
ELSE
statement

OR

IF logical-expression THEN
DO
statement1
statement 2
…………….
END
ELSE
DO
statement1
statement 2
………….
…………
END

EXAMPLE
IF I=100 THEN
SAY ‘VALUE OF I IS 100’
ELSE
SAY ‘VALUE OF I NOT EQUAL TO 100’

15
IF/THEN/ELSE Instructions

The IF instruction executes one or many REXX statements based on the result of
evaluating an expression.

If the ELSE clause appears on the same line as the last portion of the THEN
statement set, a semicolon is needed to tell REXX to terminate the THEN
statement set

Miscellaneous "If" Statement Information:

Nested Ifs must have an ELSE clause paired with the THEN clause. If no action is
appropriate for the ELSE clause, you can use the 'NOP' (no operation) statement
as the statement after the ELSE. ( Example 3 )

Example

1. if reply = ‘YES' then say 'Acknowledged'


else say 'Enter alternative:'

2. if reply = ‘YES' then say '10-4'; else say 'Please try again:'

3. if today = ‘Saturday' then


if name = ‘FRED' then say 'Go home, Fred'
else nop
else say 'Who are you and what day is this?'

Sometimes it is necessary to have one or more IF/THEN/ELSE instructions within


other IF/THEN/ELSE instructions. Having one type of instruction within another is
called nesting. With nested IF instructions, it is important to match each IF with an
ELSE and each DO with an END.

IF weather = fine THEN


DO
SAY 'What a lovely day!'
IF tenniscourt = free THEN
SAY 'Shall we play tennis?'
ELSE NOP
END

Not matching nested Ifs to Else’s and DOs to ENDs can have some surprising
results.

16
SELECT Instruction- Conditional Execution of statement

SELECT

[WHEN expression THEN statement]]

[WHEN expression THEN statement]]

[WHEN expression THEN statement]]

[OTHERWISE statements]]

END;

THE SELECT INSTRUCTION EXECUTES ONLY ONE STATEMENT FROM A


GROUP OF STATEMENTS. THE SELECTION DEPENDS ON THE RESULT OF
EVALUATING EXPRESSION PLACED AFTER THE WHEN CLAUSE.
Example

SELECT
WHEN Y = 0 THEN SAY ‘Y IS 0’
WHEN Y = 1 THEN SAY ‘Y IS 1’
WHEN Y = 2 THEN SAY ‘Y IS 2’
OTHERWISE SAY ‘Y< 0 OR > 2’
END

17
Using the SELECT/WHEN/OTHERWISE/END Instruction

Example

"Thirty days hath September, April, June, and November; all the rest have thirty-
one, save February alone ..."
Write an exec that provides the number of days in a month. First have the exec
ask the user for a month specified as a number between 1 and 12 (with January
being 1, February 2, and so forth). Then have the exec reply with the number of
days. For month "2", the reply can be "28 or 29".

/******************************** REXX*****************************/
/* This exec requests the user to enter a month as a whole number */
/* from 1 to 12 and responds with the number of days in that */
/* month */
/******************************************************************/

SAY 'To find out the number of days in a month,'


SAY 'Enter the month as a number from 1 to 12.'
PULL month

SELECT
WHEN month = 9 THEN
days = 30
WHEN month = 4 THEN
days = 30
WHEN month = 6 THEN
days = 30
WHEN month = 11 THEN
days = 30
WHEN month = 2 THEN
days = '28 or 29'
OTHERWISE
days = 31
END
SAY 'There are' days 'days in Month' month '.'

18
2.3 Looping Instructions

There are two types of looping instructions, repetitive loops and conditional loops.
Repetitive loops allow you to repeat instructions a certain number of times, and
conditional loops use a condition to control repeating. All loops, regardless of the
type, begin with the DO keyword and end with the END keyword. You can
combine repetitive and conditional loops to create a compound loop. There are
two types of conditional loops, DO WHILE and DO UNTIL. Both types of loops
are controlled by one or more expressions. However, DO WHILE loops test the
expression before the loop executes the first time and repeat only when the
expression is true. DO UNTIL loops test the expression after the loop executes at
least once and repeat only when the expression is false. The LEAVE instruction
causes an immediate exit from a repetitive loop. Another instruction, ITERATE,
stops execution from within the loop and passes control to the DO instruction at
the top of the loop.

19
DO INSTRUCTION

DO [ expression or variable = start]


[ TO limit ] [ BY increment];
[ FOR expression ];
[ WHILE expression];
[ UNTIL expression];
statement

END

THE DO INSTRUCTION IS USED TO EXECUTE A GROUP OF


REXX STATEMENTS UNDER THE CONTROL OF AN
EXPRESSION THAT DETERMINES HOW MAY TIMES THE DO
STATEMENT SET IS TO BE EXECUTED. THE DO STATEMENT
HAS SEVERAL FORMATS

20
SIMPLE DO:

DO
statement 1
……
....
END

Simple DO executes statements only one time

Controlled Repetitive DO :

DO variable = start [TO end ] [BY increment]


statement 1
statement 2
END;
Here variable starts with the value given by ‘start’ and is incremented by
‘increment’ until the variable passes the value given by ‘end’. The control variable
can be changed within the loop; the changed value will affect the number of times
the loop is executed.

DO-FOR loop

DO variable = start [TO end ] FOR expression;


statement
......
....

END;

The FOR clause specifies a non-negative whole number that sets a second limit
on the number of passes through the loop if no other condition terminates the
loop

DO-WHILE loop

DO variable=start [TO end ] WHILE expression;


statement
.....
....
END;

You can use another type of DO statement, called a DO-WHILE or DO-UNTIL. If


a WHILE or UNTIL clause is specified on a DO statement, it supplies an
expression that must evaluate to either a 0 (false) or a 1 (true). The DO loop is
repeatedly executed either WHILE the evaluated expression result is 1, or UNTIL
the evaluated expression result is 1.

21
1. DO 7 /* Repeats 7 times */
statement 1
statement 2
.….
END

2.
Do I = 2 to -1 by -1 /* Would display:*/
say I /* 2 on 1st pass through loop */
End /* 1 on 2nd pass through loop */

3. Do K = 1 to 8 by 2 for 3 /* Loop will be executed 3 times */


say k /*since ‘for 3’ overrides the*/
End /*‘K=1 to 8 by 2*/

4. Do i=1 to 20 by 2 until I > 6


say I
end
/* This loop would display: 1, 3, 5, 7, stopping at 7, since 7 > 6 */

5. switch = 1 /* switch is a logical variable */


Do i= 1 to 20 while switch
say I
if i=7 then switch=0
End /* this loop would display 1 to 7, since switch = 0 when i=7 */

6 DO FOREVER
say ‘execute this loop forever’
END
7. The following loop is set to repeat 10 times while a certain condition is met, at
which point it stops.

quantity = 20
DO number = 1 TO 10 WHILE quantity < 50
quantity = quantity + number
SAY 'Quantity = 'quantity ' (Loop 'number')'
END

22
LEAVE Instruction-Terminate a DO loop

LEAVE [name]];

THE LEAVE INSTRUCTION STOPS A DO LOOP AND TRANSFERS


CONTROL TO THE STATEMENT FOLLOWING THE END
STATEMENT.
‘NAME’ IS A CONTROL VARIABLE FOR THE DO LOOP.

Example

DO j = 1 t0 4
if j= 2 THEN LEAVE
SAY J /* Display 1 only */
END

23
ITERATE INSTRUCTION- END CURRENT ITERATION OF
DO LOOP

ITERATE [name]]

THE ITERATE INSTRUCTION STOPS THE CURRENT ITERATION


OF A DO LOOP AND TRANSFERS CONTROL TO THE END
STATEMENT. THE DO LOOP CONTINUES AFTER TESTING ANY
EXPRESSION ASSOCIATED WITH THE LOOP. LIKE LEAVE,
ITERATE IS USED WITHIN THE LOOP.
‘NAME’ IS THE CONTROL VARIABLE FOR THE DO LOOP.

DO count = 1 TO 10
IF count = 8 THEN
ITERATE
ELSE
SAY 'Number' count /*List of numbers 1 t0 10
exception of number 8*/
END

24
2.4 Subroutines and Functions

Subroutines and functions are routines made up of a sequence of instructions


that can receive data, process that data, and return a value. The routines can be
Internal, external. Internal routine is within the current exec, marked by a label
and used only by that exec. External routine is program or exec in a member of a
partitioned data set that can be called by one or more execs. In many aspects,
subroutines and functions are the same; yet they are different in a few major
aspects, such as the way they are called and the way they return values. CALL
instruction is used to call a subroutine and RETURN is used to return values from
the routine.

25
Subroutines and Functions
CALLING A SUBROUTINE

CALL subroutine_name argument1, argument2,...

CALLING A FUNCTION

x = function(argument1, argument2,...)

RETURNING A VALUE FROM A SUBROUTINE

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

Returning a value from a function

A FUNCTION MUST RETURN A VALUE. THE CALLING EXEC RECEIVES THE


VALUE AT THE FUNCTION CALL. THE VALUE REPLACES THE FUNCTION
CALL, SO THAT IN THE FOLLOWING EXAMPLE, X = VALUE.

x = function(argument1, argument2,...)

26
Passing Information by Using Variables

When an exec and its internal function share the same variables, the value of a
variable is what was last assigned, regardless of whether the assignment was in
the main part of the exec or in the function.

Example
/*REXX*******/
number1 = 5
number2 = 10
SAY add()
SAY answer
EXIT

add:
answer = number1 + number2
RETURN answer

Using the same variables in an exec and its internal function can sometimes
create problems.

To avoid this kind of problem in an internal function, you can use: The
PROCEDURE instruction.

Passing Information by Using Arguments

A way to pass information to either internal or external functions or subroutines is


through arguments. You can pass up to 20 arguments separated by commas in a
function call.
function(argument1,argument2,argument3,..........)

Using the ARG Instruction: The function can receive the arguments with the ARG
instruction. Arguments are also separated by commas in the ARG instruction.
ARG arg1,arg2,arg3 .......

27
PROCEDURE INSTRUCTION-DEFINE A PROCEDURE

PROCEDURE [ EXPOSE name,.... ];

THE PROCEDURE INSTRUCTION DEFINES A PROCEDURE.


EXPOSE IS THE KEYWORD USED TO DEFINE ONE OR MORE
GLOBAL VARIABLES THAT ARE USED WITHIN THE
PROCEDURE.
‘NAME’ IS GLOBAL VARIABLE NAME.

Example

X = "MY VALUE IS USED IN THE PROCEDURE"


Y = "MY VALUE IS NOT USED IN THE PROCEDURE "
CALL PROC
EXIT

PROC: PROCEDURE EXPOSE X


SAY X
SAY Y /* Y has no value here */
RETURN

28
ARG instruction

ARG template

THE ARG INSTRUCTION PARSES THE ARGUMENTS PASSED TO


A PROGRAM OR SUBROUTINE AND PLACES THEM IN
VARIABLES. THE PARSING IS DONE ACCORDING TO PARSING
RULES OF REXX.
‘TEMPLATE’ CONSISTS OF SYMBOLS SEPARATED BY BLANKS.

Example

ret = MYWORK(‘DATA 3’ 30 50)


Mywork: ARG string, num1, num2

AFTER PARSING, THE SYMBOLS WILL HAVE THE FOLLOWING


VALUES:
STRING HAS ‘DATA 3’ , NUM1 HAS 30 AND NUM2 HAS 50.

29
CALL Instruction

CALL name [expression,...];

THE CALL INSTRUCTION EXECUTES A SUBROUTINE, A


PROGRAM, A BUILT-IN FUNCTION, OR AN EXTERNAL ROUTINE.
CONTROL IS PASSED TO THE CALLED ROUTINE, AND AFTER
ITS EXECUTION IS COMPLETED, CONTROL IS RETURNED TO
THE STATEMENT FOLLOWING THE CALL STATEMENT IN THE
CALLING ROUTINE.

AFTER COMPLETION OF THE CALLED ROUTINE, ANY RETURN


VALUE IS PLACED IN THE VARIABLE RETURN. IF NO VALUE IS
RETURNED BY THE INVOKED ROUTINE, THEN RETURN IS
INITIALISED TO NULL.

Example

Y = 2
CALL SQUARE Y /* CALL THE ROUTINE TO CALCULATE
SQUARE OF Y */
SAY ‘SQUARE OF ‘Y’ IS ‘ RESULT
……
……
SQUARE: PROCEDURE
ARG N
RETURN N*N

30
EXIT INSTRUCTION-TERMINATE EXEC

EXIT [expression]];

THE EXIT INSTRUCTION ENDS THE EXECUTION OF A REXX


EXEC AND RETURNS CONTROL TO THE CALLING PROGRAM.
‘EXPRESSION’ IS OPTIONAL; ITS VALUE IS EVALUATED
BEFORE TERMINATION OF THE EXEC.

A VALUE IS RETURNED TO THE CALLING PROGRAM


DEPENDING ON WHETHER EXPRESSION IS PART OF THE EXIT
INSTRUCTION.

Example

In the following program fragment, the exec will terminate


returning the value ‘12’.

X=4
EXIT x*3 /* terminate exec */

31
Examples

The following program calls the function greatest which returns the max of three
numbers. First time it is called as a subroutine and then it is called as a function.
/*REXX*/
A= 1
B = 4
C = 5
MAX = 0
CALL GREATEST A B C /* SUBROUTINE CALL*/
SAY 'EXPOSED VARIABLE MAX' MAX
SAY 'RETURNED VALUE RESELT' RESULT
SAY ‘GREATEST(A B C) ‘ GREATEST(A B C) /* FUNCTION CALL */
EXIT
/*******************************************/
/*Function :greatest */
/*Arguments :N1 N2 N3 */
/*Returns greatest among N1,N2 and N3 */
/******************************************/

GREATEST: PROCEDURE EXPOSE MAX


ARG N1 N2 N3
MAX = N1
IF N2 > N1 THEN MAX = N2
IF N3 > MAX THEN MAX = N3
RETURN(MAX)

Recursive routines

Functions or subroutines can be called recursively.

/*REXX*/
N= 10
DO I = 0 TO N
SAY B(N I)/* Binomial coefficients */
END
EXIT
B:PROCEDURE
ARG N R
SELECT
WHEN R = 1 THEN RETURN(N)
WHEN (R = N ! N = 1! R = 0 ) THEN RETURN(1)
WHEN N = 0 THEN SAY 'ERROR! NOT DEFINED!'
OTHERWISE
RETURN(B(N-1 R) + B(N-1 R-1))
END

32
2.5 Built-in Functions

Over 50 functions are built into the language processor. The built-in functions fall
into the following categories: Arithmetic functions, Comparison functions,
Conversion functions, Formatting functions, String manipulating functions,
Miscellaneous functions.

2.5.1 String Manipulating Functions

These functions analyze a string supplied in the argument (or a variable


representing a string) and return a particular value.

33
Following is the list of all string manipulating functions. Commonly used functions
are explained later.

Function Description
ABBREV Returns a string indicating if one string is equal to the specified
number of leading characters of another string.
DELSTR Returns a string after deleting a specified number of
characters, starting at a specified point in the input string.
DELWORD Returns a string after deleting a specified number of words,
starting at a specified word in the input string.
FIND * Returns the word number of the first word of a specified phrase
found within the input string.
INDEX * Returns the character position of the first character of a
specified string found in the input string.
INSERT Returns a character string after inserting one input string into
another string after a specified character position.
LASTPOS Returns the starting character position of the last occurrence of
one string in another.
LENGTH Returns the length of the input string.
OVERLAY Returns a string that is the target string overlaid by a second
input string.
POS Returns the character position of one string in another.
REVERSE Returns a character string, the characters of which are in
reverse order (swapped end for end).
STRIP Returns a character string after removing leading or trailing
characters or both from the input string.
SUBSTR Returns a portion of the input string beginning at a specified
character position.
SUBWORD Returns a portion of the input string starting at a specified word
number.
TRANSLATE Returns a character string with each character of the input
string translated to another character or unchanged.
VERIFY Returns a number indicating whether an input string is
composed only of characters from another input string or
returns the character position of the first unmatched character.
WORD Returns a word from an input string as indicated by a specified
number.
WORDINDEX Returns the character position in an input string of the first
character in the specified word.
WORDLENGTH Returns the length of a specified word in the input string.
WORDPOS Returns the word number of the first word of a specified phrase
in the input string.
WORDS Returns the number of words in the input string.
* Indicates a non-SAA built-in function provided only by TSO/E.

34
FIND FUNCTION

FIND (string, pharase)

♦ DESCRIPTION

THE FIND FUNCTION FINDS THE FIRST OCCURRENCE OF A


PHRASE IN A STRING OF WORDS. FIND COMPRESSES BLANKS
INTO A SINGLE BLANK.

♦ RETURN
THE FUNCTION RETURNS THE FIRST POSITION OF THE
PHRASE IF IT IS FOUND, OTHERWISE IT RETURNS 0.

♦ EXAMPLE

Find(‘All dogs go to Heaven’, ‘go to’) returns 3


Find(‘Honey they shrunk my pay’, ’my pay’)returns 4
FIND(‘Honey they shrunk my pay’ ‘the baby’)returns 0

35
INDEX function-Search for substring

INDEX(string, substring[[,startposition]] )

THE INDEX FUNCTION SEARCHES FOR A SUBSTRING IN A


STRING AND RETURNS THE POSITION OF THE FIRST
OCCURRENCE OF THE SUBSTRING.

THE FUNCTION RETURNS


0 IF SUBSTRING IS NOT FOUND IN STRING
A NUMERIC VALUE WHICH IS RELATIVE TO 1 IF THE
SUBSTRING IS FOUND

EXAMPLE

INDEX('abcdef’, ‘cd') ->3


INDEX('abcdef’, ‘xd') ->0
INDEX('abcdef','bc',3) ->0
INDEX('abcabc','bc',3) ->5
INDEX('abcabc','bc',6) ->0

36
INSERT FUNCTION-INSERT A STRING

INSERT(ins-string, string[[,[[n]][,[[length]][,pad]]]] )

THE INSERT FUNCTION INSERTS A STRING INTO ANOTHER


STRING AT A SPECIFIED POSITION. PADDING IS DONE IF
REQUIRED.

♦ ‘INS-STRING’ IS THE STRING INSERTED INTO STRING.


♦ ‘STRING’ IS THE STRING IN WHICH INS-STRING IS INSERTED.
♦ ‘N’ IS THE CHARACTER POSITION AFTER WHICH INS-STRING
IS INSERTED IN STRING. THE VALUE OF N MUST BE
NONNEGATIVE, AND ITS DEFAULT VALUE IS 0.
♦ ‘LENGTH’ IS THE LENGTH OF INS-STRING.
♦ ‘PAD’ IS THE CHARACTER FOR PADDING IF LENGTH IS
GREATER THAN THE LENGTH OF INS-STRING.

THE FUNCTION RETURNS STRING WITH INS-STRING INSERTED.


Example

INSERT(' ','abcdef',3) ->'abc def'


INSERT('123','abc',5,6) ->'abc 123 '
INSERT('123','abc',5,6,'+'->'abc++123+++'
INSERT('123','abc') ->'123abc'
INSERT('123','abc',,5,'-') ->'123--abc'

37
LENGTH function-Get the length of a string

LENGTH(string)

♦ Description

The LENGTH function determines he number of characters in a


string.
♦ Return
The function returns the length of string

♦ Example
LENGTH(“All dogs go to heaven”) returns 21.

38
STRIP function-Remove leading/trailing characters

STRIP(string[[,[[Both or Leading or Trailing ][,char]]])

♦ Description
The STRIP function removes any leading and trailing characters
from a string.
string is the data from which characters are removed.
Both means to remove both leading and trailing characters from
string.
Leading/Trailing means to remove leading/trailing characters
from string.
‘char’ is the character to be removed from string; the default is a
blank.
♦ Return
The function returns the stripped string.
♦ Example

STRIP(' ab c ') ->'ab c'


STRIP(' ab c ','L') ->'ab c '
STRIP(' ab c ','t') ->' ab c'
STRIP('12.7000',,0) ->'12.7'
STRIP('0012.700',,0) ->'12.7'

39
SUBSTR function-Extract a substring

SUBSTR(string, position[[,[[length]][,pad]]])

♦ Description

THE SUBSTR FUNCTION EXTRACTS A SUBSTRING FROM A


STRING STARTING AT A SPECIFIED CHARACTER POSITION.
STRING IS THE STRING FROM WHICH A PORTION IS
EXTRACTED.

POSITION IS THE CHARACTER POSITION IN STRING AT WHICH


THE SUBSTRING IS EXTRACTED; IT IS ALSO THE FIRST
CHARACTER OF THE EXTRACTED SUBSTRING.
LENGTH IS THE NUMBER OF BYTES OF THE SUBSTRING.
PAD IS THE PADDING CHARACTER.
♦ RETURN
THE FUNCTION RETURNS THE SUBSTRING.
♦ EXAMPLE
SUBSTR(‘HOT DOG’,4) RETURNS ‘ DOG’.

40
2.5.2 Arithmetic Functions

These functions evaluate numbers from the argument and return a particular
value.

REXX arithmetic functions are described below.

Function Description
ABS Returns the absolute value of the input number.
DIGITS Returns the current setting of NUMERIC DIGITS.
FORM Returns the current setting of NUMERIC FORM.
FUZZ Returns the current setting of NUMERIC FUZZ.
MAX Returns the largest number from the list specified, formatted
according to the current NUMERIC settings.
MIN Returns the smallest number from the list specified, formatted
according to the current NUMERIC settings.
RANDOM Returns a quasi-random, non-negative whole number in the range
specified.
SIGN Returns a number that indicates the sign of the input number.
TRUNC Returns the integer part of the input number, and optionally a
specified number of decimal places.

41
MAX function-Determine the maximum value

MAX(number,....)

♦ Description

THE MAX FUNCTION RETURNS THE MAXIMUM NUMERIC VALUE


FROM A LIST OF NUMERIC VALUES. UP TO 20 NUMBERS ARE
ALLOWED.
NUMBER IS A NUMERIC VALUE.
♦ RETURN
THE FUNCTION RETURNS THE MAXIMUM VALUE. THE SIZE OF
THE RETURNED VALUE DEPENDS ON THE CURRENT SETTINGS
OF NUMERIC DIGITS.
♦ EXAMPLE

MAX(22,34,67,100,1,4) RETURNS 100.

42
2.5.3 Comparison Functions

These functions compare numbers and/or strings and return a value.

Function Description
COMPARE Returns 0 if the two input strings are identical. Otherwise, returns
the position of the first character that does not match.
DATATYPE Returns a string indicating the input string is a particular data
type, such as a number or character.
SYMBOL Returns this state of the symbol (variable, literal, or bad).

43
COMPARE function

COMPARE(string1,string2[[,pad]])

♦ Description

THE COMPARE FUNCTION COMPARES TWO STRINGS.


‘string1’ and ‘string2’ ARE STRINGS BEING COMPARED.
pad IS AN OPTIONAL PADDING CHARACTER; IF IT IS NOT
SPECIFIED, THE DEFAULT CHARACTER IS BLANK (X’40’).
♦ RETURN

THE FUNCTION RETURNS:


• ZERO IF BOTH INPUT STRINGS ARE THE SAME.
• A NONZERO VALUE IF THE INPUT STRINGS ARE NOT
THE SAME; THIS VALUE IS ALSO THE POSITION OF THE
FIRST MISMATCHED CHARACTERS.

♦ Example

COMPARE(‘345’,’345’) returns 0 (exact match )


COMPARE(‘MOO%% ‘, ‘MOO’,’%’ ) returns 6 ( Ist
mismatch after padding character )
COMPARE(‘daa’, ’do’) returns 2 (Ist mismatched
character )

44
2.5.4 Conversion functions

These functions convert one type of data representation to another type of data
representation.

45
Data Conversion functions

Function Description
B2X Returns a string, in character format, that represents the input binary
string converted to hexadecimal. (Binary to hexadecimal)
C2D Returns the decimal value of the binary representation of the input
string. (Character to Decimal)
C2X Returns a string, in character format, that represents the input string
converted to hexadecimal. (Character to Hexadecimal)
D2C Returns a string, in character format, that represents the input decimal
number converted to binary. (Decimal to Character)
D2X Returns a string, in character format, that represents the input decimal
number converted to hexadecimal. (Decimal to Hexadecimal)
X2B Returns a string, in character format, that represents the input
hexadecimal string converted to binary. (Hexadecimal to binary)
X2D Returns the decimal representation of the input hexadecimal string.
(Hexadecimal to Decimal)

46
X2C function-Convert hexadecimal to character

X2C(hex-string)

♦ Description
The X2C function converts a string of hexadecimal values into a
character string.
Hex-string is one or more hexadecimal digits to be converted.

♦ Return
The function returns the converted character string.
♦ Example
X2C(‘F0F1F2’) returns 012.

47
2.5.5 Formatting Functions

These functions manipulate the characters and spacing in strings supplied in the
argument.

Function Description
CENTER/ Returns a string of a specified length with the input string
CENTRE centered in it, with pad characters added as necessary to
make up the length.
COPIES Returns the specified number of concatenated copies of the
input string.
FORMAT Returns the input number, rounded and formatted.
JUSTIFY * Returns a specified string formatted by adding pad
characters between words to justify to both margins.
LEFT Returns a string of the specified length, truncated or padded
on the right as needed.
RIGHT Returns a string of the specified length, truncated or padded
on the left as needed.
SPACE Returns the words in the input string with a specified
number of pad characters between each word.

* Indicates a non-SAA built-in function provided only by TSO/E.

48
SPACE

SPACE(string[[,n]][,pad]])

RETURNS THE BLANK-DELIMITED WORDS IN STRING WITH N


PAD CHARACTERS BETWEEN EACH WORD. IF YOU SPECIFY N,
IT MUST BE A POSITIVE WHOLE NUMBER OR ZERO. IF IT IS 0,
ALL BLANKS ARE REMOVED. LEADING AND TRAILING BLANKS
ARE ALWAYS REMOVED. THE DEFAULT FOR N IS 1, AND THE
DEFAULT PAD CHARACTER IS A BLANK.

Examples

SPACE('ABC DEF ') ->'ABC DEF'


SPACE(' ABC DEF',3) ->'ABC DEF'
SPACE('ABC DEF ',1) ->'ABC DEF'
SPACE('ABC DEF ',0) ->'ABCDEF'
SPACE('ABC DEF ',2,'+')->'ABC++DEF'

49
JUSTIFY

JUSTIFY(string, length,[[pad]])

RETURNS STRING FORMATTED BY ADDING PAD CHARACTERS BETWEEN


BLANK-DELIMITED WORDS TO JUSTIFY TO BOTH MARGINS. THIS IS DONE
TO WIDTH LENGTH (LENGTH MUST BE NONNEGATIVE). THE DEFAULT
PAD CHARACTER IS A BLANK.

Examples

JUSTIFY('The blue sky',14) ->'The blue sky'


JUSTIFY('The blue sky',8) ->'The blue'
JUSTIFY('The blue sky',9) ->'The blue'
JUSTIFY('The blue sky',9,'+') ->'The++blue'

50
2.5.6 Miscellaneous Functions

These functions do not clearly fit into any of the other categories.

51
Miscellaneous Functions

Function Description
ADDRESS Returns the name of the environment to which commands are
currently being sent.
ARG Returns an argument string or information about the argument
strings to a program or internal routine.
BITAND Returns a string composed of the two input strings logically
ANDed together, bit by bit.
BITOR Returns a string composed of the two input strings logically
ORed together, bit by bit.
BITXOR Returns a string composed of the two input strings exclusive
ORed together, bit by bit.
CONDITION Returns the condition information, such as name and status,
associated with the current trapped condition.
DATE Returns the date in the default format (dd mmm yyyy) or in one
of various optional formats.
ERRORTEXT Returns the error message associated with the specified error
number.
EXTERNALS* Returns the number of elements in the terminal input buffer. In
TSO/E, this function always returns a 0.
LINESIZE* Returns the current terminal line width minus 1.
QUEUED Returns the number of lines remaining in the external data
queue at the time when the function is invoked.
SOURCELINE Returns either the line number of the last line in the source file or
the source line specified by a number.
TIME Returns the local time in the default 24-hour clock format
(hh:mm:ss) or in one of various optional formats.
TRACE Returns the trace actions currently in effect.
USERID* Returns the TSO/E user ID, if the REXX exec is running in the
TSO/E address space.
VALUE Returns the value of a specified symbol and optionally assigns it
a new value.
XRANGE Returns a string of all 1-byte codes (in ascending order) between
and including specified starting and ending values.

* Indicates a non-SAA built-in function provided only by TSO/E.

52
ADDRESS instruction

ADDRESS host-environment [expression]] or [value]] expression;

♦ Description

THE ADDRESS INSTRUCTION SPECIFIES THE HOST


ENVIRONMENT WHERE NON-REXX COMMANDS ARE TO BE
EXECUTED.
THE SETTING OF THE HOST ENVIRONMENT IS CHECKED WITH
THE ADDRESS FUNCTION.
HOST-ENVIRONMENT IS A CHARACTER STRING CONSTANT, IT
IS ONE OF THE FOLLOWING:

♦ ISPEXEC Routes commands to SPFF/PDF.


♦ ISREDIT Routes commands to a PDF edit macro
processor.
♦ TSO Routes commands to TSO.
♦ MVS Invokes a program using the normal MVS
program Search
♦ LINK Issues an MVS LINK macro to the routine being
invoked.
♦ ATTACH Issues an MVS ATTACH macro to the routine
being invoked.
♦ CMS Routes commands to CMS.
♦ DOS Routes commands to DOS/VSE.
♦ XEDIT Routes commands to XEDIT

EXAMPLE

ADDRESS TSO ‘FREE DATASET(“TEST.COBOL.PGMLOAD” )’.

53
ADRESS INSTRUCTION

General format

ADDRESS host-environment [expression] or [value] expression;

Expression is first evaluated by REXX; the result is sent to the host environment
as a command to be executed. IF expression is not specified then the destination
is set permanently until the next ADDRESS instruction is issued. Subsequent
non-EXEC commands will be sent to this new host environment. If expression is
specified, then the host environment is effective during the execution of this
ADDRESS instruction.

VALUE is used if the first character of expression is a special character.

Return

The return code from the host environment, after the command is executed, is
placed in the special variable RC.

Example

The following ADDRESS instruction sends the command


FREE DATASET(“TEST.COBOL.PGMLOAD” ) to TSO to be executed.
ADDRESS TSO ‘FREE DATASET(“TEST.COBOL.PGMLOAD” )’.

/*REXX*/
SAY 'DO YOU KNOW YOUR PF KEYS?'
PULL ANSWER
IF ANSWER = 'NO' ! ANSWER = 'N' THEN
ADDRESS ISPEXEC "DISPLAY PANEL(ISPOPT3C)"
/*Address ISPEXEC to issue to ISPF service*/
ELSE
SAY 'O.K. NEVER MIND.'

54
2.6 TSO/E External Functions

In addition to the built-in functions, TSO/E provides external functions that you
can use to do specific tasks. Some of these functions perform the same services
as control variables in the CLIST language.

55
The TSO/E external functions

GETMSG - returns in variables a system message issued during an extended


MCS console session. It also returns in variables associated information about
the message. The function call is replaced by a function code that indicates
whether or not the call was successful.

LISTDSI - returns in variables the data set attributes of a specified data set. The
function call is replaced by a function code that indicates whether or not the call
was successful.

MSG - controls the display of TSO/E messages. The function returns the previous
setting of MSG.

MVSVAR - uses specific argument values to return information about MVS,


TSO/E, and the current session.

OUTTRAP - traps lines of TSO/E command output into a specified series of


variables. The function call returns the variable name specified.

PROMPT - sets the prompt option on or off for TSO/E interactive commands. The
function returns the previous setting of prompt.

SETLANG - retrieves and optionally changes the language in which REXX


messages are displayed. The function returns the previous language setting.

STORAGE - retrieves and optionally changes the value in a storage address.

SYSCPUS - returns in a stem variable information about all CPUs that are online.

SYSDSN - returns OK if the specified data set exists; otherwise, it returns an


appropriate error message.

SYSVAR - uses specific argument values to return information about the user,
terminal, language, exec, system, and console session.

56
OUTTRAP FUNCTION

X = OUTTRAP(‘Var’)

X = OUTTRAP(‘Var’,5)

X = OUTTRAP(‘OFF’)

The OUTTRAP function puts lines of command output into a


series of numbered variables, each with the same prefix. These
variables save the command output and allow an exec to process
the output. Specify the variable name in parentheses following
the function call.

To turn trapping off, reissue the OUTTRAP function with the


word "OFF".
x = OUTTRAP('OFF') /* turns trapping OFF */
The OUTTRAP function can be used only in REXX EXECs that
run in the TSO/E address space.

57
Examples

SAY 'The OUTTRAP variable name is' OUTTRAP('var')


/* Displays the variable name in which command output is
trapped.*/

The total number of lines trapped is stored in var0.


To limit the number of lines of output saved, you can specify a limit, for after the
variable name.

x = OUTTRAP('var',5)

This results in up to 5 lines of command output stored in var1, var2, var3, var4,
var5; and var0 contains the number 5.

The stem variable includes a period, which causes the lines of output to be stored
in a series of compound variables.

x = OUTTRAP('var.')
"LISTC"
SAY 'The number of lines trapped is' var.0
lines = var.0 + 1
"LISTDS mynew.exec MEMBERS"
SAY 'The number of lines trapped is' var.0
DO I = lines TO var.0
SAY var.i
END

To turn trapping off, reissue the OUTTRAP function with the word "OFF"

x = OUTTRAP('OFF') /* turns trapping OFF */

58
SYSDSN function-Check dataset status

SYSDSN(dsname or ‘dsname(member)’)

SYSDSN IS A TSO FUNCTION THAT CHECKS THE STATUS OF A


DATASET.
DSNAME IS THE NAME FOR WHICH THE STATUS IS
REQUESTED.
MEMBER IS THE MEMBER OF THE PARTITIONED DATASET FOR
WHICH THE STATUS IS REQUESTED.
♦ Return

The function returns the following information about dataset or


member:
OK
MEMBER NOT FOUND
MEMBER SPECIFIED, BUT DATA SET IS NOT PARTITIONED
DATA SET IS NOT FOUND
ERROR PROCESSING REQUESTED DATA SET
PROTECTED DATA SET
VOLUME NOT IN THE SYSTEM
INVALID DATA SET NAME
UNAVAILABLE DATA SET
♦ Example
dsn =SYSDSN(“ ‘SYS1.PROCLIB’ “)
if dsn = ‘OK’ say ‘SYS1.PROCLIB exists’

59
2.7 TSO/E REXX Commands

Commands provided with the TSO/E implementation of the language. These


commands do REXX-related tasks in an exec, such as

♦ Control I/O processing of information to and from data sets, (EXECIO)


♦ Perform data stack services (MAKEBUF, DROPBUF, QBUF, QELEM,
NEWSTACK, DELSTACK, QSTACK)
♦ Change characteristics that control the execution of an exec (EXECUTIL and
the immediate commands)
♦ Check for the existence of a host command environment (SUBCOM).

60
Using REXX commands

An exec can consist of nothing but TSO/E commands, such as an exec that sets
up a user's terminal environment by allocating the appropriate libraries of data
sets, or the exec can contain commands intermixed with REXX language
instructions.

When an exec issues a command, the REXX special variable RC is set to the
return code. An exec can use the return code to determine a course of action
within the exec. Every time a command is issued, RC is set. Thus RC contains
the return code from the most recently issued command.

Using Quotation marks: Generally, to differentiate commands from other types


of instructions, enclose the command within single or double quotation marks.
When issuing TSO/E commands in an exec, it is recommended that you enclose
them in double quotation marks.

Many TSO/E commands use single quotation marks within the command. For
example, ALLOCATE, require single quotation marks around fully-qualified data
set names.

“ALLOC DA('USERID.MYREXX.EXEC') F(SYSEXEC) SHR REUSE”

Using Variables: When a variable is used in a TSO/E command, the variable


cannot be within quotation marks if its value is to be substituted. Only variables
outside quotation marks are processed by the language processor.
When a variable represents a fully-qualified data set name, the name must be
enclosed in two sets of quotation marks to ensure that one set of quotation marks
remains as part of the value.

name = " 'project.rel1.new' "

"LISTDS" name "STATUS"

Executing EXEC : To explicitly invoke another exec from within an exec, issue
the EXEC command as you would any other TSO/E command.
"EXEC myREXX.exec(calc) '24 55 12 38' "

You might want to invoke an exec with the EXEC command rather than as an
external routine when the exec is not within the same PDS as the calling exec, or
when the PDSs of the two execs are not allocated to either SYSEXEC or
SYSPROC.

61
Stacks and Related commands
NEWSTACK and DELSTACK command

NEWSTACK

The NEWSTACK command creates a new data stack which


becomes current stack

Example
“NEWSTACK”

DELSTACK host REXX command


DELSTACK

The DELSTACK command removes the data stack and deletes all
elements from it.

Example
“DELSTACK” /*removes stack */

62
PUSH instruction- Put an element at the top of the data
stack

PUSH expression

♦ Description
The PUSH instruction places a new element at the top of the data
stack.
expression is the element to be placed in the data stack.
♦ Example
line = “WallyMagoo”
PUSH line /* place line at the top of the stack */

63
PULL instruction- Get an element from the top of the data
stack

PULL template

♦ Description
THE PULL INSTRUCTION READS THE TOP ELEMENT OF DATA
STACK AND USES IT AS SOURCE DATA. IF THE DATA STACK IS
EMPTY, THEN PULL WILL READ FROM THE TERMINAL. THE
PULL INSTRUCTION IS THE SAME AS THE REXX INSTRUCTION
PARSE UPPER PULL
template CONSISTS OF ALTERNATING PATTERNS AND
VARIABLE NAMES.
♦ EXAMPLE
SAY ‘PLEASE ENTER YOUR FIRST NAME: ‘
PULL NAME.

64
EXECIO command-Read and write data

Read Operation

EXECIO [lines or *] [ DISKR or DISKRU ] ddname


[ linenum or 1 ]
[ ( [ [FINIS] [ LIFO or FIFO or SKIP ] ] or
[ STEM var [FINIS] ] [ ) ]

Write operation

EXECIO [ lines or * ] DISKW ddname


[( [STEM var ] [FINIS ] [ ) ] ]

THE EXECIO REXX COMMAND IS USED TO READ OR WRITE DATA TO OR


FROM DATASETS AND PDS MEMBERS. IT PERFORMS THE FOLLOWING
OPERATIONS
♦ READ DATA FROM FILE AND PLACE IN DATA STACK

♦ READ DATA FROM FILE AND PLACE IN VARIABLES

♦ READ DATA FROM DATA STACK AND WRITE TO FILE

♦ READ DATA FROM VARIABLES AND WRITE TO FILE

LINES IS THE NUMBER OF LINES TO READ OR WRITE


DISKR MEANS A READ OPERATION.
DISKRU MEANS A READ OPERATION FOR UPDATE
DISKW MEANS A WRITE OPERATION.
LINENUM IS THE RECORD NUMBER FOR READ OPERATION
FINIS MEANS TO CLOSE THE FILE AFTER A READ OR WRITE OPERATION
LIFO/FIFO MEANS TO WRITE TO THE DATA STACK IN LAST-IN-FIRST-OUT
SEQUENCE OR FIRST-IN-FIRST-OUT SEQUENCE.
SKIP MEANS TO ONLY READ THE NUMBER OF RECORDS CONTAINED IN
LINES, AND NOT TO WRITE THEM TO THE DATA STACK.
STEM SPECIFIES THE NAMES OF VARIABLES TO WHICH DATA ARE
WRITTEN OR FROM WHICH DATA ARE READ.

65
EXECIO command-Read and write data

After completion of EXECIO, command variable RC is set to the following codes:


0-Successful completion
1-Data truncated during a write operation
2-End of file reached
20-Fatal error

Example

1. To open a data set without reading any records, put a zero immediately
following the EXECIO command and specify the OPEN operand.

"EXECIO 0 DISKR mydd (OPEN"

2. To read a specific number of lines, put the number immediately following the
EXECIO command.

"EXECIO 25 ..."

3. To read the entire data set, put an asterisk immediately following the EXECIO
command.

"EXECIO * DISKR TEMP (FINIS STEM A"


Here EXECIO performs a diskread operation of a preallocated file using a TSO
ALLOC instruction and the all records are placed in the stem variable A. Do not
use the FINIS option if you want the next EXECIO statement in your exec to
continue reading at the line immediately following the last line read.

4. "ALLOC F(IN) DA('"DDNAME"') SHR"


'EXECIO * DISKR IN ( FINIS'
/* COPY FILE ONTO STACK */

5. To read just 5 lines to the data stack starting at line 100, write the following:

"EXECIO 5 DISKR myindd 100 (FINIS"

6. To open a data set at line 100 without reading lines to the data stack, write the
following:

"EXECIO 0 DISKR myindd 100 (OPEN"

If the data set is already open, no operation is performed for OPEN.

66
EXECIO Example

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


/* This exec copies records from data set 'my.input' to the end of */
/* data set 'my.output'. Neither data set has been allocated to a */
/* ddname. It assumes that the input data set has no null lines. */
/********************************************************************/
"ALLOC DA('my.input') F(indd) SHR REUSE"
"ALLOC DA('my.output') F(outdd) MOD REUSE"
SAY 'Copying ...'
"EXECIO * DISKR indd (FINIS"
QUEUE '' /* Insert a null line at the end to indicate end of file */
"EXECIO * DISKW outdd (FINIS"

SAY 'Copy complete.'


"FREE F(indd outdd)"
EXIT 0

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


/* This exec reads five records from the data set allocated to */
/* MYINDD starting with the third record. It strips trailing blanks */
/* from the records, and then writes any record that is longer than */
/* 20 characters. The file is not closed when the exec is finished. */
/***********************************************************************
"EXECIO 5 DISKR myindd 3"
DO I = 1 to 5
PARSE PULL line
stripline = STRIP(line,t)
len = LENGTH(stripline)

IF len > 20 THEN


SAY 'Line' stripline 'is long.'
ELSE NOP
END

/* The file is still open for processing */

EXIT 0

67
2.8 Debugging EXECS

2.8.1 Tracing Commands with the TRACE Instruction

The TRACE instruction has many options for various types of tracing, two of
which are "commands" or "c" and "error" or "e".

TRACE C: When you specify "trace c" in an exec, any command that follows is
traced before it is executed, then it is executed, and the return code from the
command is displayed.

E.g.:- Trace ? C
?- is the prefix which means enables interactive tracing

If an exec includes "trace c" and again incorrectly issues a command, the exec
displays the line number and the command, executes it, and displays the error
message and the return code from the command

TRACE E: When you specify "trace e" in an exec, any host command that results
in a nonzero return code is traced after it executes and the return code from the
command is displayed.

68
2.8.2 Using REXX Special Variables RC and SIGL

RC: RC stands for return code and is set every time a command is issued. When
a command ends without error, RC is usually set to 0. When a command ends in
error, RC is set to whatever return code is assigned to that error.

The RC variable can be especially useful in an IF instruction to determine which


path an exec should take.

'ALLOC DA('dsname') F(SYSPROC) SHR REUSE'


IF RC \= 0 THEN
CALL error1
ELSE NOP

The value of RC is set by every command and might not remain the same for the
duration of an exec. When using RC, make sure it contains the return code of the
command you want to test.

SIGL: The SIGL special variable is used in connection with a transfer of control
within an exec because of a function, or a SIGNAL or CALL instruction. When the
language processor transfers control to another routine or another part of the
exec, it sets the SIGL special variable to the line number from which the transfer
occurred.

SIGL and the SIGNAL ON ERROR instruction can help determine what command
caused an error and what the error was. When SIGNAL ON ERROR is included
in an exec, any host command that returns a nonzero return code causes a
transfer of control to a routine named "error".

Example
/* REXX */
SIGNAL ON ERROR
"ALLOC DA(new.data) LIKE(old.data)"


"LISTDS ?"


EXIT
ERROR:
SAY 'The return code from the command on line' SIGL 'is' RC

69
Debugging EXECs

WHEN YOU ENCOUNTER AN ERROR IN AN EXEC, THERE ARE


SEVERAL WAYS TO LOCATE THE ERROR.

♦ THE TRACE INSTRUCTION DISPLAYS HOW THE LANGUAGE


PROCESSOR EVALUATES EACH OPERATION.

♦ SPECIAL VARIABLES, RC AND SIGL, ARE SET BY THE


SYSTEM TO INDICATE

• THE RETURN CODE FROM A COMMAND - (RC)

• THE LINE NUMBER FROM WHICH THERE WAS A


TRANSFER OF CONTROL BECAUSE OF A FUNCTION
CALL, A SIGNAL INSTRUCTION, OR A CALL INSTRUCTION
(SIGL).

70
2.9 Compound Variables And STEM

Compound variables are a way to create a one-dimensional array or a list of


variables in REXX. Subscripts do not necessarily have to be numeric. A
compound variable contains at least one period with characters on both sides of
it. The following are examples of compound variables.

FRED.5
Array.Row.Col
employee.name.phone

The first variable in a compound variable always remains a symbol with no


substitution. The remaining variables in a compound variable take on values
previously assigned. If no value was previously assigned, the variable takes on
the uppercase value of the variable name.

You can use a DO loop to initialize a group of compound variables and set up an
array.

DO i = 1 TO 6

SAY 'Enter an employee name.'


PARSE PULL employee.i
END

STEMS : When working with compound variables, it is often useful to initialize an


entire collection of variables to the same value. You can do this easily with a
stem. A stem is the first variable name and first period of the compound variable.
Thus every compound variable begins with a stem. The following are stems:
FRED.
Array.
employee.

you can alter all the compound variables in an array through the stem. you can
alter all the compound variables in an array through the stem.assignment
instruction:

employee. = 'Nobody'

As a result, all compound variables beginning with employee. , whether or not


they were previously assigned, return the value Nobody. Compound variables that
are assigned after the stem assignment are not affected

SAY employee.5/* Displays 'Nobody' */

You can use stems with the EXECIO command when reading to and writing from
a data set. You can also use stems with the OUTTRAP external function when
trapping command output:

71
2.10 Sample REXX Program

/*REXX*/
/* THIS PROGRAM ENCRPYTS/DECRYPTS A DATA SET*/
/* USAGE : TSTMAC CODE DDNAME1 DDNAME2 KEY*/
PARSE ARG CODE DDNAME1 DDNAME2 KEY
ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ '
SUB = 'ZYXWABCDVU TSRQPONMLKJIHGFE'
/* FOR ENCRYPTION THIS MACRO REPLACES THE CHARACTER WITH THE */
/*CORRESPONDING CHARACTER IN SUB */

ADDRESS TSO
"ALLOC F(IN) DA('"DDNAME1"') SHR"
"ALLOC F(OUT) DA('"DDNAME2"') SHR"
'EXECIO * DISKRU IN ( FINIS STEM Q'
FIRST_CHARACTER = 1
IF RC > 0 THENDO
SAY 'ERROR IN ALLOCATE FILE .EXITING ..'
EXIT
END
DO LINE = 1 TO Q.0 /*FOR EACH LINE*/
LINE_LENGTH = LENGTH(Q.LINE)
DO CHARACTER=1 TO LINE_LENGTH/*FOR EACH CHARACTER*/
CH = SUBSTR(Q.LINE,CHARACTER,1)
IF KEY = '' THEN/* IF KEY IS NOT SPECIFIED */
CH = GET_SUB(CODE,CH) /*ENCRYPTION BY SUBSTITUTION*/
ELSE
CH = BITXOR(CH,KEY)/* ENCRYPTION BY XOR BETWEEN CH AND*/
/*KEY*/
IF CHARACTER = FIRST_CHARACTER THEN
P.LINE = CH
ELSE
P.LINE = P.LINE!!CH
END
END
'EXECIO * DISKW OUT ( FINIS STEM P'
"FREE F(IN)"
"FREE F(OUT)"
EXIT

72
/*THIS PROCEDURE RETURNS THE REPLACEMENT CHARACTER*/
GET_SUB : PROCEDURE EXPOSE SUB ALPHABET
ARG CODE1,CH1
DO I = 1 TO 27
IF CODE1 = 'E' THEN
IF SUBSTR(ALPHABET,I,1) = CH1 THEN
RETURN SUBSTR(SUB,I,1)
ELSE
NOP
ELSE
IF SUBSTR(SUB,I,1) = CH1 THEN
RETURN SUBSTR(ALPHABET,I,1)
ELSE
NOP
END
RETURN CH1

73
2.11 REXX Coding Standards

CCI designed a REXX coding standard. It mentions about naming conventions of


variable names, Program structure, coding structure, naming convention of dialog
components like panels, skeletons, tables. Refer to current version of REXX
coding standards.

74
3. ISREDIT MACROS

You can use edit macros, which look like ordinary editor commands, to extend
and customize the editor. You create an edit macro by placing a series of
commands into a data set or member of a partitioned data set. Then you can run
those commands as a single macro by typing the defined name in the
commandline.

75
EDIT MACROS

♦ Edit macros are used to extend and customize the editor


♦ You create an edit macro by placing a series of commands
into a data set or member of a partitioned data set.
♦ Edit macros can contain edit assignment statements that
communicate between a macro and the editor.
♦ Edit macros can be either CLISTs or REXX EXECs , or
program macros written in a programming language (such as
FORTRAN, PL/I, or COBOL).
♦ Edit macros have access to the dialog manager and system
services.
♦ All edit macros must have an ISREDIT MACRO statement as
the first edit command.

You can use edit macros to:


♦ Perform repeated tasks
♦ Simplify complex tasks
♦ Pass parameters
♦ Retrieve and return information

76
3.1 ISPF/PDF Macro Command Descriptions Index

ISPF/PDF macros may contain entries that may be a command, an assignment


statement or either. The column 'Type' indicates which way a particular macro
command may be used; c = command only, a = assignment statement only, or
c/a = either.

MACRO TYPE DESCRIPTION


AUTOLIST c/a set or obtain current autolist mode
AUTONUM c/a set or obtain current autonum mode
AUTOSAVE c/a set or obtain current autosave mode
BLKSIZE a obtain blocksize of current data set
BOUNDS c/a set or obtain left and right boundary columns
BUILTIN c execute a built-in edit command
CANCEL c end an edit session without saving latest
changes
CAPS c/a set or obtain current caps mode
CHANGE c search for a string and change it to another
string
CHANGE_COUNTS a obtain number of changed strings
COPY c copy a PDS member or data set into current
data
CREATE c create a new PDS member from the current
data
CTL_LIBRARY a obtain LMF library lock status
CURSOR c/a set or obtain current cursor position
DATA_CHANGED a obtain current status of changed data
DATA_WIDTH a obtain logical data width
DATAID a obtain data ID for current data set
DATASET a obtain current data set name
DEFINE c define a session-only macro command,
program or alias
DELETE c delete selected lines from current data set
DISPLAY_COLS a obtain column numbers of displayed data
DISPLAY_LINES a obtain top and bottom line numbers of
displayed data
DOWN c scroll down a variable line amount
EDIT c invoke another edit session
END c end the current edit session, saving the data
EXCLUDE c exclude selected lines from the display
EXCLUDE_COUNTS a obtain line counts from last EXCLUDE
command
FIND c find a search string in any or selected display
lines
FIND_COUNTS a obtain line counts from last FIND command
FLOW_COUNTS a obtain line counts from last TFLOW command
HEX c/a set or obtain hexadecimal display mode
IMACRO c/a set or obtain the initial edit macro
INSERT c create one or more blank lines for new data

77
MACRO TYPE DESCRIPTION
LABEL c/a set or obtain a line label
LEFT c scroll display data to the left
LEVEL c/a set or obtain library member modification level
LINE a set or obtain line data values
LINE_AFTER a add a specific-data line after indicated line
LINE_BEFORE a add a specific-data line before indicated line
LINENUM a obtain current line number of a given label
LOCATE c locate a specific data line
LRECL a obtain the logical record length
MACRO c identify a command as a macro
MACRO_LEVEL a obtain current macro nesting level
MASKLINE a set or obtain mask line value
MEMBER a obtain the current member name
MEND c end a batch macro in MVS/370 environment
MODEL c copy a development model into the current
data
MOVE c move a library member into the current data
NONUMBER c turn off number mode of the current data
NOTES c/a set or obtain the current note mode
NULLS c/a set or obtain the current nulls mode
NUMBER c/a set or obtain the current number mode
PACK c/a set or obtain the current pack mode
PROCESS c process input line commands and changes
PROFILE c/a define, switch, lock, unlock and display edit
profile
RANGE_CMD a identify an entered key command
RCHANGE c repeatedly process the most recent CHANGE
request
RECFM a obtain the current data record format
RECOVERY c/a set or obtain the edit recovery mode
RENUM c turn on number mode and renumber all data
lines
REPLACE c replace a data set member
RESET c reset the line command area
RFIND c repeat a find of a search string
RIGHT c scroll the data to the right
RMACRO c/a set or obtain current recovery macro name
SAVE c save the current data into a data set
SCAN c/a set or obtain the current scan mode setting
SEEK c seek a data string and place cursor on that
line
SEEK_COUNTS a obtain counts from last SEEK command
SHIFT ( c shift all columns to the left
SHIFT ) c shift all columns to the right
SHIFT < c shift program statements to the left
SHIFT > c shift program statements to the right
SORT c sort data into a indicated order
STATS c/a set or obtain PDS member statistics
SUBMIT c submit data to run as a batch job

78
MACRO TYPE DESCRIPTION
TABS c/a set or obtain the tabs mode and define tab
character
TABSLINE a set or obtain the tabs line
TENTER c set text entry mode for multi-line "power
typing"
TFLOW c text flow a paragraph to restructure
fragmented pieces
TSPLIT c text split a line, moving some data to the next
line
UNNUMBER c remove sequence numbers and set number
mode off
UP c scroll up through the data a specified amount
USER_STATE a save and restore the user status of the edit
display
VERSION c/a set or obtain the ISPF library member version
number
XSTATUS a set or obtain a lines exclude status

79
3.2 ISPF/PDF Edit Macro Commands

Commonly used edit macros commands like Bound, change, Cursor, Edit are
described in this sections.

80
BOUNDS ISPF/PDF Edit Macro Command
ISREDIT BOUNDS lcol rcol

ISREDIT (lvar, rvar) = BOUNDS

♦ Setting of Left and Right boundaries

♦ Assignment of current boundaries in variables

The 'lcol' parameter is the left boundary column value, which will
be set. The 'rcol' parameter is the right boundary column value to
be set. The 'lvar' and 'rvar' parameters are the names of the
variables that will receive the current left and right boundaries
respectively.

81
The BOUNDS macro allows for the setting of the left and right boundaries and
saving them in the edit profile. The assignment statement form of the BOUNDS
macro provides the current boundaries values in variables.

If both the BOUNDS macro command and the BOUNDS line command are used
at the same time, then the BOUNDS line command will override the macro
command.

Possible return codes are:

0 - the command or statement ended successfully


4 - the specified right boundary is greater than the default, so the
default will be used
12 - one or more of the specified boundaries is invalid
20 - a critical error has occurred

Example #1 - the default boundaries will be set:

ISREDIT BOUNDS

Example #2 - set the right boundary to column 72, while leaving the left
boundary alone by specifying an asterisk("*"):

ISREDIT BOUNDS * 72

Example #3 - obtain the current left boundary and put into variable &L:

ISREDIT (L) = BOUNDS

82
The CANCEL ISPF/PDF Edit Macro Command

ISREDIT CANCEL

♦ Terminate an edit session


♦ Undo the changes since the beginning of last save

The following is an example of the CANCEL macro command:

ISREDIT CANCEL

This will cause the current edit session to be cancelled.

Possible return codes are:

0 - the command or statement ended successfully


20 - a critical error has occurred

83
The FIND ISPF/PDF Edit Macro Command
ISREDIT FIND str {col1 {col2 } }
{label1 label2}
{NEXT } {ALL } {FIRST} {LAST } {PREV}
{CHARS } {PREFIX} {SUFFIX} {WORD }
{X} {NX}

THE FIND MACRO COMMAND MAY BE USED TO FIND A


SEARCH STRING IN ANY OR SELECTED DISPLAY LINES

♦ ‘str’ is the string that will be searched for


♦ ‘col1’ and ‘col2’ are optional range of column numbers that may be used
to limit the search done by the FIND command
♦ 'label1 label2' parameter identifies two labels that specify a range of lines
that will searched by the FIND macro command. The defaults are the
labels .ZFIRST and .ZLAST
♦ The default ‘NEXT’ parameter indicates the search will begin at the next
position after the cursor and will scan forward to the next occurrence
♦ The 'ALL' parameter indicates the search will begin at the top of the data
and will scan ahead to find all occurrences of the string
♦ The 'FIRST' parameter indicates the search will begin at the top of the
data, but it will stop at the first occurrence of the string
♦ The 'LAST' parameter indicates the search will begin at the bottom of the
data and scan backwards to locate the last occurrence of the string
♦ The 'PREV' parameter indicates the search will begin at the current
cursor location and scan backward to locate the previous occurrence of
the string
♦ The 'PREFIX' parameter indicates the string must be found as a prefix of
a word
♦ The 'SUFFIX' parameter indicates the string must be found as a suffix of a
word
♦ The default 'CHARS' parameter indicates the string may be found
anywhere the characters match
♦ The parameter 'WORD' indicates the string will be found when it is
surrounded by blanks, or other alphanumeric characters, on both sides
♦ The 'X' parameter indicates only excluded lines are searched. The 'NX'
parameter indicates only non-excluded lines are searched

84
String to be searched is any one of the following
Simple string - Not case sensitive
Hex string - eg. X’c27B’
Character string - Case sensitive (start with ‘c’) eg. C’Don’
Picture string - starts with ‘p’ eg. P’

Possible return codes are:

0 - the command or statement ended successfully


4 - the search string was not found
12 - an error was detected with the syntax
20 - a critical error has occurred

The following are examples of the FIND macro command:

Example #1 - find lines that contain the letters THEN:


ISREDIT FIND C'THEN'

Example #3 - find first line between .A and .C with prefix of THEN:

ISREDIT FIND THEN .A .C FIRST PREFIX

Example #4 - find last excluded line from .A to .B with suffix of THEN:

ISREDIT FIND THEN .A .B LAST SUFFIX X

Example #5 - find the first preceding non-excluded line within labels


.A and .C with a word equal to THEN in columns 1 through 5:

ISREDIT FIND THEN .A .C PREV WORD 1 5 NX

Example#6 Find all the 4 digit numerals in 8 th column

"ISREDIT F P'####' 8 ALL"

Example#7 : Find all strings matching the pattern ‘-anteil-‘ followed by 2 digit
number.

“ISREDIT F P'-anteil-##' ALL”

85
The EXCLUDE ISPF/PDF Edit Macro Command

ISREDIT EXCLUDE str col1 col2 label1 label2


{NEXT or ALL or FIRST or LAST or PREV }
{CHARS or PREFIX or SUFFIX or WORD}

THE EXCLUDE MACRO COMMAND MAY BE USED TO EXCLUDE LINES


FROM THE DISPLAY BY REPLACING LINES CONTAINING A SEARCH
STRING WITH A DASHED LINE UNTIL A RESET OR RESET EXCLUDED
COMMAND IS ISSUED.

The EXCLUDE command may be used with the FIND or CHANGE commands
to locate a string, change the string, and then exclude that line from the
display.

♦ ‘str’ is the string that will be searched for, to exclude lines


♦ ‘col1’ and ‘col2’ are the optional range of column numbers
♦ ‘label1 and ‘label2’ are range of line numbers that will be searched by
exclude command
♦ NEXT or ALL or FIRST or LAST or PREV denotes the search order
♦ ‘PREFIX’ parameter indicates string must be found as a prefix of a word.
♦ ‘SUFFIX’ parameter indicates string must be found as a suffix of a word.
♦ The default 'CHARS' parameter indicates the string may be found
anywhere the characters match.
♦ The parameter 'WORD' indicates the string will be found when it is
surrounded by blanks, or other non-alphanumeric characters, on both
sides

86
Examples:

Example #1 - exclude lines that contain the letters THEN:


ISREDIT EXCLUDE THEN

Example #2 - exclude last line between .A and .B with suffix of THEN:


ISREDIT EXCLUDE THEN .A .B LAST SUFFIX

Example #3- exclude the first preceding line within labels .A and .C with a word
equal to THEN in columns 1 through 5:

ISREDIT EXCLUDE THEN .A .C PREV WORD 1 5

Possible return codes are:

0 - the command or statement ended successfully


4 - the search string was not found
8 - no lines were excluded
20 - a critical error has occurred

87
The XSTATUS ISPF/PDF Edit Macro Command

ISREDIT (var) = XSTATUS lnptr


ISREDIT XSTATUS lnptr = X or NX

THE XSTATUS ASSIGNMENT STATEMENT MAY BE USED TO


♦ SET THE EXCLUDE STATUS OF A LINE
♦ OBTAIN THE EXCLUDE STATUS OF THE SPECIFIED LINE BY
STORING IT IN A VARIABLE

THE EXCLUDE COMMAND SHOULD BE USED TO EXCLUDE


SEVERAL LINES AT ONE TIME AND THE FIND COMMAND
SHOULD BE USED TO DISPLAY SEVERAL LINES, THAT WERE
EXCLUDED, AT ONE TIME.

EXAMPLE #1 - EXCLUDE LINE NUMBER 6:


ISREDIT XSTATUS 6 = X

EXAMPLE #1 - STORE THE EXCLUDE STATUS OF LINE &LN IN


VARIABLE &EXCLSTAT:
ISREDIT (EXCLSTAT) = XSTATUS &LN

88
CHANGE ISPF/PDF Edit Macro Command

ISREDIT CHANGE str1 str2


[ lbls]
[ NEXT Or ALL Or FIRST Or LAST Or PREV ]
[ CHARS Or PREFIX Or SUFFIX Or WORD ]
[ X Or NX ]
[ col1 ] [col2 ]

THE CHANGE MACRO COMMAND PERFORMS A SEARCH FOR A STRING


AND CHANGES IT TO ANOTHER STRING.

♦ THE 'STR1' PARAMETER IS THE EXISTING STRING TO BE SEARCHED


FOR. THE 'STR2' PARAMETER IS THE STRING THAT 'STR1' WILL BE
CHANGED TO.

♦ LBLS PARAMETER SPECIFIES THE RANGE OF LABELS TO BE


SEARCHED

♦ NEXT OR PREV OR ALL OR FIRST OR LAST DENOTES THE SEARCH


ORDER.

♦ CHARS OR PREFIX OR SUFFIX OR WORD MEANS THE STRING IS


CONSIDERED AS A WORD OR PREFIX OR SUFFIX OR CHARS FOR THE
SEARCH

♦ THE X/NX MEANS WHETHER THE STRING TO BE SEARCHED ON


EXCLUDED LINES OR NON-EXCLUDED LINES

♦ THE 'COL1' AND 'COL2' PARAMETERS SPECIFY A BEGINNING AND


ENDING COLUMN NUMBER RESPECTIVELY THAT WILL BE USED TO
LIMIT THE SEARCH.

89
CHANGE ISPF/PDF Edit Macro Command

The following are examples of the CHANGE macro command:

Example #1:
ISREDIT CHANGE ME YOU
This example, the next occurrence of ME is changed to YOU. The letters ME can
be upper, lower or mixed case letters, and may be located anywhere within a
word, on any line

Example #2:

ISREDIT (CURMEM) = MEMBER


ISREDIT CHANGE WORD &CURMEM "MEMBER:&CURMEM" 1 20 .ZFIRST
.LAB9
In this example, the current member name is put it into the variable named
CURMEM, then an identifier is added to that name, when it appears in columns 1
through 20 in the lines from the beginning to the label of .LAB9.

Possible return codes are:

0 - the command or statement ended successfully


4 - the specified string 'str1' was not found
8 - the string 'str1' could not be changed to 'str2' because 'str2' is longer than 'str1'
and there was no substitution on at least one change.
12 - the string 'str1' does not fit between the specified columns
20 - a critical error has occurred

90
The DELETE ISPF/PDF Edit Macro Command

ISREDIT DELETE { ALL X or NX [lptr-range]}


{[ALL] X or NX lptr-range}
{lptr}
{lptr-range}

THE DELETE MACRO MAY BE USED TO DELETE LINES FROM


THE DATA BEING EDITED. DELETE CAN SPECIFY A SINGLE
LINE OR A RANGE OF LINES. IT CAN LIMIT THE LINES TO BE
DELETED TO ALL EXCLUDED OR NONEXCLUDED LINES IN THE
DATA, OR TO ALL EXCLUDED OR NONEXCLUDED LINES
WITHIN A LINE POINTER RANGE.

♦ ‘ALL’ indicates all matching lines will be deleted


♦ 'X ! NX' parameters indicate the lines being deleted will be
those that are excluded or not excluded, respectively.
♦ The 'lptr' parameter indicates a label or relative line number is
to be used to specify which lines will be deleted.
♦ The 'lrange' parameter indicates a range of relative line
numbers or labels specifying the range of lines to be deleted.
♦ When either one is omitted, then one of the defaults, .ZFIRST
and .ZLAST, will be used.

91
Example #1 - delete all non-excluded lines:
ISREDIT DELETE ALL NX

Example #2 - delete the lines between labels .HERE and .THERE that have a
blank in column 1:

ISREDIT RESET X .HERE .THERE


ISREDIT EXCLUDE ALL " " 1 .HERE .THERE
ISREDIT DELETE ALL X .HERE .THERE

Example #3 - delete the last line of the current data set:

ISREDIT DELETE .ZLAST

Example #4 - delete the first 15 lines of current data set:

ISREDIT DELETE 1 15

Possible return codes are:

0 - the service ended successfully, deleting the lines


4 - no lines were deleted
8 - no standard records exist to be deleted
12 - a line number was invalid
20 - a critical error has occurred

92
CHANGE_COUNTS ISPF/PDF Edit Macro Command

ISREDIT (var1,var2) = CHANGE_COUNTS

THE CHANGE_COUNTS ASSIGNMENT STATEMENT CAN QUERY


THE CHANGE COUNTS SET BY THE LAST CHANGE COMMAND
AND STORE THE VALUES IN VARIABLES.

The 'var1' and 'var2' parameters are names of variables that will
receive the 8- character number of the strings, left-padded with
zeros, that were changed and that could not be changed,
respectively.

The following are examples of the CHANGE_COUNTS


assignment statement:

Example #1 - obtain the number of changes into the variable


&CHGS:

ISREDIT (CHGS) = CHANGE_COUNTS

Example #2 - obtain the number of change errors into the


variable &NOT:

ISREDIT (,NOT) = CHANGE_COUNTS

Example #3 - obtain both the number of changes and change


errors into the variables &CHGS and &NOT:

ISREDIT (CHGS,NOT) = CHANGE_COUNTS

93
The CURSOR ISPF/PDF Edit Macro Command

ISREDIT (var1,var2) = CURSOR


ISREDIT CURSOR = lptr col

THE CURSOR ASSIGNMENT STATEMENT MAY BE USED TO


QUERY THE CURRENT CURSOR POSITION OR SET THE
POSITION OF THE CURSOR TO A RELATIVE LINE OR LABEL.

THE CHANGE, EXCLUDE, FIND, SEEK, AND TSPLIT COMMANDS


MAY ALTER THE CURSOR POSITION.

THE 'VAR1' IS A VARIABLE NAME WHERE THE SIX-DIGIT LINE


NUMBER, LEFT-PADDED ZEROS, IS STORED. THE 'VAR2' IS THE
VARIABLE NAME WHERE THE THREE-DIGIT COLUMN NUMBER,
LEFT-PADDED WITH ZEROS, IS STORED.

THE 'LPTR' PARAMETER IS THE NEW CURSOR RELATIVE LINE


NUMBER OR LABEL. THE OPTIONALLY 'COL' PARAMETER
SPECIFIES A COLUMN NUMBER WHERE THE CURSOR IS TO BE
POSITIONED. THE VALUE IS ZERO IF THE MEMBER IS EMPTY.

94
The following are examples of the CURSOR assignment statement:

Example #1 - obtain the current cursor position line number into the variable
&WHERE:

ISREDIT (WHERE) = CURSOR

Example #2 - set the cursor to column 1 of the first data line:

ISREDIT CURSOR = 1 1
Example #3 - set the cursor to column 1 of the last data line:

ISREDIT CURSOR = .ZLAST 1

Example #4 - set the cursor position to the line at label .LBL, without changing the
column position:

ISREDIT CURSOR = .LBL

Possible return codes are:

0 - the command or statement ended successfully


4 - the column number is beyond the data, so the line number will be
incremented
12 - the line number is invalid
20 - a critical error has occurred

95
The LABEL ISPF/PDF Edit Macro Command

ISREDIT (varlab,varlev) = LABEL lptr

ISREDIT LABEL lptr = lblname { lvl }

THE LABEL ASSIGNMENT STATEMENT MAY BE USED TO SET


THE VALUES FOR A LINE
LABEL OR OBTAIN VALUES FROM AN EXISTING LINE LABEL BY
STORING THE VALUES IN DIALOG VARIABLES.

♦ 'VARLAB' PARAMETER IS THE NAME OF A VARIABLE THAT


WILL RECEIVE THE NAME OF THE LABEL
♦ 'VARLEV' PARAMETER IS THE NAME OF THE VARIABLE THAT
WILL RECEIVE THE 3-CHARACTER LABEL NESTING LEVEL
VALUE
♦ THE 'LPTR' PARAMETER IS A LINE POINTER (LABEL OR
RELATIVE LINE NUMBER) INDICATING THE LINE WHERE THE
LABEL WILL BE SET OR RETRIEVED FROM
♦ THE 'LBLNAME' PARAMETER IS THE NAME A LABEL, ONE TO
EIGHT CHARACTERS STARTING WITH A PERIOD AND A NON-
Z CHARACTER
♦ THE 'LVL' PARAMETER IS THE HIGHEST NESTING LEVEL
WHERE THIS LABEL IS VISIBLE TO YOU OR A MACRO. THE
LEVEL NUMBER CANNOT EXCEED THE CURRENT NESTING
LEVEL UP TO A MAXIMUM OF 255

96
Examples

1. ISREDIT LABEL .ZCSR = .POINT

This isredit macro command puts the label .point on the current cursor position.

2. ISREDIT (LBLNAM) = LABEL .ZCSR


This command assigns the label number of current line to the variable LBLNAM.

Possible return codes are:


0 - the command or statement ended successfully
4 - a label name was not returned because the line has no label
8 - new label was set, replacing an existing label at the same level
12 - the specified line number is not within the current data
20 - a critical error has occurred

97
The END ISPF/PDF Edit Macro Command

ISREDIT END

THE END MACRO MAY BE USED TO END THE CURRENT EDIT


SESSION, WHILE SAVING THE DATA.

THE FOLLOWING IS AN EXAMPLE OF THE END MACRO


COMMAND:
ISREDIT END
THIS EXAMPLE WILL END THE CURRENT EDIT SESSION.

POSSIBLE RETURN CODES ARE:

0 - THE COMMAND OR STATEMENT ENDED SUCCESSFULLY,


SAVING THE DATA
4 - THE NEW DATA IS SAVED
12 - THE END DID NOT COMPLETE, EITHER AUTOSAVE OFF SET
OR THE DATA COULD NOT BE SAVED IN THE LIBRARY
20 - A CRITICAL ERROR HAS OCCURRED

98
3.3 Sample ISREDIT MACRO

Then following edit macro comments out all lines in a section of COBOL program,
section name is passed as a parameter. The edit macro can be invoked from
ISPF editor as

“COMMENT 1000-initialize”

here comment is the name of the edit macro and 1000-initialize is the section to
be commented.

/*REXX*/
"ISREDIT MACRO (PARM1)"
"ISREDIT F 8 ALL" PARM1/* find the section name at the 8th
column*/
CALL ERR_ROUTINE
"ISREDIT LABEL .ZCSR = .A" /*put the label on the first line
of the section */
CALL ERR_ROUTINE
"ISREDIT (X Y) = CURSOR"
CALL ERR_ROUTINE
X = X + 1
"ISREDIT CURSOR = (X) (Y)"
CALL ERR_ROUTINE
"ISREDIT FIND SECTION NEXT"
IF RC = 4 THEN /*IF IT IS THE LAST SECTION*/
DO
"ISREDIT CHANGE ALL ' ' '*' 7 .A .ZLAST"
EXIT
END
ISREDIT (X Y) = CURSOR"
CALL ERR_ROUTINE
X = X - 1
"ISREDIT CURSOR = (X) (Y)"
CALL ERR_ROUTINE
"ISREDIT LABEL .ZCSR = .B"/* put label on the last line of
the section */
CALL ERR_ROUTINE
"ISREDIT CHANGE ALL ' ' '*' 7 .A .B"
CALL ERR_ROUTINE
"ISREDIT SAVE"
CALL ERR_ROUTINE
EXIT
ERR_ROUTINE: PROCEDURE EXPOSE RC
IF RC > 0 THEN DO
SAY "MACRO ERROR!"
"ISREDIT CANCEL"/* Undo the changes */
EXIT
END

This edit macro can also be called from a REXX program using an ISPXEC EDIT
command.

99
4. ISPF SERVICES

All the ISPF services are listed below. Commonly used ISPF services are
described in the next section. Detailed information about all the ISPF services are
obtained from MVS/QuickRef ( product - ISPF SERVICES ).

4.1 ISPF Services Index

Service Description
ADDPOP Begins pop-up window mode for panels
BRIF Browse interface from dialog program w/ flexible data capability
BROWSE Direct access to Browse from dialog
CONTROL Set environment options for display and error processing
EDIF Provide a dialog interface to the Edit service
EDIREC Provides recovery for the Edit interface facility
EDIT Allows direct access to the Edit service
EDREC Provides recovery for Edit service
DISPLAY Performs a panel display
FTCLOSE Ends file tailoring process and disposes of output file
FTERASE Erases a file tailoring output library member
FTINCL Initiates file tailoring process by including a skeleton file
FTOPEN Begins file tailoring process by opening skeleton library
GETMSG Get the message text, help panel and alarm indicator
GRERROR Provides error information from graphic service calls
GRINIT Initialize the ISPF/GDDM interface
GRTERM Terminates the ISPF/GDDM interface
ISPSTART Initialize ISPF, optionally invoking a panel, command or program
LIBDEF Defines application libraries for user dialog
LIST Write data lines to ISPF list data set from dialog
LMACT Activate a LMF-controlled hierarchy from a dialog
LMCLOSE Closes a data set
LMCOMP Compresses a partitioned data set
LMCOPY Copies partitioned data set members or sequential data sets
LMDEACT Deactivate a LMF-controlled hierarchy from a dialog
LMDFREE Frees a data set list ID created by a LMDINIT
LMDINIT Initiates a data set list by generating an ID for a level/volume
LMDLIST Provide a data set list for a LMDINIT data set list ID
LMERASE Erases an ISPF library or MVS data set
LMFREE Frees the data set associated with a given data-id
LMGET Get another record of a data set
LMHIER Hierarchy structure of the library is indicated in a table
LMINIT Initiates library access services for a data-id
LMMADD Adds an ISPF library or partitioned data set member
LMMDEL Deletes an ISPF library or partitioned data set member
LMMDISP Provides member selection list processing actions
LMMFIND Finds an ISPF library or partitioned data set member
LMMLIST Lists members of an ISPF library or partitioned data set
LMMOVE Moves partitioned data set members or sequential data sets

100
Service Description
LMMREN Renames an ISPF library or partitioned data set member
LMMREP Replaces an ISPF library or partitioned data set member
LMMSTATS Statistics for partitioned data set are saved in variables
LMOPEN Opens a data set
LMPRINT Prints to the list data set
LMPROM Promotes a member or seq. data set to a controlled ISPF library
LMPUT Writes a record to a data set
LMQUERY Queries the data set to obtain the requested information
LMRENAME Renames an ISPF library
LMREVIEW Reviews the controls set for a library
LOG Write a record to the log data set
PQUERY Query a panel definition to extract information
QLIBDEF Query LIBDEF definition
REMPOP Removes a previously created pop-up window
SELECT Starts ISPF dialog execution of panels, commands and/or programs
SETMSG Sets a message to be displayed on next panel
TBADD A row is added to a table
TBBOTTOM Moves the current row pointer (CRP) to last row of the table
TBCLOSE Closes a table and optionally saves a copy in a library
TBCREATE Creates a new table and opens it
TBDELETE Deletes a table row
TBDISPL Display all or part of an ISPF table
TBEND Closes a table without saving it
TBERASE Deletes a table from a table library
TBEXIST Determines if a table key value (row) exists
TBGET Obtain a table row
TBMOD Modify existing row or add new row
TBOPEN Open a table residing in a table library
TBPUT Updates a table row
TBQUERY Requests table information
TBSARG Sets the search argument for a following TBSCAN or TBDISPL
TBSAVE Saves an opened table to a library without closing the table
TBSCAN Scans for a table row matching TBSARG set or supplied list
TBSKIP Moves the CRP either direction a specified number of rows
TBSORT Performs a sort of the table
TBSTATS Obtains table statistics
TBTOP Places the CRP ahead of the first row of the table
TBVCLEAR Clears all related table variables to null values
VCOPY Allows a program to copy a variable value
VDEFINE Allows a program to access/define a variable
VDELETE Allows a program to remove variable definition/access from ISPF
VERASE Removes variables from shared and/or profile pool(s)
VGET Obtains a variable value from shared or profile pool
VIEW Allows you to view data as if in EDIT mode
VPUT Updates variable values in shared or profile pool
VREPLACE Allows a program to update variables in the shared/profile pool
VRESET Allows a program to remove all its variable definitions at once

101
The EDIT ISPF/PDF Service

ISPEXEC EDIT DATASET(dsn)


{VOLUME(volser) }
{PASSWORD(pswd).}
{ PANEL(panel) }
{ MACRO(mac) }
{ PROFILE(prof) }
{ FORMAT(fmt) }
{ LOCK(YES or NO).}
{ MIXED(YES or NO).}
{ CONFIRM(YES or NO) }

The most common form of the macro command is

ISPEXEC EDIT DATASET(dsn)


MACRO(mac)

♦ DSN IS THE NAME OF THE DATA SET TO BE EDITED


♦ MAC IS A NAME OF AN EDIT MACRO THAT WILL BE
EXECUTED

THE EDIT SERVICE ALLOWS A DIRECT INTERFACE TO THE


ISPF/PDF EDITOR, WITHOUT GOING THROUGH THE EDIT
ENTRY PANEL.

Example
DSNAM = ‘CCI.U.PKXXX.T001.AP.T8150’
"ISPEXEC EDIT DATASET('&DSNAM'),MACRO(CHGMANDZ)"
Here ‘CHGMANDZ’ is the name of ISREDIT MACRO.

102
The DISPLAY ISPF Service

ISPEXEC DISPLAY { PANEL(panel) }


{ MSG(msgid) }
{ CURSOR(cursorfld) }
{ CSRPOS(cursorpos) }
{ COMMAND(stackbuff) }
{ RETBUFFR(retbuff) }
{ RETLGTH(retlen) }
{ MSGLOC(msgfld) }

THIS SERVICE IS USED IN REXX ROUTINES TO DISPLAY


PANELS. MOST COMMONLY USED FORM OF DISPLAY IS
IPEXEC DISPLAY { PANEL(PANEL) }

THE DISPLAY SERVICE PERFORMS A DISPLAY OF A


PREDEFINED PANEL TO DISPLAY A COMBINATION OF
CONSTANT AND VARIABLE DATA ALONG WITH AN OPTIONAL
MESSAGE. THE PANEL SPECIFIC LOGIC IS PROCESSED WITH
THE DISPLAY AND THEN THE CALLER RECEIVES CONTROL
BACK FROM THE DISPLAY SERVICE ROUTINE.

Example
“ISPEXEC DISPLAY PANEL(COMPILE)”

Panels are described in advanced section of TSO/ISPF training


material.

103
The LIBDEF ISPF Service

ISPEXEC LIBDEF libtype


{DATASET or EXCLDATA or LIBRARY or EXCLLIBR }
{ID(datasets) or ID(ddname) }
{COND or UNCOND }

Most commonly used form of this service is


ISPEXEC LIBDEF libtype
{DATASET or LIBRARY }
{ID(datasets) or ID(ddname) }

THE LIBDEF SERVICE PERMITS THE DEFINITION OF


APPLICATION LIBRARIES BY THE USER FOR PANELS,
MESSAGES, SKELETONS, TABLES, AND PROGRAMS.
LIBTYPE IS THE TYPE OF APPLICATION LIBRARY , AND THE
VALUE IS ONE OF THE FOLLOWING.
♦ ISPMLIB = message library
♦ ISPPLIB = panel library
♦ ISPSLIB = skeleton library
♦ ISPTLIB = table input library
♦ ISPTABL = table output library
♦ ISPFILE = file tailoring output file
♦ ISPLLIB = load module library
♦ xxxxxxxx = generic library
The 'DATASET' means a list of cataloged data set names is supplied.
The 'LIBRARY' parameter indicates that a DDname of pre-allocated data sets
is given.
Example
"LIBDEF ISPPLIB LIBRARY ID(SCONPLIB)"
Application panel library is defined using this definition. Here sconplib
is the ddname of preallocated data set using the alloc statement
"ALLOC FI(SCONPLIB) DA('CCI.PKXXX.PLIB') SHR REU"
Allocation macro uses LIBDEF service to define application libraries.
See Advanced section of TSO/ISPF training material.

104
The VGET ISPF Service

ISPEXEC VGET name { ASIS or SHARED or PROFILE }

THE VGET SERVICE WILL RETRIEVE A COPY OF THE VARIABLE


VALUE FROM THE SHARED OR APPLICATION PROFILE POOL
AND PLACES IT INTO THE FUNCTION POOL. THE FUNCTION
POOL VARIABLE IS UPDATED, IF IT EXISTS ALREADY, OR IT
WILL BE CREATED, IF IT DOES NOT. FOR CREATION, A
CHARACTER VARIABLE IS SET TO BLANKS, FIXED, BIT, AND
HEX VARIABLES ARE SET TO ALL ZEROS (NULL).

♦ 'ASIS' PARAMETER SPECIFIES THAT THE SHARED POOL


WILL SEARCHED FIRST, THEN THE PROFILE POOL TO
LOCATE THE VARIABLE NAME.

♦ 'SHARED' OPTION INDICATES ONLY THE SHARED POOL WILL


SEARCHED FOR THE VARIABLE.

♦ 'PROFILE' OPTION INDICATES THAT THE APPLICATION


PROFILE IS SEARCHED FOR THE VARIABLE VALUE AND ANY
VARIABLE WITH THE SAME NAME IN THE SHARED POOL IS
DELETED.

105
The VGET ISPF Service

Possible return codes are:


0 - the service ended successfully
8 - one or more variables were not found
12 - error during validation
16 - variable data movement ended in translation or truncation error
20 - a critical error occurred

Example#1

" ISPEXEC VGET (PNUM,PNAM,PADDR) SHARED"


In this example, all variables are copied from the shared pool to the function pool.

106
The VPUT ISPF Service

ISPEXEC VPUT name { ASIS or SHARED or PROFILE }

THE VPUT SERVICE UPDATES OR CREATE A DIALOG


VARIABLE IN THE SHARED OR APPLICATION POOL BY
COPYING THE VARIABLE FROM THE FUNCTION POOL.

'ASIS' DEFAULT SPECIFIES THAT THE SHARED POOL WILL


UPDATED IF THE VARIABLE DOES NOT EXIST IN EITHER POOL
OR IN BOTH POOLS. OTHERWISE, THE VARIABLE IS UPDATED
WHERE IT EXISTS.

'SHARED' OPTION INDICATES ONLY THE SHARED POOL WILL


BE UPDATED FOR THE VARIABLE.

'PROFILE' OPTION INDICATES THAT THE APPLICATION


PROFILE IS UPDATED FOR THE VARIABLE VALUE AND ANY
VARIABLE WITH THE SAME NAME IN THE SHARED POOL IS
DELETED.

107
The VPUT ISPF Service

Possible return codes are:

0 - the service ended successfully


8 - one or more variables were not found
16- variable data movement to the application profile ended in a translation or
truncation error
20- a critical error occurred

Example

“ISPEXEC VPUT (PNUM PNAM PADDR) SHARED “


In this example, the variables are copied from the function pool to the shared
pool.

VPUT service is used in the panel proc for copying the values of entered fields to
the shared pool. See the Panels in the Advanced section.

108
The FTOPEN ISPF Service

ISPEXEC FTOPEN { TEMP }

THE FTOPEN SERVICE STARTS THE FILE TAILORING PROCESS


BY OPENING THE SKELETON LIBRARY ALLOCATED TO THE
DDNAME ISPSLIB, WHICH MAY IDENTIFY A CONCATENATION
OF DATA SETS, BUT MUST BE ALLOCATED PRIOR TO
INVOKING ISPF. VARIABLE-LENGTH RECORDS UP TO A
MAXIMUM LENGTH OF 255 ARE PERMITTED IN THE SKELETON
FILES.
ANY OUTPUT FILE TAILORING FILE MUST BE ALLOCATED TO
THE DDNAME ISPFILE BY THE TIME THE FTOPEN IS INVOKED.
THE DATA SET FOR ISPFILE MAY BE LIBRARY FORMAT OR
SEQUENTIAL.
THE 'TEMP' OPTION INDICATES THE FILE TAILORING OUTPUT
SHOULD BE WRITTEN TO A TEMPORARY SEQUENTIAL FILE IN
FIXED-LENGTH 80 BYTE RECORDS. THE DYNAMICALLY
ALLOCATED FILE IS NAMED IN THE VARIABLE ZTEMPF WITH
ZTEMPN HOLDING THE DDNAME. OTHERWISE, THE OUTPUT OF
THE FILE TAILORING PROCESS IS WRITTEN TO ISPFILE.
THE FOLLOWING COMMAND SEQUENCE WILL SUBMIT THE
OUTPUT OF A FILE TAILORING PROCESS FOR BACKGROUND
EXECUTION:
ISPEXEC FTCLOSE
ISPEXEC VGET (ZTEMPF)
SUBMIT '&ZTEMPF'

109
The FTINCL ISPF Service

ISPEXEC FTINCL skel { NOFT }

The FTINCL service initiates the file tailoring process and


indicates the skeleton that will be used to generate file tailoring
output.

The FTINCL service can perform an FTOPEN function without the


TEMP option, if an FTOPEN service was not issued previously,
before continuing the processing for the skeleton file.

♦ 'skel' is the name of the skeleton file to be included for


processing.

♦ 'NOFT' option indicates that file tailoring will not be performed


on the skeleton, it will be copied, as is, to the output file
without variable substitution.

110
The FTINCL ISPF Service

Possible return codes are:


0 - the service ended successfully
8 - the skeleton, requested to be included, could not be found
12 - the enqueue (ENQ) failed for the skeleton, it must be in use
16 - no allocation for skeleton library/output file or data was truncated
20 - a critical error was encountered

Example#1

ISPEXEC FTINCL PHONSKEL

This example show how file tailoring will use the skeleton PHONSKEL from the
file tailoring skeleton library.

Example#2

SKLNAME = 'CMPSUBB'
"ISPEXEC FTOPEN TEMP"
"ISPEXEC FTINCL " SKLNAME
"FTCLOSE"
"VGET (ZTEMPF)"
ADDRESS TSO SUBMIT ‘&ZTEMPF’

Here, the skeleton ‘CMPSUBB’ is used to generate the temporary file tailoring
output .

111
REFERENCES

1. TSO/E V2R5 REXX/MVS User's Guide


2. TSO/E V2R5 REXX/MVS Reference
3. MVS/QuickRef- Product- ISPF SERVICES
4. MVS/QuickRef- Product- ISPF EDIT MACROS
5. ISPF Edit and Edit Macros
6. ISPF Dialog Developer's Guide and Reference

TSO/ISPF training material advanced Topics includes samples of panels,


skeleton, tables etc. Allocation of ISPF product libraries and Terminal Monitor
Program IKJEFT01 is also mentioned in the book.

112