Practical Usage of TSO REXX
Springer London Berlin Heidelberg New York Barcelona Hong Kong Milan Paris Singapore Tokyo
Anthony S. Rudd Practical Usage of TSOREXX 3rd revised edition t Springer
Anthony S. Rudd, BSc, MSc (Hons) ISBN-13: 978-1-85233-261-7 DOl: 10.1007/978-1-4471-0755-2 e-isbn-13: 978-1-4471-0755-2 British Library Cataloguing in Publication Data Rudd, Anthony S. Practical usage oftso REXX. - 3rd ed. 1. REXX (Computer program language) I. Title II. Practical usage ofmvs REXX 005.2'62 ISBN 1852332611 Library of Congress Cataloging-in-Publication Data Rudd, Anthony S., 1945- Practical usage oftso REXX I Anthony S. Rudd. - - 3rd ed. p.cm. 1. REXX (Computer program language) 2. Time-sharing computer systems L Title QA 76.73.R24 R84 2000 005.2'28-dc21 00-020844 Apart from any fair dealing for the purposes of research or private study, or criticism or review, as permitted under the Copyright, Designs and Patents Act 1988, this publication may only be reproduced, stored or transmitted. in any form or by any means, with the prior permission in writing of the publishers, or in the case of reprographic reproduction in accordance with the terms of licences issued by the Copyright Licensing Agency. Enquiries concerning reproduction outside those terms should be sent to the publishers. Springer-Verlag London Limited 2000 Softcover reprint of the hardcover 3rd edition 2000 The use of registered names, trademarks etc. in this publication does not imply, even in the absence of a specific statement, that such names are exempt from the relevant laws and reguiations and therefore free for general use. The publisher makes no representation, express or implied. with regard to the accuracy of the information contained in this book and cannot accept any legal responsibility or liability for any errors or omissions that may be made. Typesetting: Camera ready by author 34/3830-543210 Printed on acid-free paper SPIN 10754897
Preface The aim of PRACI'ICAL USAGE OF TSO REXX is to show the practical use of REXX in the OS/390 TSO/E environment. The book covers not only the basic language elements but particularly emphasises the expansibility of REXX. In addition to its use as a procedures language, one of the major uses of REXX is interfacing to and from other components. Consequently, the major part of this book is devoted to the interfacing aspects of REXX. The chapter on the programming interfaces includes a wide range of examples in Assembler, C (C+ +), COBOL, and PLlI. This third edition of the book, previously titled PRACI'ICAL USAGE OF MVS REXX, has been revised to discuss the new REXX features introduced for the OS/390 TSO/E environment. It also includes two new chapters that cover the REXX compiler and provide a general discussion of the implementation aspects of using REXX as a programming language. For historical reasons, the TSO/E REXX implementation uses the term MVS as synonym for the host operating system environment (e.g. OS/390 in this case). At this point I would like to thank Detlef Insel for his help.
Table of Contents Preface... v 1. Introduction 1.1 REXX background...... 1 1.2 REXX characteristics... 2 1.3 REXX applications... 2 1.4 REXX'S future... 3 2. REXX Facilities 2.1 2.2 2.2.1 2.2.2 2.2.3 2.2.4 2.2.5 2.2.6 2.2.7 2.2.8 2.2.9 2.2.10 2.2.11 2.2.12 2.2.13 2.2.14 2.2.15 Introduction... 4 REXX structure... 8 Token... 8 Literal string... 8 Hexadecimal literal string... 9 Binary literal string... 10 Symbol... 10 Numeric symbol... 10 Variables... 11 Operator.... 13 Prefix operators... 13 Arithmetic operators... 14 Abuttal operator... 14 Comparative operators... 15 Logical operators... 16 Implicit concatenation operators... 16 Other syntax elements... 17
viii TABLE OF CONTENTS 2.3 REXX expressions... 17 2.3.1 Arithmetic expression... 18 2.3.2 Comparative expression... 19 2.3.3 Logical (Boolean) expression... 19 2.4 Statements... 20 2.5 Invocation of a REXX exec... 21 2.6 Comparison with CLISTS... 21 3. REXX Processing Elements 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.3.1 3.3.2 3.3.3 3.3.4 3.3.5 3.3.6 3.3.7 3.3.8 3.4.1 3.4.2 3.7.1 3.7.2 3.7.3 3.7.4 3.12.1 3.12.2 3.12.3 Introduction... 22 Statements... 22 Routines...,... 24 Subroutine... 25 Procedure... 26 Function... 26 Search order... 27 Invocation... 28 Parameters (arguments)... 29 Return... 32 Communication between execs... 32 Types of instruction... '"... 34 Conditional control.... 34 Loop control... 36 Control processing flow... 39 Assignment... 39 Stack (queue) processing... 40 Stack as terminal input buffer....40 Stack used for general data storage....41 Stack used for passing data between execs....41 File buffer...,... 43 Parsing... 43 Debugging... 43 Miscellaneous instructions... 43 Commands... 44 Special variables... 44 RC - Return code... 44 RESUL T - Function result.... 45 SIGL - Source line number... 45 4. REXX Instructions 4.1 Introduction... 47 4.2 Instruction descriptions... 48 4.2.1 ADDRESS - Set environment..... 48 4.2.2 ARG - Fetch argument.... 51 4.2.3 CALL - Invoke routine... 52 4.2.4 DO - Define start of Do-block... 54 4.2.5 DROP - Free variable... 56 4.2.6 EXIT - Terminate exec... 57 4.2.7 IF - Conditional execution... 58 4.2.8 INTERPRET - Interpret statement... 59
T ABLE OF CONTENTS ix 4.3 4.2.9 4.2.10 4.2.11 4.2.12 4.2.13 4.2.14 4.2.15 4.2.16 4.2.17 4.2.18 4.2.19 4.2.20 4.2.21 4.2.22 4.2.23 4.2.24 4.2.25 4.2.26 ITERATE - Terminate the current cycle in the Do-loop... 60 LEAVE - Terminate Do-loop... 61 NOP - No-operation... 62 NUMERIC - Define numeric formats... 62 OPTIONS - Pass special parameters to the language processor... 63 PARSE - Assign data... 64 PROCEDURE - Define internal procedure... 66 PULL - Fetch data element from the head of the stack... 66 PUSH - Set data element at the head ofthe stack... 67 QUEUE - Set data element at the tail of the stack... 68 RETURN - Return from routine... 68 SAY - Display... 69 SELECT - Select one condition from a series of conditions... 70 SIGNAL - Enable (or disable) an exception condition, or cause control to be passed to a routine (or label)... 71 TRACE - Set debugging options... 74 UPPER - Transform lowercase characters into uppercase... 76 = - Assign... 76 Command... 77 Examples... 77 5. Exception Handling 5.1 Introduction... 80 5.2 Condition traps... 81 5.2.1 ERROR condition... 81 5.2.2 FAILURE condition... 81 5.2.3 HALT condition... 82 5.2.4 NOVALUE condition... 82 5.2.5 SYNTAX condition... 83 5.2.6 Stacked conditions... 83 5.3 Explicit invocation... 86 6. String Processing 6.1 Introduction... 87 6.2 Word parsing... 88 6.3 Delimiter parsing... 90 6.4 Positional parsing... 91 6.5 Dynamic parsing... 92 6.6 Argument parsing... 92 6.7 Worked examples... 93 7. Numbers and Arithmetic 7. 1 Introduction... 96 7.2 Number... 96 7.3 Arithmetic operators... 97 7.3.1 Power (exponentiation)... 98 7.3.2 Multiplication... 98 7.3.3 Division... 98 7.3.4 Modulo (integer) division... 98 7.3.5 Remainder division... 99
x TABLE OF CONTENTS 7.3.6 Numeric comparison... '"... 99 7.4 Precision and representation............... 100 7.4.1 Computational base... 101 7.4.2 Retention of significance........................................... 10 1 7.4.3 Arithmetic exceptions......................................... 101 7.5 Sequence of operations... 102 7.6 Numeric formatting... 102 8. Input/Output 8.1 Introduction... 104 8.2 Data buffering... 105 8.3 Opening and closing the data files... 105 8.4 Terminal operations... 105 8.5 File-mode operations... 106 8.5.1 File positioning... 107 8.5.2 Write operation... 107 8.5.3 Delete data operation... 107 8.5.4 Read operation... 108 8.5.5 Update operation... 108 9. Debugging 9.1 Introduction... 109 9.2 9.3 9.4 9.5 9.6 9.7 9.3.1 9.3.2 9.3.3 9.3.4 9.3.5 9.3.6 9.3.7 9.3.8 9.3.9 9.4.1 9.4.2 9.4.3 9.5.1 Exception conditions... 110 Tracing options... III ALL - Display all expressions before execution... 111 COMMANDS - Display all commands before execution... 112 ERROR - Display all commands which return an error condition... 112 FAILURE - Display all commands which return a negative error condition... 113 INTERMEDIATE - Display all expressions (with intermediate results) before being executed... 113 LABELS - Display all labels as they are reached... 114 RESUL TS - Display all expressions (with end results) before being executed... 114 SYNTAX - Check syntax without processing the statements... 115 n - Suppress trace intervention... 115 Trace output.................................................... 117 Trace data prefixes....................... 117 Trace intermediate data prefixes... 117 Trace output example...................................... 118 Interactive debug... 119 Interactive debugging example... 120 Parametric debug... 121 Errors with host commands and functions... 122 10. REXX Built-in Functions 10.1 Introduction... 123 10.1.1 Function-like (direct) invocation... 124 10.1.2 Call invocation... 124
TABLE OF CONTENTS xi 10.1.3 10.1.4 10.1.5 10.1.6 10.2 10.2.1 10.2.2 10.2.3 10.2.4 10.2.5 10.2.6 10.2.7 10.2.8 10.2.9 10.2.10 10.2.11 10.2.12 10.2.13 10.2.14 10.2.15 10.2.16 10.2.17 10.2.18 10.2.19 10.2.20 10.2.21 10.2.22 10.2.23 10.2.24 10.2.25 10.2.26 10.2.27 10.2.28 10.2.29 10.2.30 10.2.31 10.2.32 10.2.33 10.2.34 10.2.35 10.2.36 10.2.37 10.2.38 10.2.39 10.2.40 10.2.41 10.2.42 10.2.43 Internal functions... 125 Function side-effects................................................. 125 Invocation errors... 126 Internal data format... 126 Function definitions.................................................. 126 ABBREV - Test whether string is an abbreviation... 128 ABS - Return absolute value... 129 ADDRESS - Return name of current environment... 129 ARG - Return argument... 129 BITAND - Logical And... 130 B ITOR - Logical Or... 130 BITXOR - Logical Exclusive-Or... 131 B2X - Convert binary data to hexadecimal... 132 CENTRE (CENTER) - Centralise data... 132 COMPARE - Compare... 133 CONDITION - Return condition... 133 COPIES - Replicate data... 134 C2D - Convert character data to decimal........................... 135 C2X - Convert character data to hexadecimal..................... 135 DATA TYPE - Determine data type... 136 DATE - Return current date... 137 DELSTR - Delete substring... 138 DELWORD - Delete words... 139 DIGITS - Return the NUMERIC DIGITS setting... 139 D2C - Convert decimal to character... 140 D2X - Convert decimal to hexadecimal... 140 ERRORTEXT - Return message text... 141 FIND - Search for word... 141 FORM - Determine NUMER I C FORM setting... 142 FORMAT - Format numeric value... 142 FUZZ - Determine NUMERIC FUZZ setting... 143 INDEX - Search for substring... 143 INSERT - Insert substring............................................ 143 JUST! FY - Justify string of words... 144 LASTPOS - Determine last position of phrase... 145 LEFT - Left-align string... 146 LENGTH - Determine length of string... 146 LINESIZE - Return the (maximum) width of a terminal line... 147 MAX - Determine the maximum of a series of numeric values... 147 MIN - Determine the minimum of a series of numeric values... 147 OVERLAY - Overlay part of a string with a phrase... 148 POS - Search for substring........................................... 149 QUEUED - Determine the number of entries in the queue... 149 RANDOM - Generate a (pseudo-)random number... 150 REVERSE - Reverse the sequence of data... 151 RIGHT - Right-align string... 151 SIGN - Determine numeric sign... 152 SOURCELINE - Return "program line"... 152
xii TABLE OF CONTENTS 10.2.44 10.2.45 10.2.46 10.2.47 10.2.48 10.2.49 10.2.50 10.2.51 10.2.52 10.2.53 10.2.54 10.2.55 10.2.56 10.2.57 10.2.58 10.2.59 10.2.60 10.2.61 10.2.62 10.2.63 10.2.64 10.3 SPACE - Insert fill-character between words... 153 STRIP - Remove padding-characters at the start or end of a string................................... 153 SUBSTR - Extract substring... 154 SUBWORD - Extract series of words from word-string... 155 SYMBOL - Determine the status of a symbol... 156 TIME - Return the current time-of-day... 156 TRACE - Return (and set) current trace mode... 158 TRANSLATE - Translate characters... 159 TRUNC - Truncate numeric value... 161 USERID - Return Userid... 162 VALUE - Return (and set) the contents of a symbol... 162 VERI FY - Test whether only characters in a phrase are present in string....................... 163 WORD - Fetch word... 163 WORD INDEX - Determine the character position of a word in a string of words...................................................... 164 WORDLENGTH - Determine word length... 164 WORDPOS - Determine the word-number of word in a word-string... 165 WORDS - Determine the number of words in a word-string... 165 XRANGE - Define a range of hexadecimal values.................. 166 X2B - Convert hexadecimal to binary............. 166 X2C - Convert hexadecimal to character.......................... 167 X2D - Convert hexadecimal to decimal... 167 Examples... "......................................... 168 11. Host REXX Commands 11.1 Introduction... 171 11.2 Host REXX command definitions..................... 171 11.2.1 DELSTACK - Delete stack... 172 11.2.2 DROPBUF - Release buffer.... 172 11.2.3 EXECIO - Perform input/output operation... 173 11.2.4 EXECUTI L - Specify execution environment for REXX exec... 175 11.2.5 HE - Halt execution............... 177 11.2.6 HI - Halt interpretation... 177 11.2.7 HT - Halt typing........... 177 11.2.8 MAKEBUF - Create new buffer in the stack... 177 11.2.9 NEWSTACK - Create a new stack... 178 11.2.10 QBUF - Query buffer........... 178 11.2.11 QELEM - Query elements... 179 11.2.12 QSTACK - Query stack... 179 11.2.13 RT - Resume typing... 180 11.2.14 SUBCOM - Confirm the host environment........... 180 11.2.15 TE - Trace end... 180 11.2.16 TS - Trace start... 180 11.3 Example... 181 12. MVS Command Functions 12.1 Introduction... 182
TABLE OF CONTENTS xiii 12.2 12.2.1 12.2.2 12.2.3 12.2.4 12.2.5 12.2.6 12.2.7 12.2.8 12.2.9 12.2.10 12.2.11 12.3 12.4 MVS command function calls... 182 GETMSG - Retrieve a console session message... 184 L1STDSI - List (obtain) dataset information... 186 MSG - Set (interrogate) CLIST CONTROL MSG option... 190 MVSVAR - Obtain information on MVS, TSO, and the current session... 190 OUTTRAP - Trap TSO display output... 192 PROMPT - Set (interrogate) CLIST CONTROL PROMPT option... 194 SET LANG - Set (interrogate) current language... 195 STORAGE - Set (interrogate) main-storage contents... 195 SYSCPUS - Obtain CPU information... 196 SYSDSN - Request dataset status... 197 SYSVAR - Fetch TSO system variable... 198 Invocation of other TSO commands................................ 199 Example... 200 13. REXX Invocation 13.1 13.2 13.3 13.4 13.5 13.6 13.6.1 13.6.2 13.6.3 13.7 13.8 13.8.1 13.9 13.9.1 13.10 13.10.1 13.10.2 13.11 Introduction... 201 Invocation from TSO/ISPF............................................ 202 Invocation from batch TSO... 203 Invocation from batch... 204 Linkage to the host environment... 205 Linkage to programs... 205 LINK (ATTACH)... 206 L1NKMVS (ATTACHMVS)... 207 L1NKPGM (ATTACHPGM)... 208 Interface with I SPEXEC (ISPF Dialog Manager)... 209 Interface with ISREDIT (ISPF/PDF Edit macro)... 210 Macro example... 210 Interface with DB2 (Database2)... 211 DB2 invocation example... 211 Interface with QMF (Query Management Facility)... 211 DSQCIX - QMF Callable Interface... 212 DSQCCI - QMF Command Interface... 213 Interface from programs with REXX... 214 14. System Interfaces 14.1 14.2 Introduction... 215 General conditions... 216 14.2.1 C, C+ + restrictions... 217 14.2.2 Other program language restrictions... 217 14.3 Invocation of a REXX exec... 218 14.3.1 14.3.2 Interface from programs to batch REXX (IRXJCL)... 218 Invocation of a REXX exec using the TSO Service Facility 14.4 14.4.1 14.4.2 14.5 14.5.1 (IJKEFTSR)... 218 Interface from programs to REXX processor (IRXEXEC)... 221 Sample program... 224 Invocation of an in-store exec... 225 Program access to REXX variables (IRXEXCOM service)... 228 Sample programs... 230
xiv TABLE OF CONTENTS 14.5.2 14.6 14.6.1 14.7 14.7.1 14.7.2 14.7.3 14.7.4 14.7.5 14.7.6 14.8 14.8.1 14.8.2 14.8.3 14.9 14.9.1 14.10 14.11 14.11.1 14.12 14.12.1 14.13 14.13.1 14.13.2 14.13.3 14.13.4 14.13.5 14.13.6 14.13.7 14.13.8 14.14 14.14.1 14.14.2 14.14.3 14.14.4 Sample retrieval program... 234 Stack processing (IRXSTK service)... 235 Sample programs... 236 Command interface... 239 Entry conditions... 240 Parameter list... 240 Exit conditions........................................ 241 Examples... 241 Command registration interface (I RXSUBCM).... 244 Command router... 247 Function interface... 247 Entry conditions..., 248 Exit conditions..., 248 Sample function program... 248 Function package... 251 Function directory... 252 Load routine (IRXLOAD service)... 254 Initialisation routine (IRXINIT service)... 256 Sample initialisation program... 257 Get result (IRXRLT service)... 258 Sample I RXRL T program... 259 Control blocks... 260 Argument List... 260 EFPL (External Function Parameter List)... 260 ENVBLOCK (Environment Block)... 261 EV ALBLOCK (Evaluation Block)... 262 EXECBLK (Exec Block)... 263 INSTBLK (In-storage Control Block)... 264 SHVBLOCK (Shared Variable (Request) Block)... 266 VEEP (Vector of External Entry Points)... '" 268 Examples...,...,...,... 269 Assembler implementation... 269 C implementation... 270 COBOL implementation... 274 PLII implementation... 276 15. Worked Examples 15.1 Introduction... 278 15.2 Worked example 1... 279 15.3 Worked example 2... 282 15.4 Worked example 3... 285 15.5 Worked example 4... 291 15.6 Worked example 5... 298 16. REXX Compiler 16.1 Introduction... 301 16.2 JCL procedures... 302 16.2.1 REXXC procedure... 303 16.2.2 REXXCL procedure... 303 16.2.3 REXXCLG procedure... 304
T ABLE OF CONTENTS xv 16.2.4 16.3 16.4 16.4.1 16.5 16.5.1 16.5.2 16.5.3 16.5.4 16.5.5 16.6 16.7 16.7.1 REXXL procedure... 304 Compiler options... 304 Combining compiled objects... 305 Produce a statically loaded program... 305 Stubs... 307 CALLCMD stub... 307 CPPL stub... 307 EFPL stub... 308 CPPLEFPL stub... 308 MVS stub... 308 Performance... 309 Compatibilty... 310 Execution sequence... 310 17. Other Environments 17.1 Introduction... 311 17.2 REXX for CICS... 311 17.3 REXX for UNIX Services... 312 18. Program Development 18.1 18.2 Introduction... 315 Reusability... 316 18.2.1 Productivity... 317 18.2.2 Standardisation... 317 18.3 Readability... 317 18.4 Reliability... 318 18.5 Maintainability... 319 18.6 Compatibility... 320 18.7 Performance... 320 18.8 Expansibility... 321 18.9 Stepwise refinement..... 321 18.10 Portability... 322 18.11 Testing... 322 18.12 Run-time debugging... 322 18.13 Development with the REXX compiler... 324 Appendix A. Syntax Notation... 325 Appendix B. Glossary... 328 Index... 333