TRN Training Material REXX

Senin S. Version 0.0 31 October, 2001

Case Consult (India) Pvt. Ltd. D-1, Block B, Technopark Campus, Trivandrum 695 581.

No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the written permission of Case Consult (India) Pvt. Ltd. Information in this document is subject to change without notice and does not represent a commitment on the part of Case Consult (India) Pvt. Ltd. This document and the referenced software described in this document is furnished under a licence agreement or nondisclosure agreement. The document and the referenced software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the document or the software on any medium except as specifically allowed in the licence or nondisclosure agreement.

Copyright 1998 Case Consult (India) Pvt. Ltd. All rights reserved.

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

Case Consult (India) Pvt. Ltd. 03/1998

REXX

C:\C\WINNT\Profiles\ar5303\Temporary Internet Files\OLK71\rexx.doc

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 IBMs System Application Architecture (SAA), which means REXX is implemented across IBMs 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.

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 IBMs VM / System product shipped in 1983. It was soon discovered that IBMs 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 IBMs 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.

REXX (Restructured Extended eXecutor) IT ALLOWS YOU TO : EXECUTE SYSTEM COMMANDS, TSO, ISPF REQUEST INPUT FROM THE TERMINAL DISPLAY OUTPUT ON THE TERMINAL EXECUTE CONTROL TSO COMMANDS UNDER PROGRAM

DO FILE MANIPULATIONS

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.

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

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.

1.4 Operators

1.4.1 Arithmetic Operators The arithmetic operators used in REXX numeric expressions are as follows Operator + * / % // ** -n +n Operation Addition Subtraction Multiplication Division, returning decimal quotient Division, returning integer quotient Division, returning remainder Exponential Negation Addition

1.4.2 Concatenation Operators The following concatenation operators are supported by REXX. Operator blank !! Operation 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 1 2 3 4 5 6 7 8 9 Operation Expressions in parentheses Prefix operators Exponential operator Multiplication and division Addition and subtraction Concatenation Comparison Logical AND Logical OR and EXCLUSIVE OR Operators () -+\ ** * / % // +!! == = \== < > >< >= <= \< \> & ! &&

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 AND OR XOR NOT Returns 1 if both comparisons are true; otherwise 0. 1 if one of several comparisons is true; Otherwise 0. 1 if only one of a group of comparisons is true; otherwise 0. 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

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

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

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.

TERMINAL INPUT AND OUTPUT

SAY PULL

DISPLAYING A LINE ON THE TERMINAL 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 */

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

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.

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

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 Elses and DOs to ENDs can have some surprising results.

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 WHEN Y = 1 THEN SAY WHEN Y = 2 THEN SAY OTHERWISE SAY Y< 0 END

Y Y Y OR

IS 0 IS 1 IS 2 > 2

Using the SELECT/WHEN/OTHERWISE/END Instruction Example "Thirty days hath September, April, June, and November; all the rest have thirtyone, 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 '.'

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.

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

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.

1.

DO 7

/* Repeats 7 times */ statement 1 statement 2 ..

END

2.
Do I = 2 to -1 by -1 say I /* End /* /* Would display:*/ 2 on 1st pass through loop */ 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*/

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

4.

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

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

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

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.

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

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

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

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.

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 */ OF Y IS RESULT

SAY SQUARE SQUARE: PROCEDURE ARG N RETURN N*N

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

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

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.

Following is the list of all string manipulating functions. Commonly used functions are explained later. Function ABBREV Description 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.

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

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

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'

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.

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 ') STRIP(' ab c ','L') STRIP(' ab c ','t') STRIP('12.7000',,0) STRIP('0012.700',,0) ->'ab c' ->'ab c ' ->' ab c' ->'12.7' ->'12.7'

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.

2.5.2 Arithmetic Functions These functions evaluate numbers from the argument and return a particular value. REXX arithmetic functions are described below. Function ABS DIGITS FORM FUZZ MAX MIN RANDOM SIGN TRUNC Description Returns the absolute value of the input number. Returns the current setting of NUMERIC DIGITS. Returns the current setting of NUMERIC FORM. Returns the current setting of NUMERIC FUZZ. Returns the largest number from the list specified, formatted according to the current NUMERIC settings. Returns the smallest number from the list specified, formatted according to the current NUMERIC settings. Returns a quasi-random, non-negative whole number in the range specified. Returns a number that indicates the sign of the input number. Returns the integer part of the input number, and optionally a specified number of decimal places.

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.

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

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

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

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)

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.

2.5.5 Formatting Functions These functions manipulate the characters and spacing in strings supplied in the argument. Function CENTER/ CENTRE COPIES FORMAT JUSTIFY * LEFT RIGHT SPACE Description Returns a string of a specified length with the input string centered in it, with pad characters added as necessary to make up the length. Returns the specified number of concatenated copies of the input string. Returns the input number, rounded and formatted. Returns a specified string formatted by adding pad characters between words to justify to both margins. Returns a string of the specified length, truncated or padded on the right as needed. Returns a string of the specified length, truncated or padded on the left as needed. 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.

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'

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 JUSTIFY('The JUSTIFY('The JUSTIFY('The blue blue blue blue sky',14) sky',8) sky',9) sky',9,'+') ->'The blue sky' ->'The blue' ->'The blue' ->'The++blue'

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

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

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 ISREDIT TSO MVS LINK ATTACH CMS DOS XEDIT
EXAMPLE

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

ADDRESS TSO FREE DATASET(TEST.COBOL.PGMLOAD ).

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

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.

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.

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.

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

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

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

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.

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

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

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.

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.

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.

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

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.

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

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

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:

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

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

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.

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.

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

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

MACRO LABEL LEFT LEVEL LINE LINE_AFTER LINE_BEFORE LINENUM LOCATE LRECL MACRO MACRO_LEVEL MASKLINE MEMBER MEND MODEL MOVE NONUMBER NOTES NULLS NUMBER PACK PROCESS PROFILE RANGE_CMD RCHANGE RECFM RECOVERY RENUM REPLACE RESET RFIND RIGHT RMACRO SAVE SCAN SEEK SEEK_COUNTS SHIFT ( SHIFT ) SHIFT < SHIFT > SORT STATS SUBMIT

TYPE c/a c c/a a a a a c a c a a a c c c c c/a c/a c/a c/a c c/a a c a c/a c c c c c c/a c c/a c a c c c c c c/a c

DESCRIPTION set or obtain a line label scroll display data to the left set or obtain library member modification level set or obtain line data values add a specific-data line after indicated line add a specific-data line before indicated line obtain current line number of a given label locate a specific data line obtain the logical record length identify a command as a macro obtain current macro nesting level set or obtain mask line value obtain the current member name end a batch macro in MVS/370 environment copy a development model into the current data move a library member into the current data turn off number mode of the current data set or obtain the current note mode set or obtain the current nulls mode set or obtain the current number mode set or obtain the current pack mode process input line commands and changes define, switch, lock, unlock and display edit profile identify an entered key command repeatedly process the most recent CHANGE request obtain the current data record format set or obtain the edit recovery mode turn on number mode and renumber all data lines replace a data set member reset the line command area repeat a find of a search string scroll the data to the right set or obtain current recovery macro name save the current data into a data set set or obtain the current scan mode setting seek a data string and place cursor on that line obtain counts from last SEEK command shift all columns to the left shift all columns to the right shift program statements to the left shift program statements to the right sort data into a indicated order set or obtain PDS member statistics submit data to run as a batch job

MACRO TABS TABSLINE TENTER TFLOW TSPLIT UNNUMBER UP USER_STATE VERSION XSTATUS

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

3.2 ISPF/PDF Edit Macro Commands Commonly used edit macros commands like Bound, change, Cursor, Edit are described in this sections.

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.

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

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

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

String to be searched is any one of the following Simple string - Not case sensitive Hex string - eg. Xc27B Character string - Case sensitive (start with c) 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

eg. CDon

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

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

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

The XSTATUS ISPF/PDF Edit Macro Command

ISREDIT (var) ISREDIT XSTATUS lnptr = 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

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.

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

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.

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

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 assignment statement: of the CHANGE_COUNTS

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

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.

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

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 NONZ 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

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

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

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.

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

Service LMMREN LMMREP LMMSTATS LMOPEN LMPRINT LMPROM LMPUT LMQUERY LMRENAME LMREVIEW LOG PQUERY QLIBDEF REMPOP SELECT SETMSG TBADD TBBOTTOM TBCLOSE TBCREATE TBDELETE TBDISPL TBEND TBERASE TBEXIST TBGET TBMOD TBOPEN TBPUT TBQUERY TBSARG TBSAVE TBSCAN TBSKIP TBSORT TBSTATS TBTOP TBVCLEAR VCOPY VDEFINE VDELETE VERASE VGET VIEW VPUT VREPLACE VRESET

Description Renames an ISPF library or partitioned data set member Replaces an ISPF library or partitioned data set member Statistics for partitioned data set are saved in variables Opens a data set Prints to the list data set Promotes a member or seq. data set to a controlled ISPF library Writes a record to a data set Queries the data set to obtain the requested information Renames an ISPF library Reviews the controls set for a library Write a record to the log data set Query a panel definition to extract information Query LIBDEF definition Removes a previously created pop-up window Starts ISPF dialog execution of panels, commands and/or programs Sets a message to be displayed on next panel A row is added to a table Moves the current row pointer (CRP) to last row of the table Closes a table and optionally saves a copy in a library Creates a new table and opens it Deletes a table row Display all or part of an ISPF table Closes a table without saving it Deletes a table from a table library Determines if a table key value (row) exists Obtain a table row Modify existing row or add new row Open a table residing in a table library Updates a table row Requests table information Sets the search argument for a following TBSCAN or TBDISPL Saves an opened table to a library without closing the table Scans for a table row matching TBSARG set or supplied list Moves the CRP either direction a specified number of rows Performs a sort of the table Obtains table statistics Places the CRP ahead of the first row of the table Clears all related table variables to null values Allows a program to copy a variable value Allows a program to access/define a variable Allows a program to remove variable definition/access from ISPF Removes variables from shared and/or profile pool(s) Obtains a variable value from shared or profile pool Allows you to view data as if in EDIT mode Updates variable values in shared or profile pool Allows a program to update variables in the shared/profile pool Allows a program to remove all its variable definitions at once

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.

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 PANEL TO PERFORMS DISPLAY A A DISPLAY OF A OF

PREDEFINED

COMBINATION

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.

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 LIBRARIES PERMITS BY THE THE USER DEFINITION FOR OF

APPLICATION

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.

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.

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.

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.

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.

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'

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.

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 .

REFERENCES 1. 2. 3. 4. 5. 6. TSO/E V2R5 REXX/MVS User's Guide TSO/E V2R5 REXX/MVS Reference MVS/QuickRef- Product- ISPF SERVICES MVS/QuickRef- Product- ISPF EDIT MACROS ISPF Edit and Edit Macros 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.