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.