Page 1 z/OS TSO/E REXX User’s Guide SA22-7791-00...
Page 3 z/OS TSO/E REXX User’s Guide SA22-7791-00...
Page 4 Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address below. IBM welcomes your comments. A form for readers’ comments may be provided at the back of this publication, or you may address your comments to the following address:...
Page 6 Receiving Information from a Function ....83 Summary of Subroutines and Functions....83 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 7 Chapter 7. Manipulating Data ....85 Using Compound Variables and Stems ....85 What is a Compound Variable? .
Page 8 Appendix C. Comparisons Between CLIST and REXX ..197 Accessing System Information ....198 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 9 Controlling Program Flow ....199 Debugging ......200 Execution .
Page 10 V1R1.0 TSO/E REXX User’s Guide...
Page 12 V1R1.0 TSO/E REXX User’s Guide...
Page 14 V1R1.0 TSO/E REXX User’s Guide...
Page 15: About This Book
(called the language processor) and the REstructured eXtended eXecutor (REXX) language. Together, the language processor and the REXX language are known as TSO/E REXX. TSO/E REXX is the implementation of the Systems Application Architecture (SAA) Procedures Language on the MVS system.
Page 16: Purpose Of Each Chapter
Please see z/OS Information Roadmap for an overview of the documentation associated with z/OS, including the documentation available for z/OS TSO/E. Accessing Licensed Books on the Web z/OS licensed documentation in PDF format is available on the Internet at the IBM Resource Link Web site at: http://www.ibm.com/servers/resourcelink Licensed books are available only to customers with a z/OS license.
Page 17: Using Lookat To Look Up Message Explanations
LookAt can be accessed from the Internet or from a TSO command line. You can use LookAt on the Internet at: http://www.ibm.com/servers/eserver/zseries/zos/bkserv/lookat/lookat.html To use LookAt as a TSO command, LookAt must be installed on your host system. You can obtain the LookAt code for TSO from the LookAt Web site by clicking on News and Help or from the z/OS Collection, SK3T-4269 .
Page 18 V1R1.0 TSO/E REXX User’s Guide...
Page 19: Part 1. Learning The Rexx Language
That is, the TSO host command environment (ADDRESS TSO) is available to the exec. For more information about the TSO/E environment service and the different considerations for running REXX execs within the environment, see z/OS TSO/E Programming Services. © Copyright IBM Corp. 1988, 2001...
Page 20 V1R1.0 TSO/E REXX User’s Guide...
Page 21: Chapter 1. Introduction
There are few rules about REXX format. You need not start an instruction in a particular column, you can skip spaces in a line or skip entire lines, you can have an instruction span many lines or have multiple instructions on one line, variables © Copyright IBM Corp. 1988, 2001...
Page 22: Convenient Built-In Functions
Languages that are not interpreted must be compiled into machine language and possibly link-edited before they are run. You can use the IBM licensed product, IBM Compiler and Library for REXX/370, to provide this function.
Page 23: Benefits Of Using A Compiler
Offers some applications and application development tools written by IBM. Several combinations of IBM hardware and software have been selected as SAA environments. These are environments in which IBM will manage the availability of support for applicable SAA elements, and the conformance of those elements to SAA specifications.
Page 24: Protection For Source Code And Programs
SAA compliance. With this option in effect, a warning message is issued for each non-SAA item found in a program. For more information, see IBM Compiler and Library for REXX/370; Introducing the Next Step in REXX Programming.
Page 25: Chapter 2. Writing And Running A Rexx Exec
To create a PDS, allocate a data set with your prefix (usually your user ID) as the first qualifier, any name as the second qualifier, and preferably "exec" as the third qualifier. You can allocate the PDS with the Utilities option in ISPF/PDF or with the © Copyright IBM Corp. 1988, 2001...
Page 26: What Is A Rexx Exec
Note that this simple exec starts with a comment line to identify the program as a REXX exec. A comment begins with /* and ends with */. To prevent incompatibilities with CLISTs, IBM recommends that all REXX execs start with a comment that includes the characters “REXX” within the first line (line 1) of the exec.
Page 27: Syntax Of Rexx Instructions
What is a REXX Exec? When you type a number, for example 42, and press the Enter key, the variable number1 is assigned the value 42. You then see another sentence on the screen. Now enter a number to add to the first number. When you enter another number, for example 21, the variable number2 is assigned the value 21.
Page 28: The Format Of Rexx Instructions
Also note that the following two instructions are identical and yield the same result when displayed on the screen: SAY 'This is', 'a string.' is functionally identical to: SAY 'This is' 'a string.' These examples appear on the screen as: z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 29: Continuing A Literal String Without Adding A Space
Syntax of REXX Instructions This is a string. In the first example, the comma at the end of line 1 adds a space when the two lines are concatenated for display. In the second example, the space between the two separate strings is preserved when the line is displayed. Continuing a literal string without adding a space If you need to continue an instruction to a second or more lines but do not want REXX to add spaces when the line appears on the screen, use the concatenation...
Page 30: Types Of Rexx Instructions
A description of each type of instruction appears after the example. In most of the descriptions, you will see an edit line number (without the prefixed zeroes) to help you locate the instruction in the example. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 31: Keyword
Syntax of REXX Instructions EDIT ---- USERID.REXX.EXEC(TIMEGAME)------------------- COLUMNS 009 080 COMMAND ===> SCROLL ===> HALF ****** ************************ TOP OF DATA ************************************ 000001 /************************** REXX ****************************/ 000002 /* This is an interactive REXX exec that asks a user for the*/ 000003 /* time and then displays the time from the TIME command. 000004 /************************************************************/ 000005 Game1: 000006...
Page 32: Execs Using Double-Byte Character Set Names
A comment next to an individual instruction can clarify its purpose. Note: To prevent incompatibilities with CLISTs, IBM recommends that all REXX execs start with a comment that includes the characters “REXX” within the first line (line 1) of the exec. Failure to do so can lead to unexpected or unintended results in your REXX exec.
Page 33 Execs Using Double-Byte Character Set Names be checked as being valid DBCS strings. DBCS characters must be enclosed within shift-out (X'0E') and shift-in (X'0F') delimiters. In the following example, the shift-out (SO) and shift-in (SI) delimiters are represented by the less than symbol ( < ) and the greater than symbol ( >...
Page 34: Running An Exec
===> exec rexx.exec(timegame) exec ENTER SESSION MANAGER MODE ===> NO (YES or NO) v On the COMMAND line of any ISPF/PDF panel as long as the EXEC command is preceded by the word "tso". z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 35: Running An Exec Implicitly
Running an Exec ------------------------------ EDIT - ENTRY PANEL --------------------------- COMMAND ===> tso exec rexx.exec(timegame) exec ISPF LIBRARY: PROJECT ===> PREFIX GROUP ===> REXX ===> ===> ===> TYPE ===> EXEC MEMBER ===> TIMEGAME (Blank for member selection list) OTHER PARTITIONED OR SEQUENTIAL DATA SET: DATA SET NAME ===>...
Page 36: Exercises - Running The Example Execs
Now write an exec to allocate your PDS to SYSPROC or SYSEXEC using Checklist #3 on page 191 or Checklist #4 on page 192. Then run the example execs implicitly. Which way is easier? z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 37: Interpreting Error Messages
Interpreting Error Messages Interpreting Error Messages When you run an exec that contains an error, an error message often displays the line on which the error occurred and gives an explanation of the error. Error messages can result from syntax errors and from computational errors. For example, the following exec has a syntax error.
Page 38: Preventing Translation To Uppercase
SAY "Please type in the name of an animal." PULL animal /* Get the animal name.*/ SAY animal If you responded to the example with the word tyrannosaurus, you would see on your screen: z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 39: Passing Information To An Exec
Preventing Translation to Uppercase TYRANNOSAURUS To cause the language processor to read input exactly as it is presented, use the PARSE PULL instruction. PARSE PULL animal Then if you responded to the example with TyRannOsauRus, you would see on the screen: TyRannOsauRus Exercises - Running and Modifying the Example Execs Write and run the preceding Example of Reading and Re-displaying Input.
Page 40: Specifying Values When Invoking An Exec
Specifying Too Many Values When you specify more values than the number of variables following the PULL or ARG instruction, the last variable gets the remaining values. For example, you pass three numbers to "add". z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 41: Preventing Translation Of Input To Uppercase
Passing Information to an Exec EXEC rexx.exec(add) '42 21 10' exec The first variable following the ARG instruction, number1, is assigned the value 42. The second variable gets both '21 10'. In this situation, the exec ends with an error when it tries to add the two variables.
Page 42: Passing Arguments
In this case, the exec is invoked with an argument string consisting of ″,2″. For more information about functions and subroutines, see “Chapter 6. Writing Subroutines and Functions” on page 69. For more information about arguments, see “Parsing Multiple Strings as Arguments” on page 92. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 43: Chapter 3. Using Variables And Expressions
(Double-byte characters are valid only if you include OPTIONS ETMODE as the first instruction of your exec.) The following variable big represents the value one million or 1,000,000. © Copyright IBM Corp. 1988, 2001...
Page 44: Variable Names
The variable name should not be RC, SIGL, or RESULT, which are REXX special variables. More about special variables appears later in this book. Examples of acceptable variable names are: ANSWER ?98B Word3 number the_ultimate_value z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 45: Variable Values
Using Variables Also, if ETMODE is set on, the following are valid DBCS variable names, where < represents shift-out, and > represents shift-in, ‘.X’, ‘.Y’, and ‘.Z’ represent DBCS characters, and lowercase letters and numbers represent themselves. <.X.Y.Z> number_<.X.Y.Z> <.X.Y>1234<.Z> Variable Values The value of the variable, which is the value the variable name represents, might be categorized as follows:...
Page 46: Using Expressions
NUMERIC DIGITS instruction. For information about the NUMERIC DIGITS instruction, see z/OS TSO/E REXX Reference. Examples of whole numbers are: 123456789 0 91221 999 12.5 A decimal number includes a decimal point.
Page 47: Division
Using Expressions Using numeric constants and arithmetic operators, you can write arithmetic expressions as follows: 7 + 2 /* result is 9 7 - 2 /* result is 5 7 * 2 /* result is 14 7 ** 2 /* result is 49 7 ** 2.5 /* result is an error */ Division...
Page 48: Comparison Operators
Expressions that use comparison operators do not return a number value as do arithmetic expressions. Comparison expressions return either a true or false response in terms of 1 or 0 as follows: True False z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 49: The Strictly Equal And Equal Operators
Using Expressions Comparison operators can compare numbers or strings and ask questions, such as: Are the terms equal? (A = B) Is the first term greater than the second? (A > B) Is the first term less than the second? (A <...
Page 50: Logical (Boolean) Operators
Logical expressions, like comparison expressions, return a true (1) or false (0) value when processed. Logical operators combine two comparisons and return the true (1) or false (0) value depending on the results of the comparisons. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 51: Using Logical Expressions
Using Expressions The logical operators are: Operator Meaning & Returns 1 if both comparisons are true. For example: (4 > 2) & (a = a) /* true, so result is 1 */ (2 > 4) & (a = a) /* false, so result is 0 */ Inclusive OR Returns 1 if at least one comparison is true.
Page 52: Concatenation Operators
One way to format output is to use variables and concatenation operators as in the following example. A more sophisticated way to format information is with parsing and templates. Information about parsing appears in “Parsing Data” on page 87. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 53: Priority Of Operators
Using Expressions Example using Concatenation Operators /****************************** REXX *******************************/ /* This exec formats data into columns for output. /*******************************************************************/ sport = 'base' equipment = 'ball' column = ' cost = 5 SAY sport||equipment column '$' cost The result of this example is: baseball Priority of Operators When more than one type of operator appears in an expression, what operation...
Page 54: Exercises - Priority Of Operators
The & operator has priority, as follows, but the outcome is the same as the previous version with the parentheses. IF inexpensive | scholarship & reputable | nearby THEN \_________/ \_________/ \_______/ \____/ true false true false \___________/ false \_________________/ true \____________________/ true z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 55: Tracing Expressions With The Trace Instruction
Tracing Expressions with the TRACE Instruction Tracing Expressions with the TRACE Instruction You can use the TRACE instruction to display how the language processor evaluates each operation of an expression as it reads it, or to display the final result of an expression.
Page 56: Tracing Results
In addition to tracing operations and results, the TRACE instruction offers other types of tracing. For information about the other types of tracing with the TRACE instruction, see z/OS TSO/E REXX Reference. Exercises - Using the TRACE Instruction Write an exec with a complex expression, such as: IF (A >...
Page 57 Tracing Expressions with the TRACE Instruction 12 *-* IF (A > B) | (C < 2 * D) >V> "1" >V> "2" >O> "0" >V> "3" >L> "2" >V> "4" >O> "8" >O> "1" >O> "1" *-* THEN 13 *-* SAY 'At least one expression was true.' >L>...
Page 58 Tracing Expressions with the TRACE Instruction z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 59: Chapter 4. Controlling The Flow Within An Exec
Looping instructions, which tell the language processor to repeat a set of instructions. A loop can repeat a specified number of times or it can use a condition to control repeating. REXX looping instructions are: DO expression/END DO FOREVER/END DO WHILE expression=true/END DO UNTIL expression=true/END © Copyright IBM Corp. 1988, 2001...
Page 60: Using Conditional Instructions
IF expression THEN instruction; ELSE instruction Generally, at least one instruction should follow the THEN and ELSE clauses. When either clause has no instructions, it is good programming practice to include NOP (no operation) next to the clause. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 61: Nested If/Then/Else Instructions
Using Conditional Instructions IF expression THEN instruction ELSE NOP If you have more than one instruction for a condition, begin the set of instructions with a DO and end them with an END. IF weather = rainy THEN SAY 'Find a good book.' ELSE SAY 'Would you like to play tennis or golf?' PULL answer...
Page 62: Select/When/Otherwise/End Instruction
IF C = 3 THEN A = 1 ELSE A = 3 ELSE NOP SELECT/WHEN/OTHERWISE/END Instruction To select one of any number of choices, use the SELECT/WHEN/OTHERWISE/END instruction. In a flowchart it appears as follows: z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 63 Using Conditional Instructions SELECT THEN WHEN True instruction False THEN WHEN True instruction False THEN WHEN True instruction False OTHERWISE instruction(s) As a REXX instruction, the flowchart example looks like: SELECT WHEN expression THEN instruction WHEN expression THEN instruction WHEN expression THEN instruction OTHERWISE instruction(s) The language processor scans the WHEN clauses starting at the beginning until it...
Page 64: Exercises - Using The Select/When/Otherwise/End Instruction
1 to 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". ANSWER z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 65: Using Looping Instructions
Using Conditional Instructions Possible Solution /******************************** 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...
Page 66: Infinite Loops
SAY 'Number' count count = count - 1 The result is called an infinite loop because count alternates between 1 and 0 and an endless number of lines saying Number 1 appear on the screen. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 67: Do Forever Loops
EXEC1, unless you are running under ISPF. For more information about the HE condition, see z/OS TSO/E REXX Reference. Note: HE does not alter the halt condition, which is raised by HI. If you entered HI...
Page 68: Leave Instruction
Like LEAVE, ITERATE is used within the loop. DO count = 1 TO 10 IF count = 8 THEN z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 69: Exercises - Using Loops
Using Looping Instructions ITERATE ELSE SAY 'Number' count This example results in a list of numbers from 1 to 10 with the exception of number Number 1 Number 2 Number 3 Number 4 Number 5 Number 6 Number 7 Number 9 Number 10 Exercises - Using Loops 1.
Page 70: Conditional Loops
PULL dataset_name DO WHILE dataset_name \= 'QUIT' "PRINTDS DA("dataset_name")" SAY dataset_name 'printed.' SAY 'Enter the name of the next data set.' SAY 'When there are no more data sets, enter QUIT.' PULL dataset_name SAY 'Good-bye.' z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 71: Exercise - Using A Do While Loop
Using Looping Instructions Exercise - Using a DO WHILE Loop Write an exec with a DO WHILE loop that asks passengers on a commuter airline if they want a window seat and keeps track of their responses. The flight has 8 passengers and 4 window seats.
Page 72: Exercise - Using A Do Until Loop
/* Increase the number of passengers by 1 */ IF answer = 'Y' THEN window_seats = window_seats + 1 /* Increase the number of window seats by 1 */ ELSE NOP SAY window_seats 'window seats were assigned.' SAY passenger 'passengers were questioned.' z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 73: Combining Types Of Loops
Using Looping Instructions Combining Types of Loops You can combine repetitive and conditional loops to create a compound loop. 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 <...
Page 74: Using Interrupt Instructions
Outer 3 Inner 1 Using Interrupt Instructions Instructions that interrupt the flow of an exec can cause the exec to: v Terminate (EXIT) v Skip to another part of the exec marked by a label (SIGNAL) z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 75: Exit Instruction
Using Interrupt Instructions v Go temporarily to a subroutine either within the exec or outside the exec (CALL/RETURN). EXIT Instruction The EXIT instruction causes an exec to unconditionally end and return to where the exec was invoked. If the exec was initiated from the PROC section of an ISPF selection panel, EXIT returns to the ISPF panel.
Page 76: Signal Instruction
In the following example, if the expression is true, then the language processor goes to the label Emergency: and skips all instructions in between. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 77 Using Interrupt Instructions IF expression THEN SIGNAL Emergency ELSE instruction(s) Emergency: instruction(s) SIGNAL is useful for testing execs or to provide an emergency course of action. It should not be used as a convenient way to move from one place in an exec to another.
Page 78 V1R1.0 TSO/E REXX User’s Guide...
Page 79: Chapter 5. Using Functions
A function call can contain up to 20 arguments separated by commas. Each argument can be one or more of the following. v Blank function( ) v Constant function(55) v Symbol function(symbol_name) v Literal string function('With a literal string') v Option recognized by the function © Copyright IBM Corp. 1988, 2001...
Page 80: Example Of A Function
The function is called MAX and is used as follows: MAX(number1,number2,number3,...) To find the maximum of 45, -2, number, 199, and put the maximum into the symbol biggest, write the following instruction: biggest = MAX(45,-2,number,199) z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 81: Built-In Functions
Miscellaneous functions These functions do not clearly fit into any of the other categories. The following tables briefly describe the functions in each category. For a complete description of these functions, see z/OS TSO/E REXX Reference. Arithmetic Functions Function Description Returns the absolute value of the input number.
Page 82: Conversion Functions
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. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 83: Miscellaneous Functions
Built-In Functions Function Description 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.
Page 84: Testing Input With Built-In Functions
Exercise - Writing an Exec with Built-In Functions Write an exec that checks a data set member name for a length of 8 characters. If a member name is longer than 8 characters, the exec truncates it to 8 and sends z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 85 Built-In Functions the user a message indicating the shortened name. Use the LENGTH and the SUBSTR built-in functions as described in z/OS TSO/E REXX Reference. ANSWER Possible Solution /**************************** REXX *********************************/ /* This exec tests the length of a name for a data set member. If */...
Page 86 Built-In Functions z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 87: Chapter 6. Writing Subroutines And Functions
There can be no space between the function name and the parentheses. The function call is part of an instruction, for example, an assignment instruction. x = function(argument1, argument2,...) v Returning a value from a subroutine © Copyright IBM Corp. 1988, 2001...
Page 88: When To Write Subroutines Vs. Functions
When the subroutine ends, it can return control to the instruction that directly follows the subroutine call. The instruction that returns control is the RETURN instruction. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 89 Writing a Subroutine; instruction(s) CALL sub1 instruction(s) EXIT sub1: instruction(s) RETURN Subroutines may be internal and designated by a label, or external and designated by the data set member name that contains the subroutine. The preceding example illustrates an internal subroutine named "sub1". IMPORTANT NOTE Because internal subroutines generally appear after the main part of the exec, when you have an internal subroutine, it is important to end the main part of...
Page 90: Passing Information To A Subroutine
"i", for their DO loops. As a result, the DO loop repeats only once in the main exec because the subroutine returns to the main exec with i = 6. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 91 Writing a Subroutine; Example of a Problem Caused by Passing Information in a Variable /******************************* REXX ******************************/ /* NOTE: This exec contains an error. /* It uses a DO loop to call an internal subroutine and the /* subroutine also uses a DO loop with same control variable as /* the main exec.
Page 92: Passing Information By Using Arguments
PROCEDURE EXPOSE number1 number1 = 7 number2 = 5 RETURN For more information about the PROCEDURE instruction, see z/OS TSO/E REXX Reference. Passing Information by Using Arguments A way to pass information to either internal or external subroutines is through arguments.
Page 93: Receiving Information From A Subroutine
= ARG(2) /* puts the second argument into width */ More information about the ARG function appears in z/OS TSO/E REXX Reference. Receiving Information from a Subroutine Although a subroutine can receive up to 20 arguments, it can specify only one expression on the RETURN instruction.
Page 94: Example - Writing An Internal And An External Subroutine
= user + 1 /* increase the user score SAY 'Computer score = ' computer Your score = ' user SAY 'Heads, tails, or quit?' PULL response CALL check /* call internal subroutine, check */ EXIT z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 95: Writing A Function
Writing a Subroutine; Possible Solution (Internal Subroutine named CHECK) check: /*******************************************************************/ /* This internal subroutine checks for valid input of "HEADS", /* "TAILS", or "QUIT". If the user entered anything else, the /* subroutine tells the user that it is an invalid response and /* asks the user to try again.
Page 96 Because internal functions generally appear after the main part of the exec, when you have an internal function, it is important to end the main part of the exec with the EXIT instruction. The following illustrates an external function named "func2". z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 97: Passing Information To A Function
Writing a Function REXX.EXEC(MAIN) instruction(s) x=func2(arg1) instruction(s) exit REXX.EXEC(FUNC2) ARG var1 instruction(s) RETURN value To determine whether to make a function internal or external, you might consider factors, such as: v Size of the function. Very large functions often are external, whereas small functions fit easily within the calling exec.
Page 98 You can also use the PROCEDURE EXPOSE instruction to protect all but a few specified variables. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 99: Passing Information By Using Arguments
PROCEDURE EXPOSE number1 number1 = 7 number2 = 5 RETURN number2 For more information about the PROCEDURE instruction, see z/OS TSO/E REXX Reference. Passing Information by Using Arguments A way to pass information to either internal or external functions is through arguments.
Page 100 = ARG(1) /* puts the first argument into length */ width = ARG(2) /* puts the second argument into width */ More information about the ARG function appears in z/OS TSO/E REXX Reference. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 101: Receiving Information From A Function
The function is called as follows: AVG(number1 number2 number3 ...) Use the WORDS and WORD built-in functions. For more information about these built-in functions, see z/OS TSO/E REXX Reference. ANSWER Possible Solution...
Page 102 Might return a value to the caller. Must return a value to the caller. Returns a value by placing it into the REXX special Returns a value by replacing the function call with the variable RESULT. value. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 103: Chapter 7. Manipulating Data
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. © Copyright IBM Corp. 1988, 2001...
Page 104: Using Stems
= 3 SAY employee.name /* Displays 'Devon, David' */ For more information about compound variables, see z/OS TSO/E REXX Reference. Using Stems When working with compound variables, it is often useful to initialize an entire collection of variables to the same value.
Page 105: Parsing Data
Using Compound Variables and Stems with the OUTTRAP external function when trapping command output. For information about OUTTRAP, see “Using the OUTTRAP Function” on page 123. Exercises - Using Compound Variables and Stems 1. After these assignment instructions, what is displayed in the following SAY instructions? a = 3 /* assigns '3' to variable 'A' */...
Page 106: Instructions That Parse
/* word1 contains 'Knowledge' */ /* word2 contains 'is' /* word3 contains 'power.' PARSE UPPER ARG causes the same result as ARG in that it changes character information to uppercase before assigning it to one or more variables. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 107: Ways Of Parsing
/* word1 contains 'KNOWLEDGE' */ /* word2 contains 'IS' /* word3 contains 'POWER.' For more information about parsing instructions, see z/OS TSO/E REXX Reference. PARSE VALUE ... WITH Instruction The PARSE VALUE ... WITH instruction parses a specified expression, such as a literal string, into one or more variable names that follow the WITH subkeyword.
Page 108: String
This example could have also been coded as follows. Note the explicit use of the column 1 indicator prior to part1 that was implied in the previous example and the use of the =5 part2 to indicate the absolute position, column 5. quote = 'Ignorance is bliss.' ..+..1..+..2 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 109 Parsing Data PARSE VAR quote 1 part1 =5 part2 /* part1 contains 'Igno' /* part2 contains 'rance is bliss.' */ When a template has more than one number, and a number at the end of the template is lower than an earlier number, parse loops back to the beginning of the data.
Page 110: Parsing Multiple Strings As Arguments
/* word3 contains '' /* string2 contains 'String Two' /* string3 contains 'String Three' */ For more information about passing multiple arguments, see z/OS TSO/E REXX Reference. Exercise - Practice with Parsing What are the results of the following parsing examples?
Page 111 Parsing Data quote = 'Experience is the best teacher.' PARSE VAR quote word1 word2 word3 a) word1 = b) word2 = c) word3 = quote = 'Experience is the best teacher.' PARSE VAR quote word1 word2 word3 word4 word5 word6 a) word1 = b) word2 = c) word3 =...
Page 112 = ’ the best teacher.’ a) v1 = ’Experi’ b) v2 = ’ence i’ c) v3 = ’s the best teacher.’ a) word1 = Knowledge b) word2 = Ignorance c) word3 = Experience z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 113: Part 2. Using Rexx
If you run a REXX exec in the TSO/E environment you created, the exec can contain TSO/E commands, external functions, and services that an exec running in a TSO/E address space can use. That is, the TSO host command environment (ADDRESS © Copyright IBM Corp. 1988, 2001...
Page 114 TSO) is available to the exec with some limitations. For more information about the TSO/E environment service, limitations on the environment it creates, and the different considerations for running REXX execs within the environment, see z/OS TSO/E Programming Services. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 115: Chapter 8. Entering Commands From An Exec
A REXX exec can issue many types of commands. The two main categories of commands are: v 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: –...
Page 116: Issuing Tso/E Commands From An Exec
Ways to specify the data set name are controlled by the TSO/E naming conventions, which define fully-qualified and non fully-qualified data sets. A fully-qualified data set name specifies all three qualifiers including the prefix and must appear within a set of quotation marks. 'userid.myrexx.exec' z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 117: Using Variables In Commands
Issuing TSO/E Commands from an Exec A non fully-qualified data set name can eliminate the prefix and is not enclosed within quotation marks. myrexx.exec If you use the EXEC command to explicitly invoke an exec, the EXEC command processor requires a set of single quotation marks around the argument. When passing a non fully-qualified data set name as an argument, you need not add additional quotation marks.
Page 118: Causing Interactive Commands To Prompt The User
RETURN or EXIT instruction. Unlike an external routine, which passes a value to the special variable RESULT, the invoked exec passes a value to the REXX special variable RC. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 119: Issuing Other Types Of Commands From An Exec
Issuing TSO/E Commands from an Exec Invoking Another Exec with the EXEC Command To explicitly invoke another exec from within an exec, issue the EXEC command as you would any other TSO/E command. The called exec should end with a RETURN or EXIT instruction, ensuring that control returns to the caller.
Page 120 When a REXX exec runs on a host system, there is at least one default environment available for executing commands. The default host command environments available in TSO/E REXX are as follows: TSO - the environment in which TSO/E commands and TSO/E REXX commands execute in the TSO/E address space.
Page 121 Issuing Other Types of Commands from an Exec v CPICOMM v LU62 v APPCMVS From TSO/E READY mode, TSO/E REXX provides the following host command environments: v TSO (the initial host command environment) v MVS v LINK v LINKMVS v LINKPGM...
Page 122: Appc/Mvs Host Command Environments
CMCFM (Confirm) v CMCFMD (Confirmed) v CMDEAL (Deallocate) v CMECS (Extract_Conversation_State) v CMECT (Extract_Conversation_Type) v CMEMN (Extract_Mode_Name) v CMEPLN (Extract_Partner_LU_Name) v CMESL (Extract_Sync_Level) v CMFLUS (Flush) v CMINIT (Initialize_Conversation) v CMPTR (Prepare_To_Receive) v CMRCV (Receive) z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 123 Issuing Other Types of Commands from an Exec v CMRTS (Request_To_Send) v CMSCT (Set_Conversation_Type) v CMSDT (Set_Deallocate_Type) v CMSED (Set_Error_Direction) v CMSEND (Send_Data) v CMSERR (Send_Error) v CMSF (Set_Fill) v CMSLD (Set_Log_Data) v CMSMN (Set_Mode_Name) v CMSPLN (Set_Partner_LU_Name) v CMSPTR (Set_Prepare_To_Receive_Type) v CMSRC (Set_Return_Control) v CMSRT (Set_Receive_Type) v CMSSL (Set_Sync_Level)
Page 124: Changing The Host Command Environment
ADDRESS instruction followed by the name of an environment. The ADDRESS instruction has two forms: one affects all commands issued after the instruction, and one affects only a single command. v All commands z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 125: Determining The Active Host Command Environment
Checking if a Host Command Environment is Available To check if a host command environment is available before trying to issue commands to that environment, issue the TSO/E REXX SUBCOM command followed by the name of the host command environment, such as ISPEXEC.
Page 126 /* Call an internal subroutine */ IF RC = 0 THEN "display PANEL(newtool)" ELSE "setmsg MSG(nt001)" /* Send an error message. */ EXIT blankem: 'vget (ZUSER)' ntgroup = ' nttype = ' ntmem = ' RETURN RC z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 127 Issuing Other Types of Commands from an Exec ADDRESS Example 3 /****************************** REXX *******************************/ /* This exec must be run in ISPF. It displays panel named newtool */ /* and gets the name of a data set from input fields named ntproj, */ /* ntgroup, nttype, and ntmem.
Page 128 Issuing Other Types of Commands from an Exec z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 129: Chapter 9. Diagnosing Problems Within An Exec
When an exec without "trace c" issues an incorrect TSO/E command, the exec ends with a TSO/E error message. For example, a LISTDS command specifies an incorrect data set name. "LISTDS ?" This example results in the following error message. © Copyright IBM Corp. 1988, 2001...
Page 130: Using Rexx Special Variables Rc And Sigl
INVALID KEYWORD, ? 3 *-* "LISTDS ?" +++ RC(12) +++ For more information about the TRACE instruction, see z/OS TSO/E REXX Reference. Using REXX Special Variables RC and SIGL As mentioned earlier, the REXX language has three special variables — RC, SIGL, and RESULT.
Page 131: Tracing With The Interactive Debug Facility
000015 /* Displays: 000016 The return code from the command on line 5 is 12 For more information about the SIGNAL instruction, see z/OS TSO/E REXX Reference. Tracing with the Interactive Debug Facility The interactive debug facility permits a user to interactively control the execution of an exec.
Page 132: Starting Interactive Tracing
0 message and 20 data records sent as 24 records to NODE1.MEL Transmission occurred on 05/20/1989 at 14:40:11. 10 *-* IF RC = 0 >>> "1" *-* THEN 11 *-* SAY 'Transmit successful.' >>> "Transmit successful." Transmit successful. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 133 Debugging Execs EXECUTIL TS Command: Another way to start interactive tracing is to issue the EXECUTIL TS (trace start) command or cause an attention interrupt and type TS. The type of interactive tracing begun is equivalent to that of the TRACE ?R instruction, except that tracing continues through all routines invoked unless it is specifically ended.
Page 134: Options Within Interactive Trace
You can end interactive tracing in one of the following ways: v Use the TRACE OFF instruction. v Let the exec run until it ends. v Use the TRACE ? instruction. v Issue the EXECUTIL TE command. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 135 EXECUTIL TE: The EXECUTIL TE (Trace End) command ends interactive tracing when issued from within an exec or when entered during a pause while interactively tracing an exec. For more information about the EXECUTIL command, see z/OS TSO/E REXX Reference. Chapter 9. Diagnosing Problems Within an Exec...
Page 136 Debugging Execs z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 137: Chapter 10. Using Tso/E External Functions
SETLANG - retrieves and optionally changes the language in which REXX messages are displayed. The function returns the previous language setting. v STORAGE - retrieves and optionally changes the value in a storage address. © Copyright IBM Corp. 1988, 2001...
Page 138: Using The Getmsg Function
The message text and associated information are stored in variables, which can be displayed or used within the REXX exec. The function call is replaced by a function code that indicates whether the call was successful. See z/OS TSO/E REXX Reference for more information about the syntax, function codes, and variables for GETMSG.
Page 139 TSO/E External Functions x = LISTDSI('my.data') /* x is set to a function code */ x = LISTDSI(my.data) /* x is set to a function code */ When you specify a variable that was previously set to a data set name, do not enclose the variable in quotation marks.
Page 140: Using The Msg Function
To resume the display of TSO/E messages, substitute the word "ON" for "OFF". To find out if messages will be displayed, issue the MSG function followed by empty parentheses. status = MSG() /* status is set to ON or OFF */ z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 141: Using The Mvsvar Function
TSO/E External Functions Using the MVSVAR Function The MVSVAR function retrieves information about MVS, TSO/E, and the current session, such as the symbolic name of the MVS system, or the security label of the TSO/E session. The information retrieved depends on the argument specified. To retrieve the information, use the MVSVAR function immediately followed by an argument value enclosed in parentheses.
Page 142: Using The Prompt Function
The OUTTRAP function does not trap all lines of command output from all TSO/E commands. For more information, see z/OS TSO/E REXX Reference. Using the PROMPT Function When your profile allows for prompting, the PROMPT function can set the prompting option on or off for interactive TSO/E commands, or it can return the type of prompting previously set.
Page 143: Using The Setlang Function
TSO/E External Functions x = PROMPT() /* x is set to ON or OFF */ The PROMPT function overrides the NOPROMPT operand of the EXEC command, but it cannot override a NOPROMPT operand in your TSO/E profile. To display your profile, issue the PROFILE command.
Page 144: Using The Storage Function
SYSDSN function returns one of the following messages: v MEMBER SPECIFIED, BUT DATASET IS NOT PARTITIONED v MEMBER NOT FOUND v DATASET NOT FOUND v ERROR PROCESSING REQUESTED DATASET v PROTECTED DATASET v VOLUME NOT ON SYSTEM v UNAVAILABLE DATASET z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 145: Using The Sysvar Function
TSO/E External Functions v INVALID DATASET NAME, data-set-name: v MISSING DATASET NAME After a data set is available for use, you may find it useful to get more detailed information. For example, if you later need to invoke a service that requires a specific data set organization, then use the LISTDSI function.
Page 146: User Information
Invocation could be implicit or explicit. SYSPCMD Name of most recently executed command SYSSCMD Name of most recently executed subcommand System Information Argument Value Description SYSCPU Number of CPU seconds used during session in the form: seconds.hundredths of seconds z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 147: Console Session Information
TSO/E External Functions Argument Value Description SYSHSM Level of Data Facility Hierarchical Storage Manager (DFHSM) installed SYSJES Name and level of JES installed SYSLRACF Level of RACF installed SYSRACF Whether RACF is available SYSNODE Network node name of the installation’s JES SYSSRV Number of system resource manager (SRM) service units used during session...
Page 148: Additional Examples
/* Allocate the new data set. IF RC = 0 THEN /* If return code from allocate is 0 */ SAY 'Data set' newds 'was allocated.' ELSE SAY 'Data set' newds 'was not allocated. Return code was' RC z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 149 Additional Examples Example 2 Part 1 - Using the OUTTRAP Function /**************************** REXX *********************************/ /* This exec adds a data set to the front of the data sets in the */ /* SYSPROC concatenation. It first asks for the name of the data */ /* set to add, then it finds all data sets currently allocated to */ /* SYSPROC, adds the new data set to the beginning and re-allocates*/ /* the concatenation to SYSPROC.
Page 150 = i + 3 IF SUBSTR(name.i,1,3) = ' ' THEN i = i - 1 concat = concat",'"name.i"'" ELSE i = name.0 ELSE NOP /* Allocate the new concatenation to SYSPROC */ "ALLOC F(sysproc) DA('"addname"',"concat") SHR REUSE" z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 151: Function Packages
Additional Examples Example 3 - Using the OUTTRAP Function /******************************* REXX ******************************/ /* This exec lists datasets allocated to a ddname that is passed /* as an argument when the exec is invoked. It uses the OUTTRAP /* function to trap output from the LISTA STATUS command. It then */ /* loops through the output looking for a match to the input ddname*/ /* When match is found, the exec will SAY the name of all datasets */ /* allocated to that ddname.
Page 152: Search Order For Functions
IRXFLOC. Other function packages can be named in a parameter block set up by a system programmer. For more information about function packages, see z/OS TSO/E REXX Reference. Search Order for Functions When the language processor encounters a function call, if defaults have not been changed, it goes through the following search order: v Internal functions —...
Page 153: Chapter 11. Storing Information In The Data Stack
Because elements are placed on the bottom of a queue and removed from the top, the oldest elements on a queue are the ones processed first. The technique is called FIFO (first in first out). © Copyright IBM Corp. 1988, 2001...
Page 154: Manipulating The Data Stack
= 'String A for the data stack' QUEUE elemA If the two preceding sets of instructions were in an exec, the data stack would appear as follows: z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 155: Removing Elements From The Stack
Manipulating the Data Stack Note: Some people find it less confusing when adding elements in a particular order to the data stack, to consistently use the same instruction, either PUSH or QUEUE, but not both. Removing Elements from the Stack To remove information from the data stack, use the PULL and PARSE PULL instructions, the same instructions used previously in this book to extract information from the terminal.
Page 156: Exercise - Using The Data Stack
QUEUE 'S' /* Data in stack is: QUEUE 'O' (first queue) T */ QUEUE 'E' (second queue) S */ (third queue) O */ DO QUEUED() (fourth queue) E */ PULL stackitem /***************************/ SAY stackitem z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 157: Processing Of The Data Stack
You can think of a data stack as a temporary holding place for information. Every TSO/E REXX user has a separate data stack available for each REXX environment that is initialized. REXX environments are initialized at the READY prompt, when you enter ISPF, and again when you split the screen in ISPF.
Page 158: Using The Data Stack
You can use the data stack to pass information from an exec to an external routine without using arguments. The exec pushes or queues the information on the stack and the routine pulls it off and uses it as in the following example. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 159 Using the Data Stack Example of Using the Data Stack to Pass Information /***************************** REXX ********************************/ /* This exec helps an inexperienced user allocate a new PDS. It /* prompts the user for the data set name and approximate size, /* and queues that information on the data stack.
Page 160: Passing Information To Interactive Commands
To help prevent this, TSO/E provides the MAKEBUF command that creates a buffer, which you can think of as an extension to the stack, and the DROPBUF command that deletes the buffer and all elements within it. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 161: Creating A Buffer With The Makebuf Command
To create a buffer on the data stack before adding more elements to the stack, use the TSO/E REXX MAKEBUF command. All elements added to the data stack after the MAKEBUF command are placed in the buffer. Below the buffer are elements placed on the stack before the MAKEBUF command.
Page 162: Dropping A Buffer With The Dropbuf Command
Finding the Number of Buffers with the QBUF Command To find out how many buffers were created with the MAKEBUF command, use the TSO/E REXX QBUF command. QBUF returns in the REXX special variable RC, the number of buffers created.
Page 163: Finding The Number Of Elements In A Buffer
Finding the Number of Elements In a Buffer To find out how many elements are in the most recently created buffer, use the TSO/E REXX QELEM command. QELEM returns in the REXX special variable RC, the number of elements in the most recently created buffer.
Page 164 What is returned to the function? SAY QUEUED() b. What is RC? 'QBUF' SAY RC c. What is RC? 'QELEM' SAY RC d. What are both RCs and the result of the QUEUED() function? z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 165: Protecting Elements In The Data Stack
Creating a Buffer on the Data Stack 'DROPBUF 2' 'QBUF' SAY RC 'QELEM' SAY RC SAY QUEUED() ANSWERS B (b was changed to uppercase because it was queued without quotes and pulled without PARSE.) 1, 1, 1 Protecting Elements in the Data Stack In certain environments, particularly MVS, where multiple tasks run at the same time, it is often important for an exec to isolate stack elements from other execs.
Page 166: Creating A New Data Stack With The Newstack Command
TSO/E REXX NEWSTACK command. Read the next section to see how the exec in the previous example can safely issue an interactive TSO/E command. To delete the new data stack and all elements in it, use the TSO/E REXX DELSTACK command. Execs can create multiple stacks before deleting them.
Page 167: Deleting A Private Stack With The Delstack Command
Finding the Number of Stacks To find out how many stacks exist, use the TSO/E REXX QSTACK command. QSTACK returns in the REXX special variable RC, the total number of stacks including the original data stack.
Page 168: Additional Examples
/* a blank screen and PULL waits for terminal /* input. To end the wait, press ENTER. 'DELSTACK' /* Remove the new stack and return to original stack.*/ PULL anyitem SAY anyitem /* Displays ATTENTION PLEASE! THIS IS A TEST. */ z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 169 Protecting Elements in the Data Stack Data Stack Example 2 /******************************** REXX *****************************/ /* This exec runs another exec implicitly and then sends a message */ /* when the called exec finishes. It receives as an argument the */ /* name of a PDS member to run. It activates the system procedure */ /* file SYSEXEC, allocates the data set to SYSEXEC, pushes some /* commands on the data stack and then implicitly executes the exec*/ /*******************************************************************/...
Page 170 Protecting Elements in the Data Stack z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 171: Chapter 12. Processing Data And Input/Output Processing
REXX instruction. v Processing information to and from data sets The TSO/E REXX EXECIO command in an exec reads information from a data set to the data stack (or a list of variables) and writes information from the data stack (or list of variables) back to a data set.
Page 172: Using Execio To Process Information To And From Data Sets
One Data Set to Another” on page 159. If you use EXECIO to read information from a data set and to the data stack, the information can be stored in FIFO or LIFO order on the data stack. FIFO is the z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 173: Reading Information From A Data Set
Using EXECIO to Process Information ... default. If you use EXECIO to read information from a data set and to a list of variables, the first data set line is stored in variable1, the second data set line is stored in variable2, and so on. Data read into a list of variables can be accessed randomly.
Page 174 1, newvar.2 contains record 2, and so forth up to newvar.10 which contains record 10. All stem variables beyond newvar.10 (for example, variables newvar.11 and newvar.12) are residual and contain the value(s) held prior to entering the EXECIO command. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 175: Writing Information To A Data Set
The rest of this topic describes the types of information you can specify with EXECIO DISKW. For further information, see z/OS TSO/E REXX Reference. How to specify the number of lines to write: To open a data set without writing records to it, put a zero immediately following the EXECIO command and specify the OPEN operand.
Page 176 The EXECIO command can also specify the number of lines to write from a list of compound variables. "EXECIO 5 DISKW myoutdd (STEM newvar." In this example, the EXECIO command writes 5 items from the newvar variables including uninitialized compound variables, if any. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 177: Return Codes From Execio
Using EXECIO to Process Information ... See EXECIO Example 6 under the heading Figure 7 on page 168, which shows the usage of the EXECIO command with stem variables. Return Codes from EXECIO After an EXECIO command runs, it sets the REXX special variable "RC" to a return code.
Page 178 MYINDD and MYOUTDD respectively, you could write the following instructions. Note the "MOD" attribute on the second allocation, which appends the 5 lines at the end of the data set rather than on top of existing data. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 179: Copying Information To And From A List Of Compound Variables
Using EXECIO to Process Information ... Appending 5 Lines of Data to an Existing Data Set "ALLOC DA(weekly.input(mar28)) F(myindd) SHR REUSE" "ALLOC DA(yearly.output) F(myoutdd) MOD" "EXECIO 5 DISKR myindd (FINIS" "EXECIO 5 DISKW myoutdd (FINIS" Note: Do not use the MOD attribute when allocating a member of a PDS to which you want to append information.
Page 180: Updating Information In A Data Set
Updating multiple lines: To update multiple lines, you can issue more than one EXECIO command to the same data set. For example, to update Mary Leone’s user ID in addition to Amy Crandall’s phone extension, write the following instructions. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 181: Additional Examples
Using EXECIO to Process Information ... Updating Multiple Specific Lines in a Data Set "ALLOC DA('dept5.employee.list') F(updatedd) OLD" "EXECIO 1 DISKRU updatedd 2 (LIFO" PULL line PUSH 'Crandall, Amy 5500' "EXECIO 1 DISKW updatedd" "EXECIO 1 DISKRU updatedd 5 (LIFO" PULL line PUSH 'Leone, Mary MARYL...
Page 182: Execio Example 1
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 Figure 2. EXECIO Example 2 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 183: Execio Example 3
Using EXECIO to Process Information ... EXECIO Example 3 /**************************** 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.
Page 184 END "EXECIO 0 DISKR indd (FINIS" /* Close the input file, indd IF out_ctr > 0 THEN /* Were any lines written to outdd?*/ /* Yes. So outdd is now open Figure 5. EXECIO Example 5 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 185: Execio Example 5
Using EXECIO to Process Information ... EXECIO Example 5 (continued) /****************************************************************/ /* Since the outdd file is already open at this point, the /* following "EXECIO 0 DISKW ..." command will close the file, */ /* but will not empty it of the lines that have already been /* written.
Page 186 DO i = 1 TO newvar.0 /* Loop through all records SAY newvar.i /* Display the ith record "EXECIO" newvar.0 "DISKW myoutdd (STEM newvar." /* Write exactly the number of records read Figure 7. EXECIO Example 6 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 187: Execio Example 6 (Continued)
Using EXECIO to Process Information ... EXECIO Example 6 (continued) IF rc = 0 THEN /* If write was successful SAY newvar.0 "records were written to 'all.sample.data'" ELSE exec_RC = RC /* Save exec return code SAY "Error during 1st EXECIO ... DISKW, return code is " RC ELSE exec_RC = RC /* Save exec return code...
Page 188: Execio Example 6
SAY "Error during 2nd EXECIO ... DISKR, return code is " RC "EXECIO 0 DISKW myoutdd (FINIS" /* Close output file "FREE FI(myindd1)" "FREE FI(myindd2)" "FREE FI(myoutdd)" EXIT 0 Figure 9. EXECIO Example 6 (continued) z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 189: Chapter 13. Using Rexx In Tso/E And Other Mvs Address Spaces
Space REXX language instructions — These instructions are used throughout this book. For a description of each one, see z/OS TSO/E REXX Reference. Built-in functions — A brief description of each built-in function appears in “Built-In Functions” on page 63. A longer description appears in z/OS TSO/E REXX Reference.
Page 190 MSG — controls the display of messages for TSO/E commands v MVSVAR — returns information about MVS, TSO/E and the current session v OUTTRAP — traps lines of TSO/E command output v PROMPT — controls prompting for TSO/E interactive commands z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 191: Running Execs In A Tso/E Address Space
Services Available to REXX Execs Service Non-TSO/E TSO/E Address Address Space Space v SETLANG — controls the language in which REXX messages are displayed v STORAGE — retrieves and optionally changes the value in a storage address v SYSCPUS — returns information about CPUs that are online v SYSDSN —...
Page 192: Things To Consider When Allocating To A System File (Sysproc Or Sysexec)
For general information about ALTLIB, see “Appendix B. Specifying Alternate Libraries with the ALTLIB Command” on page 195. For more information about the EXECUTIL and ALTLIB commands, see z/OS TSO/E Command Reference. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 193: Running An Exec From A Clist
Running Execs in a TSO/E Address Space Running an Exec from a CLIST A CLIST can invoke an exec with the EXEC command explicitly or implicitly. If it invokes an exec implicitly, the exec must be in a PDS allocated to SYSEXEC or SYSPROC.
Page 194: Running An Exec In The Background
Background processing does not interfere with a person’s use of the terminal. You can run time-consuming and low priority execs in the background, or execs that do not require terminal interaction. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 195: Running Execs In A Non-Tso/E Address Space
(IRXEXEC or IRXJCL). If you use IRXEXEC, you must specify parameters that define the exec to be run and supply other related information. For more information, see z/OS TSO/E REXX Reference. Chapter 13. Using REXX in TSO/E and Other MVS Address Spaces...
Page 196: Using Irxjcl To Run An Exec In Mvs Batch
PARM='JCLTEST Test IRXJCL' //* Name of exec <-----> | //* Argument <---------> //OUTDD DSN=USERID.TRACE.OUTPUT,DISP=MOD //SYSTSPRT DD DSN=USERID.IRXJCL.OUTPUT,DISP=OLD //SYSEXEC DD DSN=USERID.MYREXX.EXEC,DISP=SHR //SYSTSIN DD First line of data Second line of data Third line of data z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 197 Running Execs in a Non-TSO/E Address Space USERID.MYREXX.EXEC(JCLTEST) /****************************** REXX ******************************/ /* This exec receives input from its invocation in JCL.EXEC, pulls*/ /* data from the input stream and sends back a condition code of */ /* 137. /******************************************************************/ TRACE error SAY 'Running exec JCLTEST' ADDRESS MVS PARSE ARG input...
Page 198: Using The Data Stack In Tso/E Background And Mvs Batch
CLISTs. for the exec that is running. Output sent to a specified output data set or to a Output sent to a specified output data set or to a SYSOUT class. SYSOUT class. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 199: Requirements
Summary of TSO/E Background and MVS Batch TSO/E BACKGROUND (IKJEFT01) MVS BATCH (IRXJCL) Messages are displayed in the output file. Messages may appear in two places; the JCL output listing and in the output file. To suppress messages in the output file, use the TRACE OFF instruction.
Page 200: Customizing A Language Processor Environment
Change the values in the three default parameters modules, IRXTSPRM, IRXISPRM, and IRXPARMS. v Call an initialization routine IRXINIT and specifying parameters to change default parameters. For more information about customizing a language processor environment, see z/OS TSO/E REXX Reference. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 202 V1R1.0 TSO/E REXX User’s Guide...
Page 203: Appendix A. Allocating Data Sets
Checklists for allocating a data set to SYSEXEC and SYSPROC appear in: – “Checklist #3: Writing an Exec that Sets up Allocation to SYSEXEC” on page 191 – “Checklist #4: Writing an Exec that Sets up Allocation to SYSPROC” on page 192 © Copyright IBM Corp. 1988, 2001...
Page 204: Where To Begin
(DDNAME)). 2. Write down the names of the data sets at your installation that are allocated to SYSEXEC. First data set: ______________________________________________ Remaining data sets: ______________________________________________ ______________________________________________ z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 205: Checklist #1: Creating And Editing A Data Set Using Ispf/Pdf
Preliminary Checklist ______________________________________________ ______________________________________________ 3. Write down the names of the data sets at your installation that are allocated to SYSPROC. First data set: ______________________________________________ Remaining data sets: ______________________________________________ ______________________________________________ ______________________________________________ ______________________________________________ 4. Issue the LISTDS command for the first data set in each system file to display the record format, logical record length, and block size.
Page 206 - Enter TSO command or CLIST 7 DIALOG TEST - Perform dialog testing 8 LM UTILITIES- Perform library administrator utility functions 9 IBM PRODUCTS- Additional IBM program development products C CHANGES - Display summary of changes for this release T TUTORIAL...
Page 207 - Enter TSO command or CLIST 7 DIALOG TEST - Perform dialog testing 8 LM UTILITIES- Perform library administrator utility functions 9 IBM PRODUCTS- Additional IBM program development products C CHANGES - Display summary of changes for this release T TUTORIAL...
Page 208: Checklist #2: Creating A Data Set With The Allocate Command
RECFM(v,b) and a record format of FB as RECFM(f,b). If your installation has no attribute recommendations and you have no attributes from the Preliminary Checklist, you can use the attributes in the following example. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 209: Checklist #3: Writing An Exec That Sets Up Allocation To Sysexec
ALLOCATE DA(rexx.exec) NEW DIR(10) SPACE(50,20) DSORG(po) RECFM(v,b) LRECL(255) BLKSIZE(6120) For more information about the ALLOCATE command, see z/OS TSO/E REXX User’s Guide and z/OS TSO/E Command Reference. 2. Edit a member of the newly created PDS by selecting the ISPF/PDF EDIT option (option 2) and specifying the PDS name with a member name.
Page 210: Checklist #4: Writing An Exec That Sets Up Allocation To Sysproc
SYSPROC from the list in the “Preliminary Checklist” on page 186. If there are no other data sets allocated to SYSPROC, specify your PDS only. Your SETUP exec could look like the following example. z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 211 Checklist #4 Sample SETUP Exec /****************************** REXX *******************************/ /* This exec is an example of how to allocate a private PDS named */ /* USERID.REXX.EXEC to the beginning of a concatenation to SYSPROC */ /* that consists of 3 other data sets named 'ICQ.INFOCNTR.ICQCLIB' */ /* 'SYS1.TSO.CLIST', and 'ISP.ISPF.CLISTS'.
Page 212 NEW PASSWORD ===> PROCEDURE ===> MYPROC GROUP IDENT ===> ACCT NMBR ===> 00123 SIZE ===> 5800 PERFORM ===> COMMAND ===> EXEC rexx.exec(setup) exec ENTER AN 'S' BEFORE EACH OPTION DESIRED BELOW: -NOMAIL -NONOTICE -RECONNECT -OIDCARD z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 213: Appendix B. Specifying Alternate Libraries With The Altlib Command
1. With ALTLIB, data sets concatenated to each of the levels can have differing characteristics (logical record length and record format), but the data sets within the same level must have the same characteristics. © Copyright IBM Corp. 1988, 2001...
Page 214: Stacking Altlib Requests
To deactivate searching for a certain level, use the DEACTIVATE operand; for example, to deactivate searching for execs on the system level (those allocated to SYSEXEC or SYSPROC), issue: ALTLIB DEACTIVATE SYSTEM(exec) And, to reset exec searching back to the system level, issue: ALTLIB RESET z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 215: Appendix C. Comparisons Between Clist And Rexx
Some major features of REXX that are different from CLIST are: v Host command environments - TSO/E REXX has the ability to invoke commands from several environments in MVS and ISPF, as well as from TSO/E. The ADDRESS instruction sets the environment for commands. For more information, see “Issuing Other Types of Commands from an Exec”...
Page 216: Accessing System Information
&SYSICMD SYSICMD &SYSISPF SYSISPF &SYSNEST SYSNEST &SYSPCMD SYSPCMD &SYSSCMD SYSSCMD For System Information For System Information &SYSCPU SYSCPU &SYSHSM SYSHSM &SYSJES SYSJES &SYSLRACF SYSLRACF &SYSNODE SYSNODE &SYSRACF SYSRACF &SYSSRV SYSSRV &SYSTERMID SYSTERMID &SYSTSOE SYSTSOE z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 217: Controlling Program Flow
Accessing System Information CLIST REXX Control Variables: Arguments of the MVSVAR external function: For System Information For System Information &SYSAPPCLU SYSAPPCLU &SYSDFP SYSDFP &SYSMVS SYSMVS &SYSNAME SYSNAME &SYSSECLAB SYSSECLAB &SYSSMFID SYSSMFID &SYSSMS SYSSMS &SYSCLONE SYSCLONE &SYSPLEX SYSPLEX &SYSSYMDEF SYMDEF Controlling Program Flow CLIST REXX Branching...
Page 218: Debugging
SIGNAL ON HALT, SIGNAL ON NOVALUE, and SIGNAL ON SYNTAX instructions. CALL ON ERROR, CALL ON FAILURE, and CALL ON HALT instructions.¹ For more information about REXX error handling instructions, see z/OS TSO/E REXX Reference. Execution CLIST REXX Explicit Explicit...
Page 219: Interactive Communication
Execution CLIST REXX 1. Allocate/concatenate to SYSPROC 1. Allocate/concatenate to SYSPROC or SYSEXEC 2. Specify member name of PDS with or without % 2. Specify member name of PDS with or without % Interactive Communication CLIST REXX Reading from the terminal Reading from the terminal READ, READDVAL statements PULL, PARSE PULL, PARSE UPPER PULL, PARSE EXTERNAL...
Page 220: Performing File I/O
Continuing a statement over more than one line Continuing an instruction over more than one line Use - or + Use , IF &STR(SYSDATE)=&STR(10/13/87) THEN + say 'This instruction', WRITE On &SYSDATE the system was down. 'covers two lines.' z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 221: Using Functions
Syntax CLIST REXX Separating statements within a line Separating instructions within a line No more than one statement per line Use ; do 5; Say 'Hello'; end Character set of statements Character set of instructions Must be in uppercase Can be upper, lower, or mixed case Comments Comments Enclose between /* */, closing delimiter optional at the end of a line.
Page 222 Using Variables z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 223: Appendix D. Notices
Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Page 224 The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.
Page 225: Programming Interface Information
This book documents intended Programming Interfaces that allow the customer to write programs to obtain the services of z/OS TSO/E REXX language processor. Trademarks The following terms are trademarks of the IBM Corporation in the United States or other countries or both: v CICS...
Page 226 V1R1.0 TSO/E REXX User’s Guide...
Page 227: Bibliography
TSO/E Programming Guide, SA22-7788 v z/OS TSO/E Programming Services, SA22-7789 v z/OS TSO/E REXX Reference, SA22-7790 v z/OS TSO/E REXX User’s Guide, SA22-7791 v z/OS TSO/E System Programming Command Reference, SA22-7793 v z/OS TSO/E System Diagnosis: Data Areas, GA22-7792 v z/OS TSO/E User’s Guide, SA22-7794...
Page 228 MVS Data Areas, Vol 4 (RD-SRRA), GA22-7584 v z/OS MVS Data Areas, Vol 5 (SSAG-XTLST), GA22-7585 ISPF Publications v z/OS ISPF Services Guide, SC34-4819 v z/OS ISPF Dialog Developer’s Guide and Reference, SC34-4821 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 229: Index
#1 - creating and editing a data set using passing to an exec 24 ISPF/PDF 187 used to pass information to a function 82 used to pass information to a subroutine 74 checklist #2 - creating a data set with ALLOCATE 190 © Copyright IBM Corp. 1988, 2001...
Page 230 85 manipulating 136 used in EXECIO command 156, 158, 161 passing information between an exec and a used in LISTDSI 124 routine 140 using stems 86 passing information to an interactive command 142 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 231 data stack (continued) exec (continued) protecting an element 147 prompting the user for input to a TSO/E removing an element 137 command 124, 149 removing an element from a stack with a buffer 143 receiving input 22 search order for processing 139 returning information to a CLIST 176 type of input 139 running...
Page 232 LISTDSI 120 speeding up search time 18 MSG 122 using % 18 MVSVAR 123 inclusive OR 33 OUTTRAP 123 infinite loop PROMPT 124 from TSO/E background and MVS batch 180 SETLANG 125 stopping 48 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 233 input instruction 71 (continued) TRACE passing argument 24 ending tracing 117 preventing translation to uppercase 23 interactive tracing 114 receiving with ARG 22 tracing command 111 receiving with PULL 21 tracing expression 37 sending with EXEC command 22 type of to an exec assignment 13 preventing translation to uppercase 20, 23...
Page 234 TSO/E background 180 multiple strings 92 running an exec 178 separator using IRXJCL 178 blank 89 using the data stack 180 number 90 MVS host command environment 102 string 90 MVSVAR external function 123 variable 90 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 235 parsing (continued) REXX instruction 71 (continued) template 89 ADDRESS 106 partitioned data set ARG 22, 74, 82, 88 creating in ISPF/PDF 187 blank 14 creating with ALLOCATE 190 CALL/RETURN 57 description 185 comment 14 for an exec 7 conditional 41 passing arguments 24 continuing to the next line 10 PDS 7...
Page 236 57 SYSSMS 123 comparison to a function 69, 83 SYSSRV 129 description 69 system file exposing a specific variable 74 external 71 allocating to 17, 174, 185 internal 71 reason to allocate to 174 z/OS V1R1.0 TSO/E REXX User’s Guide...
Page 237 TSO/E external function (continued) SYSEXEC 17, 174, 195 SYSCPUS 126 SYSPROC 14, 17, 174, 195 SYSDSN 126 SYSUEXEC 195 SYSVAR 127 SYSUPROC 195 TSO/E REXX command Systems Application Architecture (SAA) DELSTACK 149 Procedures Language xiii description 97 SYSTERMID 129 DROPBUF 144 SYSTSOE 129...
Page 238 V1R1.0 TSO/E REXX User’s Guide...
Page 239 No Thank you for your responses. May we contact you? When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you.
Page 240 IF MAILED IN THE UNITED STATES BUSINESS REPLY MAIL FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK POSTAGE WILL BE PAID BY ADDRESSEE IBM Corporation Department 55JA, Mail Station P384 2455 South Road Poughkeepsie, NY 12601-5400 _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _...
Page 242 Program Number: 5694-A01 Printed in the United States of America on recycled paper containing 10% recovered post-consumer fiber. SA22-7791-00...

IBM TSO/E REXX User Manual

Table of Contents

Chapter 1. Introduction

Chapter 2. Writing and Running a Rexx Exec

Chapter 3. Using Variables and Expressions

Chapter 4. Controlling the Flow Within an Exec

Chapter 5. Using Functions

Chapter 6. Writing Subroutines and Functions

Chapter 7. Manipulating Data

Chapter 8. Entering Commands from an Exec

Chapter 9. Diagnosing Problems Within an Exec

Chapter 10. Using Tso/E External Functions

Chapter 11. Storing Information in the Data Stack

Chapter 12. Processing Data and Input/Output Processing

Spaces

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

Appendix A. Allocating Data Sets

Appendix B. Specifying Alternate Libraries with the ALTLIB Command

Appendix C. Comparisons between CLIST and REXX

Appendix D. Notices

Quick Links

Chapters

Related Manuals for IBM TSO/E REXX

Summary of Contents for IBM TSO/E REXX