Practical Usage of MVS REXX

1. Introduction.- 1.1 rexx background.- 1.2 rexx characteristics.- 1.3 rexx applications.- 1.4 REXX's future.- 2. REXX Facilities.- 2.1 Introduction.- 2.2 rexx structure.- 2.2.1 Token.- 2.2.2 Literal string.- 2.2.3 Hexadecimal literal string.- 2.2.4 Binary literal string.- 2.2.5 Symbol.- 2.2.6 Numeric symbol.- 2.2.7 Variables.- 2.2.8 Operator.- 2.2.9 Prefix operators.- 2.2.10 Arithmetic operators.- 2.2.11 Abuttal operator.- 2.2.12 Comparative operators.- 2.2.13 Logical operators.- 2.2.14 Implicit concatenation.- 2.2.15 Other syntax elements.- 2.3 rexx expressions.- 2.3.1 Arithmetic expression.- 2.3.2 Comparative expression.- 2.3.3 Logical (Boolean) expression.- 2.4 Statements.- 2.5 Invocation of a rexx exec.- 2.6 Comparison with CLISTS.- 3. REXX Processing Elements.- 3.1 Introduction.- 3.2 Statements.- 3.3 Routines.- 3.3.1 Subroutine.- 3.3.2 Procedure.- 3.3.3 Function.- 3.3.4 Search order.- 3.3.5 Invocation.- 3.3.6 Parameters (arguments).- 3.3.7 Return.- 3.3.8 Communication between execs.- 3.4 Types of instruction.- 3.4.1 Conditional control.- 3.4.2 Loop control.- 3.5 Control processing flow.- 3.6 Assignment.- 3.7 Stack (queue) processing.- 3.7.1 Stack as terminal input buffer.- 3.7.2 Stack used for general data storage.- 3.7.3 Stack used for passing data between execs.- 3.7.4 File buffer.- 3.8 Parsing.- 3.9 Debugging.- 3.10 Miscellaneous instructions.- 3.11 Commands.- 3.12 Special variables.- 3.12.1 rc - Return code.- 3.12.2 result - Function result.- 3.12.3 sigl - Source line number.- 4. REXX Instructions.- 4.1 Introduction.- 4.2 Instruction descriptions.- 4.2.1 address - Set environment.- 4.2.2 arg - Fetch argument.- 4.2.3 call - Invoke routine.- 4.2.4 do - Define start of DO-block.- 4.2.5 drop - Free variable.- 4.2.6 exit- Terminate exec.- 4.2.7 if - Conditional execution.- 4.2.8 interpret - Interpret statement.- 4.2.9 iterate - Terminate the current cycle in the Do-loop.- 4.2.10 leave - Terminate Do-loop.- 4.2.11 nop - No-operation.- 4.2.12 numeri c - Define numeric formats.- 4.2.13 options - Pass special parameters to the language processor.- 4.2.14 parse - Assign data.- 4.2.15 procedure - Define internal procedure.- 4.2.16 pull - Fetch data element from the head of the stack.- 4.2.17 push - Set data element at the head of the stack.- 4.2.18 queue - Set data element at the tail of the stack.- 4.2.19 return - Return from routine.- 4.2.20 say - Display.- 4.2.21 select - Select one condition from a series of conditions.- 4.2.22 signal - Enable (or disable) an exception condition, or cause control to be passed to a routine (or label).- 4.2.23 trace - Set debugging options.- 4.2.24 upper - Transform lowercase characters into uppercase.- 4.2.25 = - Assign.- 4.2.26 Command.- 4.3 Examples.- 5. Exception Handling.- 5.1 Introduction.- 5.2 Condition traps.- 5.2.1 error condition.- 5.2.2 failure condition.- 5.2.3 halt condition.- 5.2.4 novalue condition.- 5.2.5 syntax condition.- 5.2.6 Stacked conditions.- 5.3 Explicit invocation.- 6. String Processing.- 6.1 Introduction.- 6.2 Word parsing.- 6.3 Delimiter parsing.- 6.4 Positional parsing.- 6.5 Dynamic parsing.- 6.6 Argument parsing.- 6.7 Worked examples.- 7. Numbers and Arithmetic.- 7.1 Introduction.- 7.2 Number.- 7.3 Arithmetic operators.- 7.3.1 Power (exponentiation).- 7.3.2 Multiplication.- 7.3.3 Division.- 7.3.4 Modulo (integer) division.- 7.3.5 Remainder division.- 7.3.6 Numeric comparison.- 7.4 Precision and representation.- 7.4.1 Computational base.- 7.4.2 Retention of significance.- 7.4.3 Arithmetic exceptions.- 7.5 Sequence of operations.- 7.6 Numeric formatting.- 8. Input/Output.- 8.1 Introduction.- 8.2 Data buffering.- 8.3 Opening and closing the data files.- 8.4 Terminal operations.- 8.5 File-mode operations.- 8.5.1 File positioning.- 8.5.2 Write operation.- 8.5.3 Delete data operation.- 8.5.4 Read operation.- 8.5.5 Update operation.- 9. Debugging.- 9.1 Introduction.- 9.2 Exception conditions.- 9.3 Tracing options.- 9.3.1 all - Display all expressions before execution.- 9.3.2 commands - Display all conmiands before execution.- 9.3.3 error - Display all commands which return an error condition.- 9.3.4 failure - Display all commands which return a negative error condition.- 9.3.5 intermediate - Display all expressions (with intermediate results) before being executed.- 9.3.6 labels - Display all labels as they are reached.- 9.3.7 results - Display all expressions (with end results) before being executed.- 9.3.8 syntax - Check syntax without processing the statements.- 9.3.9 n - Suppress trace intervention.- 9.4 Trace output.- 9.4.1 Trace data prefixes.- 9.4.2 Trace intermediate data prefixes.- 9.4.3 Trace output example.- 9.5 Interactive debug.- 9.5.1 Interactive debugging example.- 9.6 Parametric debug.- 9.7 Errors with host commands and functions.- 10. REXX Built-in Functions.- 10.1 Introduction.- 10.1.1 Function-like (direct) invocation.- 10.1.2 Call invocation.- 10.1.3 Internal functions.- 10.1.4 Function side-effects.- 10.1.5 Invocation errors.- 10.1.6 Internal data format.- 10.2 Function definitions.- 10.2.1 abbrev - Test whether string is an abbreviation.- 10.2.2 abs - Return absolute value.- 10.2.3 address - Return name of current environment.- 10.2.4 arg - Return argument.- 10.2.5 bitand - Logical And.- 10.2.6 bitor - Logical Or.- 10.2.7 bitxor - Logical Exclusive-Or.- 10.2.8 B2X - Convert binary data to hexadecimal.- 10.2.9 centre (CENTER) - Centralise data.- 10.2.10 compare - Compare.- 10.2.11 condition - Return condition.- 10.2.12 copies - Duplicate data.- 10.2.13 C2D - Convert character data to decimal.- 10.2.14 C2X - Convert character data to hexadecimal.- 10.2.15 datatype - Determine data type.- 10.2.16 date - Return current date.- 10.2.17 delstr - Delete substring.- 10.2.18 delword - Delete words.- 10.2.19 digits - Return the numeric DIGITS setting.- 10.2.20 D2C - Convert decimal data to character.- 10.2.21 D2X - Convert hexadecimal data to character.- 10.2.22 errortext - Retum message text.- 10.2.23 find - Search for word.- 10.2.24 form - Determine numeric FORM setting.- 10.2.25 format - Format numeric value.- 10.2.26 fuzz - Determine numeric FUZZ setting.- 10.2.27 index - Search for substring.- 10.2.28 insert - Insert substring.- 10.2.29 justify - Justify string of words.- 10.2.30 lastpos - Determine last position of phrase.- 10.2.31 left - Left-align string.- 10.2.32 length - Determine length of string.- 10.2.33 linesize - Retum the (maximum) width of a terminal line.- 10.2.34 max - Determine the maximum of a series of numeric values.- 10.2.35 min - Determine the minimum of a series of numeric values.- 10.2.36 overlay - Overlay part of a string with a phrase.- 10.2.37 pos - Search for substring.- 10.2.38 queued - Determine the number of entries in the queue.- 10.2.39 random - Generate a (pseudo-)random number.- 10.2.40 reverse - Reverse the sequence of data.- 10.2.41 right - Right-align string.- 10.2.42 sign - Determine numeric sign.- 10.2.43 sourceline - Retum "program line".- 10.2.44 space - Insert fill-character between words.- 10.2.45 strip - Remove padding-characters at the start or end of a string.- 10.2.46 substr - Extract substring.- 10.2.47 suBWORD - Extract series of words from word-string.- 10.2.48 symbol - Determine the status of a symbol.- 10.2.49 time - Return the current time-of-day.- 10.2.50 trace - Return (and set) current trace mode.- 10.2.51 translate - Translate.- 10.2.52 trunc - Truncate numeric value.- 10.2.53 userid - Return Userid.- 10.2.54 value - Return the content of a symbol.- 10.2.55 verify - Test whether only characters in a phrase are present in string.- 10.2.56 word - Fetch word.- 10.2.57 wordindex - Determine the character position of a word in a string of words.- 10.2.58 wordlength - Determine word length.- 10.2.59 wordpos - Determine word-number of word in word-string.- 10.2.60 words - Determine number of words in word-string.- 10.2.61 xrange - Define a range of hexadecimal values.- 10.2.62 X2B - Convert hexadecimal to binary.- 10.2.63 X2c - Convert hexadecimal to character.- 10.2.64 X2D - Convert hexadecimal to decimal.- 10.3 Examples.- 11. Host REXX Commands.- 11.1 Introduction.- 11.2 Host rexx command definitions.- 11.2.1 delstack - Delete stack.- 11.2.2 dropbuf - Release buffer.- 11.2.3 execio - Perform input/output operation.- 11.2.4 executil - Specify execution environment for rexx program.- 11.2.5 he - Halt execution.- 11.2.6 hi - Halt interpretation.- 11.2.7 ht - Halt typing.- 11.2.8 makebuf - Create new buffer in the stack.- 11.2.9 newstack - Create a new stack.- 11.2.10 qbuf - Query buffer.- 11.2.11 qelem - Query elements.- 11.2.12 qstack - Query stack.- 11.2.13 rt - Resume typing.- 11.2.14 subcom - Confirm the host environment.- 11.2.15 te - Trace end.- 11.2.16 ts - Trace start.- 11.3 Example.- 12. MVS Command Functions.- 12.1 Introduction.- 12.2 mvs command function calls.- 12.2.1 getmsg - Retrieve a console session message.- 12.2.2 listdsi - List (obtain) dataset information.- 12.2.3 msg - Set (interrogate) clist CONTROL msg option.- 12.2.4 outtrap - Trap tso display output.- 12.2.5 prompt - Set (interrogate) clist CONTROL prompt option.- 12.2.6 setlang - Set language.- 12.2.7 storage - Set (interrogate) main storage content.- 12.2.8 sysdsn - Request dataset status.- 12.2.9 sysvar - Fetch tso system variable.- 12.3 Invocation of other tso commands.- 12.4 Example.- 13. REXX Invocation.- 13.1 Introduction.- 13.2 Invocation from TSO/ISPF.- 13.3 Invocation from batch TSO.- 13.4 Invocation from MVS.- 13.5 Linkage to the host (MVS-TSO) environment.- 13.6 Linkage to programs.- 13.6.1 link (ATTACH).- 13.6.2 linkmvs (ATTACHMVS).- 13.6.3 linkpgm (ATTACHPGM).- 13.7 Interface with ispexec (ISPF Dialog Manager).- 13.8 Interface with i SRED i T (ISPF/PDF Edit macro).- 13.8.1 Macro example.- 13.9 Interface with DB2 (Database2).- 13.9.1 DB2 invocation example.- 13.10 Interface with qmf (Query Management Facility).- 13.10.1 dsqcix - qmf Callable Interface.- 13.10.2 dsqcci - qmf Command Interface.- 13.11 Interface from programs with REXX.- 14. System Interfaces.- 14.1 Introduction.- 14.2 General conditions.- 14.2.1 C/370 restrictions.- 14.2.2 Other program language restrictions.- 14.3 Invocation of a rexx exec.- 14.3.1 Interface from programs to batch rexx (IRXJCL service).- 14.3.2 Invocation of a rexx exec using the tso Service Facility (IJKEFTSR service).- 14.4 Interface from programs to rexx processor (IRXEXEC).- 14.4.1 Sample program.- 14.4.2 Invocation of an in-store exec.- 14.5 Program access to rexx variables (IRXEXCOM service).- 14.5.1 Sample programs.- 14.5.2 Sample retrieval program.- 14.6 Stack processing (IRXSTK service).- 14.6.1 Sample programs.- 14.7 Command interface.- 14.7.1 Entry conditions.- 14.7.2 Parameter list.- 14.7.3 Exit conditions.- 14.7.4 Examples.- 14.7.5 Command registration interface.- 14.7.6 Command router.- 14.8 Function interface.- 14.8.1 Entry conditions.- 14.8.2 Exit conditions.- 14.8.3 Sample function program.- 14.9 Function package.- 14.9.1 Function directory.- 14.10 Load routine - irxload service.- 14.11 Initialisation routine - irxinit service.- 14.11.1 Sample program.- 14.12 Get result - irxrlt service.- 14.12.1 Sample program.- 14.13 Control blocks.- 14.13.1 Argument List.- 14.13.2 efpl (External Function Parameter List).- 14.13.3 envblock (Environment Block).- 14.13.4 evalblock (Evaluation Block).- 14.13.5 execblk (Exec Block).- 14.13.6 instblk (In-storage Control Block).- 14.13.7 shvblock (Shared Variable (Request) Block).- 14.13.8 veep (Vector of External Entry Points).- 14.14 Examples.- 14.14.1 Assembler implementation.- 14.14.2 C/370 implementation.- 14.14.3 cobol implementation.- 14.14.4 PL/I implementation.- 15. Worked Examples.- 15.1 Introduction.- 15.2 Worked example 1.- 15.3 Worked example 2.- 15.4 Worked example 3.- 15.5 Worked example 4.- 15.6 Worked example 5.- Appendix A. Syntax Notation.- Appendix B. Glossary.