Practical Usage of MVS REXX

Practical Usage of MVS REXX provides a concise and complete source of information for the development of applications using the REXX language - IBM's systems application architecture procedural language. The book adopts a highly practical approach and includes many lists and diagrams to make finding the relevant information as easy to find and use as possible. It particularly emphasises the interfacing capabilities of REXX. Both beginners and experts will find the book useful. Beginners are led through the steps required to develop REXX applications via a series of worked examples, and experts will find a complete and easy reference to the language.

Table of Contents:
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.