z/OS

TSO/E REXX Reference

SA22-7790-10

Note Before using this information and the product it supports, read the information in Notices on page 523.

This edition applies to Version 1, Release 13 of z/OS (5694-A01) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SA22-7790-09. Copyright IBM Corporation 1988, 2011. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Figures . . . . . . . . . . . . . . vii Tables . . . . . . . . . . . . . . . ix About this document . . . . . . . . . xi
Who should read this document . . . . . . . xi How to use this document . . . . . . . . . xi Where to find more information . . . . . . . xiv The z/OS Basic Skills Information Center . . . . xv

Chapter 4. Functions. . . . . . . . . 81
Syntax . . . . . . . . . . . . . . . . 81 Functions and subroutines . . . . . . . . . 82 Built-in functions . . . . . . . . . . . . 87 TSO/E external functions . . . . . . . . . 123

Chapter 5. Parsing . . . . . . . . . 169

Simple templates for parsing into words Parsing with variable patterns . . . . Using UPPER . . . . . . . . . Parsing instructions summary . . . . Parsing instructions examples . . . . Advanced topics in parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 175 176 177 177 178

How to send your comments to IBM

If you have a technical problem . . . . . .

xvii
. xvii

Summary of changes . . . . . . . . xix

Changes made in z/OS Version 1 Release 13 . . . xix Changes made in z/OS Version 1 Release 12 . . . xix Changes made in z/OS Version 1 Release 11 . . . xx

Chapter 6. Numbers and arithmetic

Introduction . Definition . . . . . . . . . . . . . . . . . . . . . . . . .

185
. 185 . 186

Chapter 1. Introduction . . . . . . . . 1
What the SAA Solution Is . . Benefits of using a compiler . . . . . . . . . . . . . . . . 1 . 2

Chapter 7. Conditions and condition traps . . . . . . . . . . . . . . . 195

Action taken when a condition is not trapped Action taken when a condition is trapped . . Condition information . . . . . . . . Special variables . . . . . . . . . . . . . . . . . . 196 197 198 199

Chapter 2. REXX general concepts . . . 5

Structure and general syntax . . . . Expressions and operators . . . . Clauses and instructions . . . . . Assignments and symbols . . . . Commands to external environments . . . . . . . . . . . . . . . . . . . . . . . . . . 6 13 19 20 24

Chapter 8. Using REXX in different address spaces . . . . . . . . . . 201

Additional REXX support . . . . . . . . . Writing execs that run in Non-TSO/E address spaces . . . . . . . . . . . . . . . . Running an exec in a Non-TSO/E address space Writing execs that run in the TSO/E address space Running an exec in the TSO/E address space . . Summary of writing execs for different address spaces . . . . . . . . . . . . . . . . 202 204 205 205 207 208

Chapter 3. Keyword instructions. . . . 45

ADDRESS . . ARG. . . . CALL . . . DO . . . . DROP . . . EXIT. . . . IF. . . . . INTERPRET . ITERATE . . LEAVE . . . NOP. . . . NUMERIC. . OPTIONS . . PARSE . . . PROCEDURE. PULL . . . PUSH . . . QUEUE. . . RETURN . . SAY . . . . SELECT . . SIGNAL . . TRACE . . . UPPER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 47 48 52 57 57 58 59 61 61 62 63 64 65 68 70 71 72 72 73 73 74 76 80

Chapter 9. Reserved keywords, special variables, and command names . . . . . . . . . . . . . . 211

Reserved keywords . . . Special variables . . . . Reserved command names . . . . . . . . . . . . . . . . . . . . . . . 211 . 212 . 213

Chapter 10. TSO/E REXX commands

DELSTACK . . . . DROPBUF . . . . EXECIO . . . . . EXECUTIL . . . . HE . . . . . . . HI . . . . . . . HT . . . . . . . Immediate Commands MAKEBUF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

215
. . . . . . . . . 216 217 218 231 237 238 239 239 240

Copyright IBM Corp. 1988, 2011

iii

NEWSTACK. QBUF . . . QELEM . . QSTACK . . RT . . . . SUBCOM. . TE . . . . TS . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

241 242 244 245 247 247 249 249

Changing the default values for initializing an environment. . . . . . . . . . . . . Specifying values for different environments . . Control blocks created for a Language Processor Environment . . . . . . . . . . . . Changing the maximum number of environments in an address space . . . . . . . . . . Using the data stack in different environments .

. 384 . 388 . 400 . 409 . 410

Chapter 11. Debug aids . . . . . . . 251

Interactive debugging of programs . . . . Interrupting execution and controlling tracing . . . 251 . 253

Chapter 15. Initialization and termination routines . . . . . . . . 417

Initialization routine IRXINIT . Termination routine IRXTERM . . . . . . . . . . . . 417 . 434

Chapter 12. TSO/E REXX programming services . . . . . . . 259

General considerations for calling TSO/E REXX routines . . . . . . . . . . . . . . . Exec processing routines IRXJCL and IRXEXEC External functions and subroutines, and function packages . . . . . . . . . . . . . . . Variable access routine IRXEXCOM . . . . . Maintain entries in the host command environment table IRXSUBCM . . . . . . . . . . . Trace and execution control routine IRXIC . . . Get result routine IRXRLT . . . . . . . . SAY instruction routine IRXSAY . . . . . . Halt condition routine IRXHLT . . . . . . . Text retrieval routine IRXTXT . . . . . . . LINESIZE function routine IRXLIN . . . . . 261 267 288 301 308 312 315 322 325 327 332

Chapter 16. Replaceable routines and exits . . . . . . . . . . . . . . . 437

Replaceable routines . . . Exec load routine . . . . Input/Output routine . . Host command environment Data stack routine . . . . Storage management routine User ID routine. . . . . Message identifier routine . REXX exit routines . . . . . . . . . . . . routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 441 453 463 466 471 474 476 477

Appendix A. Double-byte character set (DBCS) support . . . . . . . . . 481

General description . . . DBCS function handling . . DBCS processing functions . Function descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 485 490 490

Chapter 13. TSO/E REXX customizing services. . . . . . . . . . . . . . 337

Flow of REXX exec processing. . Overview of replaceable routines . Exit routines. . . . . . . . . . . . . . . . . . . . . . . . 338 . 342 . 343

Appendix B. IRXTERMA routine . . . 497

Entry specifications Parameters . . . Return specifications Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 498 498 499

Chapter 14. Language Processor Environments . . . . . . . . . . . 345

Overview of Language Processor Environments Using the environment block . . . . . . . . When environments are automatically initialized in TSO/E . . . . . . . . . . . . . . . When environments are automatically initialized in MVS . . . . . . . . . . . . . . . . Types of environments integrated and not integrated into TSO/E . . . . . . . . . . Characteristics of a Language Processor Environment . . . . . . . . . . . . . Flags and corresponding masks . . . . . . . Module name table . . . . . . . . . . . Host command environment table . . . . . . Function package table . . . . . . . . . . Values provided in the three default parameters modules . . . . . . . . . . . . . . . How IRXINIT determines what values to use for the environment . . . . . . . . . . . . Chains of environments and how environments are located . . . . . . . . . . . . . . . 345 348 349 351 352 353 358 363 368 371 374 377 379

Appendix C. Writing REXX Execs to perform MVS operator activities . . . 501

Activating a console session and issuing MVS commands . . . . . . . . . . . . . . Using the CONSOLE Host command environment Processing messages during a console session . . Using the CART to associate commands and their responses. . . . . . . . . . . . . . . 501 501 503 504

Appendix D. Additional variables that GETMSG sets . . . . . . . . . . . 507

Variables GETMSG sets for the entire message . Variables GETMSG sets for each line of message text . . . . . . . . . . . . . . . . . 507 . 511

Appendix E. REXX symbol and hexadecimal code cross-reference . . 513 Appendix F. Accessibility . . . . . . 519

iv

z/OS V1R13.0 TSO/E REXX Reference

Using assistive technologies . . . . . Keyboard navigation of the user interface . z/OS information . . . . . . . . .

. . .

. . .

. 519 . 519 . 519

Bibliography . . . . . . . . . . . . 527
TSO/E Publications . Related Publications . . . . . . . . . . . . . . . . . . . . 527 . 527

Notices . . . . . . . . . . . . . . 523
Programming interface information . Trademarks . . . . . . . . . . . . . . . . . . 525 . 525

Index . . . . . . . . . . . . . . . 529

Contents

vi

z/OS V1R13.0 TSO/E REXX Reference

Figures
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. Example of using the REXX exec identifier 7 Example JCL for TP profile for a Non-TSO/E REXX exec . . . . . . . . . . . . . 32 Example JCL for TP profile for a TSO/E REXX exec . . . . . . . . . . . . . . . 32 Parameters for LINK and ATTACH environments . . . . . . . . . . . . 36 Parameters for LINKMVS and ATTCHMVS environments . . . . . . . . . . . . 38 Parameters for LINKPGM and ATTCHPGM environments . . . . . . . . . . . . 43 Concept of a DO loop . . . . . . . . . 56 External routine resolution and execution 85 Conceptual overview of parsing . . . . . 181 Conceptual view of finding next pattern 182 Conceptual view of word parsing . . . . . 183 Example of closing data sets with EXECIO 225 Overview of parameter lists for TSO/E REXX routines . . . . . . . . . . . . . 263 Example of invoking an exec from a JCL EXEC statement using IRXJCL . . . . . . 268 Example PL/I version 2 program using IRXJCL . . . . . . . . . . . . . 270 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. Example of a function package directory Request block (SHVBLOCK) . . . . . . Overview of REXX Exec processing in any address space . . . . . . . . . . . Overview of parameters module . . . . . Function package table entries function package directories. . . . . . . . . . Three Language Processor Environments in a chain . . . . . . . . . . . . . . Separate chains on two different tasks One chain of environments for attached tasks Separate data stacks for each environment Sharing of the data stack between environments . . . . . . . . . . . Separate data stack and sharing of a data stack . . . . . . . . . . . . . . Creating a new data stack with the NEWSTACK command . . . . . . . . Extended parameter list parameter 8 Example exec (CHKPRT) to check start of printers . . . . . . . . . . . . . 299 304 338 354 374 379 380 381 412 413 414 415 424 506

Copyright IBM Corp. 1988, 2011

vii

viii

z/OS V1R13.0 TSO/E REXX Reference

Tables
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. Syntax examples . . . . . . . . . Sample APPC/MVS transaction programs in SYS1.SAMPLIB . . . . . . . . . . Examples of using LINKMVS, ATTCHMVS, and CALL to invoke a program . . . . . Function codes for GETMSG that replace the function call . . . . . . . . . . . Function codes for LISTDSI that replace the function call . . . . . . . . . . . Variables that LISTDSI sets . . . . . . LISTDSI reason codes . . . . . . . . Different ways prompting is affected Language codes for SETLANG function that replace the function call . . . . . . . SYSCPUS function codes . . . . . . . Summary of using instructions, functions, commands, and services . . . . . . . Common return codes for TSO/E REXX routines . . . . . . . . . . . . Parameter for calling the IRXJCL routine Return codes for IRXJCL routine . . . . Parameters for IRXEXEC routine . . . . Format of the exec block (EXECBLK) Format of the argument list . . . . . . Format of the header for the in-storage control block . . . . . . . . . . . Vector of records for the in-storage control block . . . . . . . . . . . . . Format of the evaluation block . . . . . IRXEXEC return codes . . . . . . . External function parameter list . . . . Format of the argument list three arguments . . . . . . . . . . . Format of the evaluation block . . . . . Return codes from function or subroutine code (in register 15) . . . . . . . . Format of the function package directory header . . . . . . . . . . . . . Format of entries in function package directory . . . . . . . . . . . . Parameters for IRXEXCOM . . . . . . Format of the SHVBLOCK . . . . . . Return codes from IRXEXCOM (in register 15) . . . . . . . . . . . . . . Parameters for IRXSUBCM . . . . . . Format of an entry in the host command environment table . . . . . . . . . Return codes for IRXSUBCM . . . . . Parameters for IRXIC . . . . . . . . Return codes for IRXIC . . . . . . . Parameters for IRXRLT . . . . . . . IRXRLT return codes for the GETBLOCK function . . . . . . . . . . . . IRXRLT return codes for the GETRLT and GETRLTE functions . . . . . . . . . xiv . 33 . 40 . 125 . 130 . 134 . 137 153 . 155 . 158 . 208 . 266 269 . 270 . 273 277 . 280 . 280 . . . . 283 285 287 290 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. 54. 55. 56. 57. 58. 59. 60. 61. 62. 63. 64. 65. 66. 67. 68. 69. 70. . . . . . 311 312 313 315 317 71. 72. 73. 74. 75. 76. IRXRLT return codes for the GETEVAL function . . . . . . . . . . . . . Parameters for IRXSAY . . . . . . . . Return codes for IRXSAY . . . . . . . Parameters for IRXHLT . . . . . . . . Return codes for IRXHLT . . . . . . . Parameters for IRXTXT . . . . . . . . Text unit and day returned - DAY function Text unit and month returned - MTHLONG function . . . . . . . . . . . . . Text unit and abbreviated month returned MTHSHORT function . . . . . . . . . Return codes for IRXTXT . . . . . . . Parameters for IRXLIN . . . . . . . . Return codes for IRXLIN. . . . . . . . Overview of replaceable routines . . . . . Format of the parameter block (PARMBLOCK) . . . . . . . . . . . Summary of each flag bit in the parameters module . . . . . . . . . . . . . Flag settings for NOMSGWTO and NOMSGIO . . . . . . . . . . . . Format of the module name table . . . . . Summary of fields in module name table and types of environments . . . . . . . . Format of the host command environment table header . . . . . . . . . . . . Format of entries in host command environment table . . . . . . . . . . Function package table header . . . . . . Values TSO/E provides in the three default parameters modules . . . . . . . . . Format of the environment block . . . . . Format of the parameter block (PARMBLOCK) . . . . . . . . . . . Format of the work block extension . . . . Format of REXX vector of external entry points . . . . . . . . . . . . . . Format of the environment table . . . . . Parameters for IRXINIT . . . . . . . . Parameters module and in-storage parameter list . . . . . . . . . . . . . . . Reason codes for IRXINIT processing IRXINIT return codes for finding an environment . . . . . . . . . . . . IRXINIT return codes for checking an environment . . . . . . . . . . . . IRXINIT return codes for initializing an environment . . . . . . . . . . . . Return codes for IRXTERM . . . . . . . Parameters for the exec load routine . . . . Format of the exec block . . . . . . . . Format of the in-storage control block header Vector of records for the in-storage control block . . . . . . . . . . . . . . 321 323 325 326 327 329 330 331 331 332 333 335 342 354 356 362 363 367 369 369 372 375 401 403 404 407 410 419 426 430 432 433 434 436 443 447 450 452

. 291 . 292 . 293 . 296 . 297 . 302 . 304 . 307 . 309

. 320 . 321

Copyright IBM Corp. 1988, 2011

ix

77. 78. 79. 80. 81. 82. 83. 84. 85. 86.

Return codes for the exec load replaceable routine . . . . . . . . . . . . . . Input parameters for the I/O replaceable routine . . . . . . . . . . . . . . Format of the data set information block Return codes for the I/O replaceable routine Parameters for a host command environment routine . . . . . . . . . . . . . . Return codes for the host command environment routine . . . . . . . . . Parameters for the data stack routine Return codes for the data stack replaceable routine . . . . . . . . . . . . . . Parameters for the storage management replaceable routine . . . . . . . . . . Return codes for the storage management replaceable routine . . . . . . . . . .

453 455 460 462 464 465 468 471

87. 88. 89. 90. 91. 92. 93. 94. 95. 96.

472 473

Parameters for the user ID replaceable routine Return codes for the user ID replaceable routine . . . . . . . . . . . . . . Return codes for the message identifier replaceable routine . . . . . . . . . . DBCS ranges. . . . . . . . . . . . Parameters for IRXTERMA . . . . . . . Return codes for IRXTERMA . . . . . . Variables GETMSG sets for an entire message Variables GETMSG sets for each line of message text . . . . . . . . . . . . REXX symbol and hexadecimal code - in hexadecimal sequence. . . . . . . . . REXX symbol and hexadecimal code - in logical sequence. . . . . . . . . . .

474 476 477 481 498 499 507 512 513 515

z/OS V1R13.0 TSO/E REXX Reference

About this document

Who should read this document
This document supports z/OS (5694A01). This document describes the z/OS TSO/E REXX Interpreter (hereafter referred to as the interpreter or language processor) and the REstructured eXtended eXecutor (called REXX) language. Together, the language processor and the REXX language are known as TSO/E REXX. This document is intended for experienced programmers, particularly those who have used a block-structured, high-level language (for example, PL/I, Algol, or Pascal). TSO/E REXX is the implementation of SAA REXX on the MVS system. Although TSO/E provides support for REXX, you can run REXX programs (called REXX execs) in any MVS address space. That is, you can run a REXX exec in TSO/E and non-TSO/E address spaces. Descriptions include the use and syntax of the language and explain how the language processor interprets the language as a program is running. The document also describes TSO/E external functions and REXX commands you can use in a REXX exec, programming services that let you interface with REXX and the language processor, and customizing services that let you customize REXX processing and how the language processor accesses and uses system services, such as storage and I/O requests.

How to use this document

This document is a reference rather than a tutorial. It assumes you are already familiar with REXX programming concepts. The material in this document is arranged in chapters: 1. Chapter 1, Introduction, on page 1 2. Chapter 2, REXX general concepts, on page 5 3. Chapter 3, Keyword instructions, on page 45 (in alphabetic order) 4. Chapter 4, Functions, on page 81 (in alphabetic order) 5. Chapter 5, Parsing, on page 169 (a method of dividing character strings, such as commands) 6. Chapter 6, Numbers and arithmetic, on page 185 7. Chapter 7, Conditions and condition traps, on page 195 8. Chapter 8, Using REXX in different address spaces, on page 201 9. Chapter 9, Reserved keywords, special variables, and command names, on page 211 10. Chapter 10, TSO/E REXX commands, on page 215 11. Chapter 11, Debug aids, on page 251 12. Chapter 12, TSO/E REXX programming services, on page 259 13. Chapter 13, TSO/E REXX customizing services, on page 337 14. Chapter 14, Language Processor Environments, on page 345 15. Chapter 15, Initialization and termination routines, on page 417 16. Chapter 16, Replaceable routines and exits, on page 437 There are several appendixes covering: v Appendix A, Double-byte character set (DBCS) support, on page 481 v Appendix B, IRXTERMA routine, on page 497
Copyright IBM Corp. 1988, 2011

xi

v Appendix C, Writing REXX Execs to perform MVS operator activities, on page 501 v Appendix D, Additional variables that GETMSG sets, on page 507 This introduction and Chapter 2, REXX general concepts provide general information about the REXX programming language. The two chapters provide an introduction to TSO/E REXX and describe the structure and syntax of the REXX language; the different types of clauses and instructions; the use of expressions, operators, assignments, and symbols; and issuing commands from a REXX program. Other chapters in the document provide reference information about the syntax of the keyword instructions and built-in functions in the REXX language, and the external functions TSO/E provides for REXX programming. The keyword instructions, built-in functions, and TSO/E external functions are described in Chapter 3, Keyword instructions, on page 45 and Chapter 4, Functions, on page 81. Other chapters provide information to help you use the different features of REXX and debug any problems in your REXX programs. These chapters include: v Chapter 5, Parsing, on page 169 v Chapter 6, Numbers and arithmetic, on page 185 v Chapter 7, Conditions and condition traps, on page 195 v Chapter 9, Reserved keywords, special variables, and command names, on page 211 v Chapter 11, Debug aids, on page 251 TSO/E provides several REXX commands you can use for REXX processing. The syntax of these commands is described in Chapter 10, TSO/E REXX commands, on page 215. Although TSO/E provides support for the REXX language, you can run REXX execs in any MVS address space (TSO/E and non-TSO/E). Chapter 8, Using REXX in different address spaces, on page 201 describes various aspects of using REXX in TSO/E and non-TSO/E address spaces and any restrictions. In addition to REXX language support, TSO/E provides programming services you can use to interface with REXX and the language processor, and customizing services that let you customize REXX processing and how the language processor accesses and uses system services, such as I/O and storage. The programming services are described in Chapter 12, TSO/E REXX programming services, on page 259. The customizing services are introduced in Chapter 13, TSO/E REXX customizing services, on page 337 and are described in more detail in the following chapters: v Chapter 14, Language Processor Environments, on page 345 v Chapter 15, Initialization and termination routines, on page 417 v Chapter 16, Replaceable routines and exits, on page 437 Throughout the document, examples that include data set names are provided. When an example includes a data set name that is enclosed in single quotation marks, the prefix is added to the data set name. In the examples, the user ID is the prefix.

xii

z/OS V1R13.0 TSO/E REXX Reference

How to read syntax diagrams

This section describes how to read syntax diagrams. It defines syntax diagram symbols, items that might be contained within the diagrams (keywords, variables, delimiters, operators, fragment references, operands) and provides syntax examples that contain these items. Syntax diagrams pictorially display the order and parts (options and arguments) that comprise a command statement. They are read from left to right and from top to bottom, following the main path of the horizontal line.

Symbols
The following symbols can be displayed in syntax diagrams: Symbol Definition Indicates the beginning of the syntax diagram. Indicates that the syntax diagram is continued to the next line. Indicates that the syntax is continued from the previous line. Indicates the end of the syntax diagram.

Syntax items
Syntax diagrams contain many different items. Syntax items include: v Keywords - a command name or any other literal information. v Variables - variables are italicized, appear in lowercase and represent the name of values you can supply. v Delimiters - delimiters indicate the start or end of keywords, variables, or operators. For example, a left parenthesis is a delimiter. v Operators - operators include add (+), subtract (-), multiply (*), divide (/), equal (=), and other mathematical operations that might need to be performed. v Fragment references - a part of a syntax diagram, separated from the diagram to show greater detail. v Separators - a separator separates keywords, variables or operators. For example, a comma (,) is a separator. Keywords, variables, and operators can be displayed as required, optional, or default. Fragments, separators, and delimiters can be displayed as required or optional. Item type Required Optional Default Definition Required items are displayed on the main path of the horizontal line. Optional items are displayed below the main path of the horizontal line. Default items are displayed above the main path of the horizontal line.

About this document

xiii

Syntax examples
The following table provides syntax examples.
Table 1. Syntax examples
Item Required item. Required items appear on the main path of the horizontal line. You must specify these items. Required choice. A required choice (two or more items) appears in a vertical stack on the main path of the horizontal line. You must choose one of the items in the stack. Optional item. Optional items appear below the main path of the horizontal line. Optional choice. A optional choice (two or more items) appear in a vertical stack below the main path of the horizontal line. You can choose one of the items in the stack. Default. Default items appear above the main path of the horizontal line. The remaining items (required or optional) appear on (required) or below (optional) the main path of the horizontal line. The following example displays a default with optional items. Variable. Variables appear in lowercase italics. They represent names or values. Repeatable item. An arrow returning to the left above the main path of the horizontal line indicates an item that can be repeated. An arrow returning to the left above a group of repeatable items indicates that one of the items can be selected, or a single item can be repeated. Fragment. The fragment symbol indicates that a labelled group is described below the main syntax diagram. Syntax is occasionally broken into fragments if the inclusion of the fragment would overly complicate the main syntax diagram. Syntax example

KEYWORD required_item

KEYWORD

required_choice1 required_choice2

KEYWORD optional_item

KEYWORD optional_choice1 optional_choice2

default_choice1 KEYWORD optional_choice2 optional_choice3

KEYWORD

variable

KEYWORD

repeatable_item

KEYWORD

fragment

fragment:
, required_choice1 ,default_choice ,required_choice2 ,optional_choice

Where to find more information

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.

xiv

z/OS V1R13.0 TSO/E REXX Reference

The z/OS Basic Skills Information Center

The z/OS Basic Skills Information Center is a Web-based information resource intended to help users learn the basic concepts of z/OS, the operating system that runs most of the IBM mainframe computers in use today. The Information Center is designed to introduce a new generation of Information Technology professionals to basic concepts and help them prepare for a career as a z/OS professional, such as a z/OS system programmer. Specifically, the z/OS Basic Skills Information Center is intended to achieve the following objectives: v Provide basic education and information about z/OS without charge v Shorten the time it takes for people to become productive on the mainframe v Make it easier for new people to learn z/OS. To access the z/OS Basic Skills Information Center, open your Web browser to the following Web site, which is available to all users (no login required): http://publib.boulder.ibm.com/infocenter/zos/basics/index.jsp

About this document

xv

xvi

z/OS V1R13.0 TSO/E REXX Reference

How to send your comments to IBM

We appreciate your input on this publication. Feel free to comment on the clarity, accuracy, and completeness of the information or give us any other feedback that you might have. Use one of the following methods to send us your comments: 1. Send an email to [email protected] 2. Visit the Contact z/OS web page at http://www.ibm.com/systems/z/os/zos/ webqs.html 3. Mail the comments to the following address: IBM Corporation Attention: MHVRCFS Reader Comments Department H6MA, Building 707 2455 South Road Poughkeepsie, NY 12601-5400 U.S.A. 4. Fax the comments to us as follows: From the United States and Canada: 1+845+432-9405 From all other countries: Your international access code +1+845+432-9405 Include the following information: v Your name and address v Your email address v Your telephone or fax number v The publication title and order number: z/OS V1R13.0 TSO/E REXX Reference SA22-7790-10 v The topic and page number related to your comment v The text of your comment. 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. IBM or any other organizations will only use the personal information that you supply to contact you about the issues that you submit.

If you have a technical problem

Do not use the feedback methods listed above. Instead, do one of the following: v Contact your IBM service representative v Call IBM technical support v Visit the IBM support portal at http://www.ibm.com/systems/z/support/

Copyright IBM Corp. 1988, 2011

xvii

xviii

z/OS V1R13.0 TSO/E REXX Reference

Summary of changes
This document contains terminology, maintenance, and editorial changes to improve consistency and retrievability. Technical changes or additions to the text and illustrations are indicated by a vertical line to the left of the change.

Changes made in z/OS Version 1 Release 13

This document contains information previously presented in z/OS TSO/E REXX Reference, SA22-7790-09, which supports z/OS TSO/E Version 1 Release 12. New information: v Added parameter 11 to Parameters for IRXINIT in Table 66 on page 419. v Added parameter 11 to Output parameters for IRXINIT in Output parameters on page 429. v Added parameter 11 to Changed information: v Updated descriptions of SYSUPDATED, SYSREFDATE, and SYSDSSMS in variables set by LISTDSI in Table 6 on page 134. v Updated argument strings directory and smsinfo for LISTDSI on page 130. v Updated parameters section of Initialization routine - IRXINIT in Parameters on page 418. v Updated Extended parameter list parameter 8 to include new parameter 11 in Figure 28 on page 424. v Updated reason code 21 in Reason codes for IRXINIT processing in Table 68 on page 430. v The description of the OUTTRAP function has been updated on page 146. v The contents of the example for SYSDSN have been updated on page 159. v The contents of compound symbol STEMS have been updated in Stems on page 23.

Changes made in z/OS Version 1 Release 12

This document contains information previously presented in z/OS TSO/E REXX Reference, SA22-7790-08, which supports z/OS TSO/E Version 1 Release 11. New information: v An example of using GETMSG has been added on page 129. v An example of using SYSVAR has been added on page 167. v A paragraph about passing a null string to a function and omitting an argument has been added in Argument list on page 291. Changed information: v The contents of the SYSREFDATE variable have been updated in Table 6 on page 134. v The first example of using MVSVAR has been updated on page 144. v The information of the lines operand has been updated on page 222.
Copyright IBM Corp. 1988, 2011

xix

v v v v v

The information of the OPEN operand has been updated on page 223. The information in the LISTDSI function was updated on page 133. Example 9 on page 228 of the EXECIO command has been updated. The contents of the OUTTRAP external function has been updated on page 146. The "Readers' Comments - We'd like to Hear from You" section at the back of this publication has been replaced with a new section How to send your comments to IBM on page xvii. The hardcopy mail-in form has been replaced with a page that provides information appropriate for submitting readers comments to IBM.

Changes made in z/OS Version 1 Release 11

This document contains information previously presented in z/OS TSO/E REXX Reference, SA22-7790-07, which supports z/OS TSO/E Version 1 Release 8. New information: v Two new LISTDSI variables, SYSEATTR and SYSEADSCB, have been added on page 137 for EAV R2 support. v New information has been added to the description of the STORAGE external function on page 157 for APAR OA25932. Changed information: v The title of a reference book in Commands to external environments on page 24 has been updated. v The description of Host commands and host command environments on page 26 has been updated. v The description of SYSRECFM in Table 6 on page 134 has been updated. v Table 6 on page 134 for LISTDSI has also been updated to remove obsolete information. v The descriptions of the following arguments for MVSVAR function have been updated: SYSDFP on page 141 and 142 SYSSMS on page 141 and 143

xx

z/OS V1R13.0 TSO/E REXX Reference

Chapter 1. Introduction
This introduction gives a brief overview of the Systems Application Architecture (SAA) solution.

What the SAA Solution Is

The SAA solution is based on a set of software interfaces, conventions, and protocols that provide a framework for designing and developing applications. The purpose of SAA REXX is to define a common subset of the language that can be used on several environments. TSO/E REXX is the implementation of SAA REXX on the z/OS system. If you plan on running your REXX programs on other environments, however, some restrictions can apply and you should review the publication SAA Common Programming Interface REXX Level 2 Reference. The SAA solution: v Defines a Common Programming Interface that you can use to develop consistent, integrated enterprise software v Defines Common Communications Support that you can use to connect applications, systems, networks, and devices v Defines a Common User Access architecture that you can use to achieve consistency in screen layout and user interaction techniques v Offers some applications and application development tools written by IBM

Supported environments
Several combinations of IBM hardware and software have been selected as SAA environments. These are environments in which IBM manages the availability of support for applicable SAA elements, and the conformance of those elements to SAA specifications. The SAA environments are the following: v z/OS Base system (TSO/E, APPC/MVS, batch) CICS TS IMS v z/VM v i5/OS v Operating System/2 (OS/2)

Common programming interface

The Common Programming Interface (CPI) provides languages and services that programmers can use to develop applications that take advantage of SAA consistency. The components of the interface currently fall into two general categories: v Languages Application Generator C COBOL FORTRAN
Copyright IBM Corp. 1988, 2011

Introduction
PL/I REXX (formerly called Procedures Language) RPG v Services Communications Database Dialog Language Environment Presentation PrintManager Query Repository Resource Recovery The CPI is not in itself a product or a piece of code. Butas a definitionit does establish and control how IBM products are being implemented, and it establishes a common base across the applicable SAA environments.

Benefits of using a compiler

The IBM Compiler for REXX/370 and the IBM Library for REXX/370 provide significant benefits for programmers during program development and for users when a program is run. The benefits are: v Improved performance v Reduced system load v Protection for source code and programs v Improved productivity and quality v Portability of compiled programs v SAA compliance checking

Improved performance
The performance improvements that you can expect when you run compiled REXX programs depend on the type of program. A program that performs large numbers of arithmetic operations of default precision shows the greatest improvement. A program that mainly issues commands to the host shows minimal improvement because REXX cannot decrease the time taken by the host to process the commands.

Reduced system load

Compiled REXX programs run faster than interpreted programs. Because a program has to be compiled only one time, system load is reduced and response time is improved when the program is run frequently. For example, a REXX program that performs many arithmetic operations might take 12 seconds to run interpreted. If the program is run 60 times, it uses about 12 minutes of processor time. The same program when compiled might run six times faster, using only about 2 minutes of processor time.

Protection for source code and programs

Your REXX programs and algorithms are assets that you want to protect. The Compiler produces object code, which helps you protect these assets by discouraging other users from making unauthorized changes to your programs. You can distribute your REXX programs in object code only.

z/OS V1R13.0 TSO/E REXX Reference

Introduction
Load modules can be further protected by using a security product, such as the Resource Access Control Facility (RACF).

Improved productivity and quality

The Compiler can produce source listings, cross-reference listings, and messages, which help you more easily develop and maintain your REXX programs. The Compiler identifies syntax errors in a program before you start testing it. You can then focus on correcting errors in logic during testing with the REXX interpreter.

Portability of compiled programs

A REXX program compiled under MVS/ESA can run under CMS. Similarly, a REXX program compiled under CMS can run under MVS/ESA.

SAA compliance checking

The Systems Application Architecture (SAA) definitions of software interfaces, conventions, and protocols provide a framework for designing and developing applications that are consistent within and across several operating systems. SAA REXX is a subset of the REXX language supported by the interpreter under TSO/E and can be used in this operating environment. To help you write programs for use in all SAA environments, the Compiler can optionally check for SAA compliance. With this option in effect, an attention message is issued for each non-SAA item found in a program. For more information, see IBM Compiler for REXX/370: Introducing the Next Step in REXX Programming.

Chapter 1. Introduction

z/OS V1R13.0 TSO/E REXX Reference

Chapter 2. REXX general concepts

The REstructured eXtended eXecutor (REXX) language is particularly suitable for: v Command procedures v Application front ends v User-defined macros (such as editor subcommands) v Prototyping v Personal computing. Individual users can write programs for their own needs. REXX is a general purpose programming language like PL/I. REXX has the usual structured-programming instructions IF, SELECT, DO WHILE, LEAVE, and so on and a number of useful built-in functions. The language imposes no restrictions on program format. There can be more than one clause on a line, or a single clause can occupy more than one line. Indentation is allowed. You can, therefore, code programs in a format that emphasizes their structure, making them easier to read. There is no limit to the length of the values of variables, as long as all variables fit into the storage available. Implementation maximum: No single request for storage can exceed the fixed limit of 16 MB. This limit applies to the size of a variable plus any control information. It also applies to buffers obtained to hold numeric results. The limit on the length of symbols (variable names) is 250 characters. You can use compound symbols, such as
NAME.Y.Z

(where Y and Z can be the names of variables or can be constant symbols), for constructing arrays and for other purposes. Issuing host commands from within a REXX program is an integral part of the REXX language. For example, in the TSO/E address space, you can use TSO/E commands in a REXX exec. The exec can also use ISPF commands and services if the exec runs in ISPF. In execs that run in both TSO/E and non-TSO/E address spaces, you can use the TSO/E REXX commands, such as MAKEBUF, DROPBUF, and NEWSTACK. You can also link to or attach programs. Host commands and host command environments on page 26 describes the different environments for using host services. TSO/E REXX execs can reside in a sequential data set or in a member of a partitioned data set (PDS). Partitioned data sets containing REXX execs can be allocated to either the system file SYSPROC (TSO/E address space only) or SYSEXEC. In the TSO/E address space, you can also use the TSO/E ALTLIB command to define alternate exec libraries for storing REXX execs. For more information about allocating exec data sets, see z/OS TSO/E REXX User's Guide. In TSO/E, you can call an exec explicitly using the EXEC command followed by the data set name and the exec keyword operand of the EXEC command. The exec keyword operand distinguishes the REXX exec from a TSO/E CLIST, which you also call using the EXEC command.
Copyright IBM Corp. 1988, 2011

REXX General Concepts

You can call an exec implicitly by entering the member name of the exec. You can call an exec implicitly only if the PDS in which the exec is stored has been allocated to a system file (SYSPROC or SYSEXEC). SYSEXEC is a system file whose data sets can contain REXX execs only. SYSPROC is a system file whose data sets can contain either CLISTs or REXX execs. If an exec is in a data set that is allocated to SYSPROC, the exec must start with a comment containing the characters REXX within the first line (line 1). This enables the TSO/E EXEC command to distinguish a REXX exec from a CLIST. For more information, see Structure and general syntax. SYSEXEC is the default load ddname from which REXX execs are loaded. If your installation plans to use REXX, store your REXX execs in data sets that are allocated to SYSEXEC, not SYSPROC. This makes them easier to maintain. For more information about the load ddname and searching SYSPROC or SYSEXEC, see Using SYSPROC and SYSEXEC for REXX execs on page 395. REXX programs are run by a language processor (interpreter). That is, the program is run line-by-line and word-by-word, without first being translated to another form (compiled). The advantage of this is you can fix the error and rerun the program faster than you can with a compiler. When an exec is loaded into storage, the load routine checks for sequence numbers in the data set. The routine removes the sequence numbers during the loading process. For information about how the load routine checks for sequence numbers, see Exec load routine on page 441. There is also a set of z/OS UNIX extensions to the TSO/E REXX language which enables REXX programs to access z/OS UNIX callable services. The z/OS UNIX extensions, called syscall commands, have names that correspond to the names of the callable services that they invokefor example, access, chmod, and chown. For more information about the z/OS UNIX extensions, see z/OS Using REXX and z/OS UNIX System Services.

Structure and general syntax

If you store a REXX exec in a data set that is allocated to SYSPROC, the exec must start with a comment and the comment must contain the characters REXX within the first line (line 1) of the exec. This is known as the REXX exec identifier and is required in order for the TSO/E EXEC command to distinguish REXX execs from TSO/E CLISTs, which are also stored in SYSPROC. The characters REXX must be in the first line (line 1) even if the comment spans multiple lines. In Figure 1 on page 7, example A on the left is correct. The program starts with a comment and the characters REXX are in the first line (line 1). Example B on the right is incorrect. The program starts with a comment. However, although the comment contains the characters REXX, they are not in the first line (line 1).

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

Example A (Correct) /* REXX program to check ... ... The program then ... */ ADDRESS CPICOMM ... ... ... EXIT Example B (Incorrect) /* This program checks ... ... in REXX and ... ADDRESS CPICOMM ... ... ... EXIT */

Figure 1. Example of using the REXX exec identifier

If the exec is in a data set that is allocated to a file containing REXX execs only, not CLISTs (for example, SYSEXEC), the comment including the characters REXX is not required. However, it is suggested that you start all REXX execs with a comment in the first column of the first line and include the characters REXX in the comment. In particular, this is suggested if you are writing REXX execs for use in other SAA environments. Including REXX in the first comment also helps users identify that the program is a REXX program and distinguishes a REXX exec from a TSO/E CLIST. For more information about how the EXEC command processor distinguishes REXX execs and CLISTs, see z/OS TSO/E Command Reference. A REXX program is built from a series of clauses that are composed of: v Zero or more blanks (which are ignored) v A sequence of tokens (see Tokens on page 9) v Zero or more blanks (again ignored) v A semicolon (;) delimiter that can be implied by line-end, certain keywords, or the colon (:) Conceptually, each clause is scanned from left to right before processing, and the tokens composing it are identified. Instruction keywords are recognized at this stage, comments are removed, and multiple blanks (except within literal strings) are converted to single blanks. Blanks adjacent to operator characters and special characters (see page 12) are also removed.

Characters
A character is a member of a defined set of elements that is used for the control or representation of data. You can usually enter a character with a single keystroke. The coded representation of a character is its representation in digital form. A character, the letter A, for example, differs from its coded representation or encoding. Various coded character sets (such as ASCII and EBCDIC) use different encoding for the letter A (decimal values 65 and 193, respectively). This book uses characters to convey meanings and not to imply a specific character code, except where otherwise stated. The exceptions are certain built-in functions that convert between characters and their representations. The functions C2D, C2X, D2C, X2C, and XRANGE have a dependence on the character set in use. A code page specifies the encoding for each character in a set. Appendix E, REXX symbol and hexadecimal code cross-reference, on page 513 shows the REXX symbols and their hexadecimal values as found in the U.S. Code Page (037). You should be aware that: v Some code pages do not contain all characters that REXX defines as valid (for example, , the logical NOT character). v Some characters that REXX defines as valid have different encoding in different code pages (for example, !, the exclamation point).
Chapter 2. REXX general concepts

REXX General Concepts

One result of these differences is that users in countries using code pages other than 037 might have to enter a character different from the one shown in this manual to accomplish the same result. Another result of character sensitivity in different code pages concerns operating environments. When REXX programs are transferred between different environments, such as PC REXX and TSO/E REXX, adjustments might need to be made as special characters might have different meanings in the different environments. For information about Double-Byte Character Set characters, see Appendix A, Double-byte character set (DBCS) support, on page 481.

Comments
A comment is a sequence of characters (on one or more lines) delimited by /* and */. Within these delimiters any characters are allowed. Comments can contain other comments, as long as each begins and ends with the necessary delimiters. They are called nested comments. Comments can be anywhere and can be of any length. They have no effect on the program, but they do act as separators. (Two tokens with only a comment in between are not treated as a single token.)
/* This is an example of a valid REXX comment */

Take special care when commenting out lines of code containing /* or */ as part of a literal string. Consider the following program segment:
01 02 03 04 parse pull input if substr(input,1,5) = /*123 then call process dept = substr(input,32,5)

To comment out lines 2 and 3, the following change would be incorrect:

01 parse pull input 02 /* if substr(input,1,5) = /*123 03 then call process 04 */ dept = substr(input,32,5)

This is incorrect because the language processor would interpret the /* that is part of the literal string /*123 as the start of a nested comment. It would not process the rest of the program because it would be looking for a matching comment end (*/). You can avoid this type of problem by using concatenation for literal strings containing /* or */; line 2 would be:
if substr(input,1,5) = / || *123

You could comment out lines 2 and 3 correctly as follows:

01 parse pull input 02 /* if substr(input,1,5) = / || *123 03 then call process 04 */ dept = substr(input,32,5)

For information about Double-Byte Character Set characters, see Appendix A, Double-byte character set (DBCS) support, on page 481 and the OPTIONS instruction on page 64.

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

Tokens
A token is the unit of low-level syntax from which clauses are built. Programs written in REXX are composed of tokens. They are separated by blanks or comments or by the nature of the tokens themselves. The classes of tokens are: Literal Strings: A literal string is a sequence including any characters and delimited by the single quotation mark (') or the double quotation mark ("). Use two consecutive double quotation marks ("") to represent a " character within a string delimited by double quotation marks. Similarly, use two consecutive single quotation marks () to represent a character within a string delimited by single quotation marks. A literal string is a constant and its contents are never modified when it is processed. A literal string with no characters (that is, a string of length 0) is called a null string. These are valid strings:
Fred "Dont Panic!" You shouldnt

/* Same as "You shouldnt" */ /* The null string */

Note that a string followed immediately by a ( is considered to be the name of a function. If followed immediately by the symbol X or x, it is considered to be a hexadecimal string. If followed immediately by the symbol B or b, it is considered to be a binary string. Descriptions of these forms follow. Implementation maximum: A literal string can contain up to 250 characters. (But note that the length of computed results is limited only by the amount of storage available.) Hexadecimal Strings: A hexadecimal string is a literal string, expressed using a hexadecimal notation of its encoding. It is any sequence of zero or more hexadecimal digits (09, af, AF), grouped in pairs. A single leading 0 is assumed, if necessary, at the front of the string to make an even number of hexadecimal digits. The groups of digits are optionally separated by one or more blanks, and the whole sequence is delimited by single or double quotation marks, and immediately followed by the symbol X or x. (Neither x nor X can be part of a longer symbol.) The blanks, which can be present only at byte boundaries (and not at the beginning or end of the string), are to aid readability. The language processor ignores them. A hexadecimal string is a literal string formed by packing the hexadecimal digits given. Packing the hexadecimal digits removes blanks and converts each pair of hexadecimal digits into its equivalent character, for example: 'C1'X to A. Hexadecimal strings let you include characters in a program even if you cannot directly enter the characters themselves. These are valid hexadecimal strings:
ABCDx "1d ec f8"X "1 d8"x

A hexadecimal string is not a representation of a number. Rather, it is an escape mechanism that lets a user describe a character in
Chapter 2. REXX general concepts

REXX General Concepts

terms of its encoding (and, therefore, is machine-dependent). In EBCDIC, '40'X is the encoding for a blank. In every case, a string of the form '.....'x is simply an alternative to a straightforward string. In EBCDIC 'C1'x and 'A' are identical, as are '40'x and a blank, and must be treated identically. Implementation maximum: The packed length of a hexadecimal string (the string with blanks removed) cannot exceed 250 bytes. Binary Strings: A binary string is a literal string, expressed using a binary representation of its encoding. It is any sequence of zero or more binary digits (0 or 1) in groups of 8 (bytes) or 4 (nibbles). The first group can have fewer than four digits; in this case, up to three 0 digits are assumed to the left of the first digit, making a total of four digits. The groups of digits are optionally separated by one or more blanks, and the whole sequence is delimited by matching single or double quotation marks and immediately followed by the symbol b or B. (Neither b nor B can be part of a longer symbol.) The blanks, which can be present only at byte or nibble boundaries (and not at the beginning or end of the string), are to aid readability. The language processor ignores them. A binary string is a literal string formed by packing the binary digits given. If the number of binary digits is not a multiple of eight, leading zeros are added on the left to make a multiple of eight before packing. Binary strings allow you to specify characters explicitly, bit by bit. These are valid binary strings:
11110000b "101 1101"b 1b 10000 10101010b b /* /* /* /* /* == == == == == f0x */ 5dx */ 00000001b and 01x */ 0001 0000 1010 1010b */ */

A note on binary string interpretation in TSO/E: Binary string support was introduced with TSO/E Version 2 Release 4. With this release, and all following ones, a string in the form of stringB causes string to be interpreted as binary string. Prior to TSO/E 2.4, the two parts of the expression stringB, string and B, were concatenated after the value for the variable B was determined. For example, if B=variable_value were concatenated with string, then stringB would be interpreted as stringvariable_value. If this error is detected in REXX execs written before TSO/E 2.4, use the concatenation operator ( || ) to eliminate the problem. For example, code stringB as:
string|Lor.B

Symbols:

Symbols are groups of characters, selected from the: v English alphabetic characters (AZ and az1) v Numeric characters (09) v Characters @ # $ . !2 ? and underscore. v Double-Byte Character Set (DBCS) characters (X'41'X'FE')ETMODE must be in effect for these characters to be valid in symbols.

1. Note that some code pages do not include lowercase English characters az. 2. The encoding of the exclamation point character depends on the code page in use.

10

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

Any lowercase alphabetic character in a symbol is translated to uppercase (that is, lowercase az to uppercase AZ) before use. These are valid symbols:
Fred Albert.Hall WHERE?

If a symbol does not begin with a digit or a period, you can use it as a variable and can assign it a value. If you have not assigned it a value, its value is the characters of the symbol itself, translated to uppercase (that is, lowercase az to uppercase AZ). Symbols that begin with a number or a period are constant symbols and cannot be assigned a value. One other form of symbol is allowed to support the representation of numbers in exponential format. The symbol starts with a digit (09) or a period, and it can end with the sequence E or e, followed immediately by an optional sign (- or +), followed immediately by one or more digits (which cannot be followed by any other symbol characters). The sign in this context is part of the symbol and is not an operator. These are valid numbers in exponential notation:
17.3E-12 .03e+9

Implementation maximum: A symbol can consist of up to 250 characters. (But note that its value, if it is a variable, is limited only by the amount of storage available.) Numbers: These are character strings consisting of one or more decimal digits, with an optional prefix of a plus or minus sign, and optionally including a single period (.) that represents a decimal point. A number can also have a power of 10 suffixed in conventional exponential notation: an E (uppercase or lowercase), followed optionally by a plus or minus sign, then followed by one or more decimal digits defining the power of 10. Whenever a character string is used as a number, rounding may occur to a precision specified by the NUMERIC DIGITS instruction (default nine digits). See pages 185-193 for a full definition of numbers. Numbers can have leading blanks (before and after the sign, if any) and can have trailing blanks. Blanks might not be embedded among the digits of a number or in the exponential part. Note that a symbol (see preceding) or a literal string can be a number. A number cannot be the name of a variable. These are valid numbers:
12 -17.9 127.0650 73e+128 + 7.9E5

A whole number is a number that has a zero (or no) decimal part and that the language processor would not usually express in exponential notation. That is, it has no more digits before the decimal point than the current setting of NUMERIC DIGITS (the default is 9).

Chapter 2. REXX general concepts

11

REXX General Concepts

Implementation maximum: The exponent of a number expressed in exponential notation can have up to nine digits. Operator Characters: The characters: + - \ / % * | & = > < and the sequences >= <= \> \< \= >< <> == \== // && || ** > < = == >> << >>= \<< << \>> >> <<= /= /== indicate operations (see page 14). A few of these are also used in parsing templates, and the equal sign is also used to indicate assignment. Blanks adjacent to operator characters are removed. Therefore, the following are identical in meaning:
345>=123 345 >=123 345 >= 123 345 > = 123

Some of these characters might not be available in all character sets, and, if this is the case, appropriate translations can be used. In particular, the vertical bar (|) or character is often shown as a split vertical bar (). Throughout the language, the not character, , is synonymous with the backslash (\). You can use the two characters interchangeably according to availability and personal preference. Special Characters: The following characters, together with the individual characters from the operators, have special significance when found outside of literal strings:
, ; : ) (

These characters constitute the set of special characters. They all act as token delimiters, and blanks adjacent to any of these are removed. There is an exception: a blank adjacent to the outside of a parenthesis is deleted only if it is also adjacent to another special character (unless the character is a parenthesis and the blank is outside it, too). For example, the language processor does not remove the blank in A (Z). This is a concatenation that is not equivalent to A(Z), a function call. The language processor does remove the blanks in (A) + (Z) because this is equivalent to (A)+(Z). The following example shows how a clause is composed of tokens.
REPEAT A + 3;

This is composed of six tokensa literal string (REPEAT), a blank operator, a symbol (A, which can have a value), an operator (+), a second symbol (3, which is a number and a symbol), and the clause delimiter (;). The blanks between the A and the + and between the + and the 3 are removed. However, one of the blanks between the REPEAT and the A remains as an operator. Thus, this clause is treated as though written:
REPEAT A+3;

Implied semicolons
The last element in a clause is the semicolon delimiter. The language processor implies the semicolon: at a line-end, after certain keywords, and after a colon if it

12

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

follows a single symbol. This means that you need to include semicolons only when there is more than one clause on a line or to end an instruction whose last character is a comma. A line-end usually marks the end of a clause and, thus, REXX implies a semicolon at most end of lines. However, there are the following exceptions: v The line ends in the middle of a string. v The line ends in the middle of a comment. The clause continues on to the next line. v The last token was the continuation character (a comma) and the line does not end in the middle of a comment. (Note that a comment is not a token.) REXX automatically implies semicolons after colons (when following a single symbol, a label) and after certain keywords when they are in the correct context. The keywords that have this effect are: ELSE, OTHERWISE, and THEN. These special cases reduce typographical errors significantly. Restriction: The two characters forming the comment delimiters, /* and */, must not be split by a line-end (that is, / and * should not appear on different lines) because they could not then be recognized correctly; an implied semicolon would be added. The two consecutive characters forming a literal quotation mark within a string are also subject to this line-end ruling.

Continuations
A clause can be continued onto the next line by using the comma, which is referred to as the continuation character. The comma is functionally replaced by a blank, and, thus, no semicolon is implied. One or more comments can follow the continuation character before the end of the line. The continuation character cannot be used in the middle of a string or it will be processed as part of the string itself. The same situation holds true for comments. Note that the comma remains in execution traces. The following example shows how to use the continuation character to continue a clause.
say You can use a comma, to continue this clause.

This displays:
You can use a comma to continue this clause.

A clause can also be continued onto the next line by using nulls. That is, the clause can be a literal string that contains blank characters and spans multiple lines until the ending quote is encountered. A literal string can contain up to 250 characters.

Expressions and operators

Expressions in REXX are a general mechanism for combining one or more pieces of data in various ways to produce a result, usually different from the original data. Appendix E, REXX symbol and hexadecimal code cross-reference, on page 513 shows the REXX symbols and their hexadecimal values as found in the U.S. Code Page (037).

Chapter 2. REXX general concepts

13

REXX General Concepts

Expressions
Expressions consist of one or more terms (literal strings, symbols, function calls, or subexpressions) interspersed with zero or more operators that denote operations to be carried out on terms. A subexpression is a term in an expression bracketed within a left and a right parenthesis. Terms include: v Literal Strings (delimited by quotation marks), which are constants v Symbols (no quotation marks), which are translated to uppercase. A symbol that does not begin with a digit or a period may be the name of a variable; in this case the value of that variable is used. Otherwise a symbol is treated as a constant string. A symbol can also be compound. v Function calls (see page 81), which are of the form:
, symbol( literal_string( ) expression

Evaluation of an expression is left to right, modified by parentheses and by operator precedence in the usual algebraic manner (see Parentheses and operator precedence on page 17). Expressions are wholly evaluated, unless an error occurs during evaluation. All data is in the form of typeless character strings (typeless because it is notas in some other languagesof a particular declared type, such as Binary, Hexadecimal, Array, and so forth). Consequently, the result of evaluating any expression is itself a character string. Terms and results (except arithmetic and logical expressions) can be the null string (a string of length 0). Note that REXX imposes no restriction on the maximum length of results. However, there is usually some practical limitation dependent upon the amount of storage available to the language processor.

Operators
An operator is a representation of an operation, such as addition, to be carried out on one or two terms. The following pages describe how each operator (except for the prefix operators) acts on two terms, which can be symbols, strings, function calls, intermediate results, or subexpressions. Each prefix operator acts on the term or subexpression that follows it. Blanks (and comments) adjacent to operator characters have no effect on the operator; thus, operators constructed from more than one character can have embedded blanks and comments. In addition, one or more blanks, where they occur in expressions but are not adjacent to another operator, also act as an operator. There are four types of operators: v Concatenation v Arithmetic v Comparison v Logical

String concatenation
The concatenation operators combine two strings to form one string by appending the second string to the right-hand end of the first string. The concatenation might occur with or without an intervening blank. The concatenation operators are: (blank) Concatenate terms with one blank in between

14

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

|| (abuttal) Concatenate without an intervening blank Concatenate without an intervening blank

You can force concatenation without a blank by using the || operator. The abuttal operator is assumed between two terms that are not separated by another operator. This can occur when two terms are syntactically distinct, such as a literal string and a symbol, or when they are separated only by a comment. Examples: An example of syntactically distinct terms is: if Fred has the value 37.4, then Fred'%' evaluates to 37.4%. If the variable PETER has the value 1, then (Fred)(Peter) evaluates to 37.41. In EBCDIC, the two adjoining strings, one hexadecimal and one literal,
c1 c2xCDE

evaluate to ABCDE. In the case of:

Fred/* The NOT operator precedes Peter. */Peter

there is no abuttal operator implied, and the expression is not valid. However,
(Fred)/* The NOT operator precedes Peter. */(Peter)

results in an abuttal, and evaluates to 37.40.

Arithmetic
You can combine character strings that are valid numbers (see page 11) using the arithmetic operators: + * / % // ** Prefix Prefix + Add Subtract Multiply Divide Integer divide (divide and return the integer part of the result) Remainder (divide and return the remaindernot modulo, because the result may be negative) Power (raise a number to a whole-number power) Same as the subtraction: 0 - number Same as the addition: 0 + number

See Chapter 6, Numbers and arithmetic, on page 185 for details about precision, the format of valid numbers, and the operation rules for arithmetic. Note that if an arithmetic result is shown in exponential notation, it is likely that rounding has occurred.

Comparison
The comparison operators compare two terms and return the value 1 if the result of the comparison is true, or 0 otherwise.
Chapter 2. REXX general concepts

15

REXX General Concepts

The strict comparison operators all have one of the characters defining the operator doubled. The ==, \==, /==, and == operators test for an exact match between two strings. The two strings must be identical (character by character) and of the same length to be considered strictly equal. Similarly, the strict comparison operators such as >> or << carry out a simple character-by-character comparison, with no padding of either of the strings being compared. The comparison of the two strings is from left to right. If one string is shorter than and is a leading substring of another, then it is smaller than (less than) the other. The strict comparison operators also do not attempt to perform a numeric comparison on the two operands. For all the other comparison operators, if both terms involved are numeric, a numeric comparison (in which leading zeros are ignored, and so forthsee Numeric comparisons on page 190) is effected. Otherwise, both terms are treated as character strings (leading and trailing blanks are ignored, and then the shorter string is padded with blanks on the right). Character comparison and strict comparison operations are both case-sensitive, and for both the exact collating order may depend on the character set used for the implementation. For example, in an EBCDIC environment, lowercase alphabetics precede uppercase, and the digits 09 are higher than all alphabetics. In an ASCII environment, the digits are lower than the alphabetics, and lowercase alphabetics are higher than uppercase alphabetics. The comparison operators and operations are: = \=, =, /= > < >< <> >= \<, < <= \>, > == True if the terms are equal (numerically or when padded, and so forth) True if the terms are not equal (inverse of =) Greater than Less than Greater than or less than (same as not equal) Greater than or less than (same as not equal) Greater than or equal to Not less than Less than or equal to Not greater than True if terms are strictly equal (identical)

\==, ==, /== True if the terms are NOT strictly equal (inverse of ==) >> << >>= \<<, << <<= \>>, >> Strictly greater than Strictly less than Strictly greater than or equal to Strictly NOT less than Strictly less than or equal to Strictly NOT greater than

Guideline: Throughout the language, the not character, , is synonymous with the backslash (\). You can use the two characters interchangeably, according to

16

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

availability and personal preference. The backslash can appear in the following operators: \ (prefix not), \=, \==, \<, \>, \<<, and \>>.

Logical (boolean)
A character string is taken to have the value false if it is 0, and true if it is 1. The logical operators take one or two such values (values other than 0 or 1 are not allowed) and return 0 or 1 as appropriate: & AND Returns 1 if both terms are true. | Inclusive OR Returns 1 if either term is true. && Exclusive OR Returns 1 if either (but not both) is true. Prefix \, Logical NOT Negates; 1 becomes 0, and 0 becomes 1

Parentheses and operator precedence

Expression evaluation is from left to right; parentheses and operator precedence modify this: v When parentheses are encountered (other than those that identify function calls) the entire subexpression between the parentheses is evaluated immediately when the term is required. v When the sequence:
term1 operator1 term2 operator2 term3

is encountered, and operator2 has a higher precedence than operator1, the subexpression (term2 operator2 term3) is evaluated first. The same rule is applied repeatedly as necessary. Note, however, that individual terms are evaluated from left to right in the expression (that is, as soon as they are encountered). The precedence rules affect only the order of operations. For example, * (multiply) has a higher priority than + (add), so 3+2*5 evaluates to 13 (rather than the 25 that would result if strict left to right evaluation occurred). To force the addition to occur before the multiplication, you could rewrite the expression as (3+2)*5. Adding the parentheses makes the first three tokens a subexpression. Similarly, the expression -3**2 evaluates to 9 (instead of -9) because the prefix minus operator has a higher priority than the power operator. The order of precedence of the operators is (highest at the top): +-\ ** * / % // +(prefix operators) (power) (multiply and divide) (add and subtract)

(blank) || (abuttal) (concatenation with or without blank) =>< == >> <<

Chapter 2. REXX general concepts

(comparison operators)

17

REXX General Concepts

\= = >< <> \> > \< < \== == \>> >> \<< << >= >>= <= <<= /= /== & | && Examples: Suppose the symbol A is a variable whose value is 3, DAY is a variable whose value is Monday, and other variables are uninitialized. Then:
A+5 A-4*2 A/2 0.5**2 (A+1)>7 = == == (A+1)*3=12 077>11 077 >> 11 abc >> ab abc << abd ab << abd Today is Day If it is day Substr(Day,2,3) !xxx! 000000 >> 0E0000 -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> -> 8 -5 1.5 0.25 0 /* that is, 1 /* that is, 0 /* that is, 1 /* that is, 1 /* that is, 1 /* that is, 0 /* that is, 1 /* that is, 1 /* that is, 1 /* that is, TODAY IS Monday If it is Monday ond /* Substr is a !XXX! 1 /* that is,

(and) (or, exclusive or)

False True False True True True False True True True

*/ */ */ */ */ */ */ */ */ */

function */ True */

Note: The last example would give a different answer if the > operator had been used rather than >>. Because '0E0000' is a valid number in exponential notation, a numeric comparison is done; thus '0E0000' and '000000' evaluate as equal. The REXX order of precedence usually causes no difficulty because it is the same as in conventional algebra and other computer languages. There are two differences from common notations: v The prefix minus operator always has a higher priority than the power operator. v Power operators (like other operators) are evaluated left-to-right. For example:
-3**2 == 9 /* not -9 */ -(2+1)**2 == 9 /* not -9 */ 2**2**3 == 64 /* not 256 */

18

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

Clauses and instructions

Clauses can be subdivided into the following types:

Null clauses
A clause consisting only of blanks or comments or both is a null clause. It is completely ignored (except that if it includes a comment it is traced, if appropriate). Tip: A null clause is not an instruction; for example, putting an extra semicolon after the THEN or ELSE in an IF instruction is not equivalent to using a dummy instruction (as it would be in PL/I). The NOP instruction is provided for this purpose.

Labels
A clause that consists of a single symbol followed by a colon is a label. The colon in this context implies a semicolon (clause separator), so no semicolon is required. Labels identify the targets of CALL instructions, SIGNAL instructions, and internal function calls. More than one label may precede any instruction. Labels are treated as null clauses and can be traced selectively to aid debugging. Any number of successive clauses can be labels. This permits multiple labels before other clauses. Duplicate labels are permitted, but control passes only to the first of any duplicates in a program. The duplicate labels occurring later can be traced but cannot be used as a target of a CALL, SIGNAL, or function invocation. Appendix E, REXX symbol and hexadecimal code cross-reference, on page 513 shows the REXX symbols and their hexadecimal values as found in the U.S. Code Page (037). You can use DBCS characters in labels. See Appendix A, Double-byte character set (DBCS) support, on page 481 for more information.

Instructions
An instruction consists of one or more clauses describing some course of action for the language processor to take. Instructions can be: assignments, keyword instructions, or commands.

Assignments
A single clause of the form symbol=expression is an instruction known as an assignment. An assignment gives a variable a (new) value. See Assignments and symbols on page 20.

Keyword instructions
A keyword instruction is one or more clauses, the first of which starts with a keyword that identifies the instruction. Keyword instructions control the external interfaces, the flow of control, and so forth. Some keyword instructions can include nested instructions. In the following example, the DO construct (DO, the group of instructions that follow it, and its associated END keyword) is considered a single keyword instruction.

Chapter 2. REXX general concepts

19

REXX General Concepts

DO instruction instruction instruction END

A subkeyword is a keyword that is reserved within the context of some particular instruction, for example, the symbols TO and WHILE in the DO instruction.

Commands
A command is a clause consisting of only an expression. The expression is evaluated and the result is passed as a command string to some external environment.

Assignments and symbols

A variable is an object whose value can change during the running of a REXX program. The process of changing the value of a variable is called assigning a new value to it. The value of a variable is a single character string, of any length, that might contain any characters. You can assign a new value to a variable with the ARG, PARSE, or PULL instructions, the VALUE built-in function, or the Variable Access Routine (IRXEXCOM), but the most common way of changing the value of a variable is the assignment instruction itself. Any clause of the form: symbol=expression; is taken to be an assignment. The result of expression becomes the new value of the variable named by the symbol to the left of the equal sign. On TSO/E, if you omit expression, the variable is set to the null string. However, it is suggested that you explicitly set a variable to the null string: symbol=. Appendix E, REXX symbol and hexadecimal code cross-reference, on page 513 shows the REXX symbols and their hexadecimal values as found in the U.S. Code Page (037). Variable names can contain DBCS characters. For information about DBCS characters, see Appendix A, Double-byte character set (DBCS) support, on page 481. Example:
/* Next line gives FRED the value "Frederic" */ Fred=Frederic

The symbol naming the variable cannot begin with a digit (09) or a period. (Without this restriction on the first character of a variable name, you could redefine a number; for example 3=4; would give a variable called 3 the value 4.) You can use a symbol in an expression even if you have not assigned it a value, because a symbol has a defined value at all times. A variable you have not assigned a value is uninitialized. Its value is the characters of the symbol itself, translated to uppercase (that is, lowercase az to uppercase AZ). However, if it is a compound symbol (described under Compound symbols on page 21), its value is the derived name of the symbol.

20

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

Example:
/* If Freda has not yet been assigned a value, /* then next line gives FRED the value "FREDA" Fred=Freda */ */

The meaning of a symbol in REXX varies according to its context. As a term in an expression (rather than a keyword of some kind, for example), a symbol belongs to one of four groups: constant symbols, simple symbols, compound symbols, and stems. Constant symbols cannot be assigned new values. You can use simple symbols for variables where the name corresponds to a single value. You can use compound symbols and stems for more complex collections of variables, such as arrays and lists.

Constant symbols
A constant symbol starts with a digit (09) or a period. You cannot change the value of a constant symbol. It is simply the string consisting of the characters of the symbol (that is, with any lowercase alphabetic characters translated to uppercase). These are constant symbols:
77 827.53 .12345 12e5 3D 17E-3

/* Same as 12E5 */

Appendix E, REXX symbol and hexadecimal code cross-reference, on page 513 shows the REXX symbols and their hexadecimal values as found in the U.S. Code Page (037).

Simple symbols
A simple symbol does not contain any periods and does not start with a digit (09). By default, its value is the characters of the symbol (that is, translated to uppercase). If the symbol has been assigned a value, it names a variable and its value is the value of that variable. These are simple symbols:
FRED Whatagoodidea? ?12 /* Same as WHATAGOODIDEA? */

Appendix E, REXX symbol and hexadecimal code cross-reference, on page 513 shows the REXX symbols and their hexadecimal values as found in the U.S. Code Page (037).

Compound symbols
A compound symbol permits the substitution of variables within its name when you refer to it. A compound symbol contains at least one period and at least two other characters. It cannot start with a digit or a period, and if there is only one period in the compound symbol, it cannot be the last character.

Chapter 2. REXX general concepts

21

REXX General Concepts

The name begins with a stem (that part of the symbol up to and including the first period). This is followed by a tail, parts of the name (delimited by periods) that are constant symbols, simple symbols, or null. The derived name of a compound symbol is the stem of the symbol, in uppercase, followed by the tail, in which all simple symbols have been replaced with their values. A tail itself can be comprised of the characters AZ, az, 09, and @ # $ . ! ? and underscore. The value of a tail can be any character string, including the null string and strings containing blanks. For example:
taila=* ( tailb= stem.taila=99 stem.tailb=stem.taila say stem.tailb /* Displays: 99 */ /* But the following instruction would cause an error */ /* say stem.* ( */

You cannot use constant symbols with embedded signs (for example, 12.3E+5) after a stem; in this case, the whole symbol would not be a valid symbol. These are compound symbols:
FRED.3 Array.I.J AMESSY..One.2.

Before the symbol is used (that is, at the time of reference), the language processor substitutes the values of any simple symbols in the tail (I, J, and One in the examples), thus generating a new, derived name. This derived name is then used just like a simple symbol. That is, its value is by default the derived name, or (if it has been used as the target of an assignment) its value is the value of the variable named by the derived name. The substitution into the symbol that takes place permits arbitrary indexing (subscripting) of collections of variables that have a common stem. Note that the values substituted can contain any characters (including periods and blanks). Substitution is done only one time. To summarize: the derived name of a compound variable that is referred to by the symbol
s0.s1.s2. --- .sn

is given by
d0.v1.v2. --- .vn

where d0 is the uppercase form of the symbol s0, and v1 to vn are the values of the constant or simple symbols s1 through sn. Any of the symbols s1-sn can be null. The values v1-vn can also be null and can contain any characters (in particular, lowercase characters are not translated to uppercase, blanks are not removed, and periods have no special significance). Some examples follow in the form of a small extract from a REXX program:
a=3 /* assigns 3 z=4 /* c=Fred /* a.z=Fred /* a.fred=5 /* a.c=Bill /* c.c=a.fred /* y.a.z=Annie /* to the variable A 4 to Z Fred to C Fred to A.4 5 to A.FRED Bill to A.Fred 5 to C.Fred Annie to Y.3.4 */ */ */ */ */ */ */ */

22

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

say a z c a.a a.z a.c c.a a.fred y.a.4 /* displays the string: */ /* "3 4 Fred A.3 Fred Bill C.3 5 Annie" */

You can use compound symbols to set up arrays and lists of variables in which the subscript is not necessarily numeric, thus offering great scope for the creative programmer. A useful application is to set up an array in which the subscripts are taken from the value of one or more variables, effecting a form of associative memory (content addressable). Implementation maximum: The length of a variable name, before and after substitution, cannot exceed 250 characters. Appendix E, REXX symbol and hexadecimal code cross-reference, on page 513 shows the REXX symbols and their hexadecimal values as found in the U.S. Code Page (037).

Stems
A stem is a symbol that contains just one period, which is the last character. It cannot start with a digit or a period. These are stems:
FRED. A.

By default, the value of a stem is the string consisting of the characters of its symbol (that is, translated to uppercase). If the symbol has been assigned a value, it names a variable and its value is the value of that variable. Further, when a stem is used as the target of an assignment, all possible compound variables whose names begin with that stem receive the new value, whether they previously had a value or not. Following the assignment, a reference to any compound symbol with that stem returns the new value until another value is assigned to the stem or or that stem or individual variable is dropped. For example: | | | | |
hole. = "empty" hole.9 = "full" hole.rat = "full" rat = "cheese" drop hole.rat say hole.1 hole.mouse hole.9 hole.rat /* says "empty empty full HOLE.cheese" */

Thus, you can give a whole collection of variables the same value. For example:
total. = 0 do forever say "Enter an amount and a name:" pull amount name if datatype(amount)=CHAR then leave total.name = total.name + amount end

You can always obtain the value that has been assigned to the whole collection of variables by using the stem. However, this is not the same as using a compound variable whose derived name is the same as the stem. For example:
Chapter 2. REXX general concepts

23

REXX General Concepts

total. = 0 null = "" total.null = total.null + 5 say total. total.null

/* says "0 5" */

You can manipulate collections of variables, referred to by their stem, with the DROP and PROCEDURE instructions. DROP FRED. drops all variables with that stem (see page 57), and PROCEDURE EXPOSE FRED. exposes all possible variables with that stem (see page 68). Notes: 1. When the ARG, PARSE, or PULL instruction or the VALUE built-in function or the Variable Access Routine (IRXEXCOM) changes a variable, the effect is identical with an assignment. Anywhere a value can be assigned, using a stem sets an entire collection of variables. 2. Because an expression can include the operator =, and an instruction can consist purely of an expression (see Commands to external environments), a possible ambiguity is resolved by the following rule: any clause that starts with a symbol and whose second token is (or starts with) an equal sign (=) is an assignment, rather than an expression (or a keyword instruction). This is not a restriction, because you can ensure the clause is processed as a command in several ways, such as by putting a null string before the first name, or by enclosing the first part of the expression in parentheses. Similarly, if you unintentionally use a REXX keyword as the variable name in an assignment, this should not cause confusion. For example, the clause:
Address=10 Downing Street;

is an assignment, not an ADDRESS instruction. 3. You can use the SYMBOL function (see page 113) to test whether a symbol has been assigned a value. In addition, you can set SIGNAL ON NOVALUE to trap the use of any uninitialized variables (except when they are tails in compound variablessee page 196). Appendix E, REXX symbol and hexadecimal code cross-reference, on page 513 shows the REXX symbols and their hexadecimal values as found in the U.S. Code Page (037).

Commands to external environments

Issuing commands to the surrounding environment is an integral part of REXX.

Environment
The system under which REXX programs run is assumed to include at least one host command environment for processing commands. An environment is selected by default on entry to a REXX program. In TSO/E REXX, the environment for processing host commands is known as the host command environment. TSO/E provides different environments for TSO/E and non-TSO/E address spaces. You can change the environment by using the ADDRESS instruction. You can find out the name of the current environment by using the ADDRESS built-in function. The underlying operating system defines environments external to the REXX program. The host command environment selected depends on the caller. For example, if you call a REXX program from a TSO/E address space, the default host command environment that TSO/E provides for processing host commands is TSO. If you

24

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

call an exec from a non-TSO/E address space, the default host command environment that TSO/E provides is MVS. TSO/E provides several host command environments for a TSO/E address space (TSO/E and ISPF) and for non-TSO/E address spaces. Host commands and host command environments on page 26 explains the different types of host commands you can use in a REXX exec and the different host command environments TSO/E provides for the processing of host commands. The environments are provided in the host command environment table, which specifies the host command environment name and the routine that is called to handle the command processing for that host command environment. You can provide your own host command environment and corresponding routine and define them to the host command environment table. Host command environment table on page 368 describes the table in more detail. Changing the default values for initializing an environment on page 384 describes how to change the defaults TSO/E provides in order to define your own host command environments. You can also use the IRXSUBCM routine to maintain entries in the host command environment table (see page 309).

Commands
To send a command to the currently addressed host command environment, use a clause of the form:
expression;

The expression is evaluated, resulting in a character string (which can be the null string), which is then prepared as appropriate and submitted to the host command environment. Any part of the expression not to be evaluated should be enclosed in quotation marks. The environment then processes the command, which might have side-effects. It eventually returns control to the language processor, after setting a return code. A return code is a string, typically a number, that returns some information about the command that has been processed. A return code usually indicates if a command was successful or not but can also represent other information. The language processor places this return code in the REXX special variable RC. See Special variables on page 199. In addition to setting a return code, the underlying system might also indicate to the language processor if an error or failure occurred. An error is a condition raised by a command for which a program that uses that command would usually be expected to be prepared. (For example, a locate command to an editing system might report requested string not found as an error.) A failure is a condition raised by a command for which a program that uses that command would not usually be expected to recover (for example, a command that is not executable or cannot be found). Errors and failures in commands can affect REXX processing if a condition trap for ERROR or FAILURE is ON (see Chapter 7, Conditions and condition traps, on page 195). They might also cause the command to be traced if TRACE E or TRACE F is set. TRACE Normal is the same as TRACE F and is the defaultsee page 76. Here is an example of submitting a command. If the host command environment were TSO/E, the sequence:

Chapter 2. REXX general concepts

25

REXX General Concepts

mydata = "PROGA.LOAD" "FREE DATASET("mydata")"

would result in the string FREE DATASET(PROGA.LOAD) being submitted to TSO/E. Of course, the simpler expression:
"FREE DATASET(PROGA.LOAD)"

would have the same effect in this case. Recommendation: Whenever you use a host command in a REXX program, enclose the command in double quotation marks. See z/OS TSO/E REXX User's Guide for a description of using single and double quotation marks in commands. On return, the return code from the FREE command is placed in the REXX special variable RC. The return code in RC is 0 if the FREE command processor successfully freed the data set or 12 if it did not. Whenever a host command is processed, the return code from the command is placed in the REXX special variable RC. Remember that the expression is evaluated before it is passed to the environment. Enclose in quotation marks any part of the expression that is not to be evaluated.

Host commands and host command environments

You can issue host commands from a REXX program. When the language processor processes a clause that it does not recognize as a REXX instruction or an assignment instruction, the language processor considers the clause to be a host command and routes the command to the current host command environment. The host command environment processes the command and then returns control to the language processor. For example, in REXX processing, a host command can be: v A TSO/E command processor, such as ALLOCATE, FREE, or EXEC v A TSO/E REXX command, such as NEWSTACK or QBUF v A program that you link to or attach v An MVS system or subsystem command that you invoke during an extended MCS console session v An ISPF command or service v An SAA CPI Communications call or APPC/MVS call If a REXX exec contains
FRED var1 var2

the language processor considers the clause to be a command and passes the clause to the current host command environment for processing. The host command environment processes the command, sets a return code in the REXX special variable RC, and returns control to the language processor. The return code set in RC is the return code from the host command you specified. For example, the value in RC may be the return code from a TSO/E command processor, an ISPF command or service, or a program you attached. The return code may also be a -3, which indicates that the host command environment could not locate the specified host command (TSO/E command, CLIST, exec, attached or linked routine, ISPF command or service, and so on). A return code of -3 is always returned if you issue a host command in an exec and the host command environment cannot locate the command. A return code of -3 is also returned if a

26

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

TSO/E host command is in the AUTHCMD list of the IKJTSOxx parmlib member and the host command is found in a non-APF authorized library. This is different from what happens in a CLIST or line-mode TSO/E when a command from the AUTHCMD list is found in a non-APF authorized library. In those cases, the command is called and runs unauthorized. However, in a REXX exec if a command from the AUTHCMD list is found in a non-APF authorized library, it fails. Tip: If you issue a host command from a REXX exec that is running in an authorized or isolated environment, a -3 return code may be returned. If a system abend occurs during a host command, the REXX special variable RC is set to the negative of the decimal value of the abend code. If a user abend occurs during a host command, the REXX special variable RC is set to the decimal value of the abend code. If no abend occurs during a host command, the REXX special variable RC is set to the decimal value of the return code from the command. Certain conditions may be raised depending on the value of the special variable RC: v If the RC value is negative, the FAILURE condition is raised. v If the RC value is positive, the ERROR condition is raised. v If the RC value is zero, neither the ERROR nor FAILURE conditions are raised. See Chapter 7, Conditions and condition traps for more information. Recommendation: If you issue a host command in a REXX exec, you should enclose the entire command in double quotation marks, for example:
"routine-name var1 var2"

TSO/E provides several host command environments that process different types of host commands. The following topics describe the different host command environments TSO/E provides for non-TSO/E address spaces and for the TSO/E address space (TSO/E and ISPF).

The TSO host command environment

The TSO host command environment is available only to REXX execs that run in the TSO/E address space. Use the TSO host command environment to invoke TSO/E commands and services. You can also invoke all of the TSO/E REXX commands, such as MAKEBUF and NEWSTACK, and invoke other REXX execs and CLISTs. When you invoke a REXX exec in the TSO/E address space, the default initial host command environment is TSO. Note that the value that can be set in the REXX special variable RC for the TSO environment is a signed 24-bit number in the range -8,388,608 to +8,388,607.

The CONSOLE host command environment

The CONSOLE host command environment is available only to REXX execs that run in the TSO/E address space. Use the CONSOLE environment to invoke MVS system and subsystem commands during an extended MCS console session. To use the CONSOLE environment, you must have CONSOLE command authority. Before you can use the CONSOLE environment, you must first activate an extended MCS console session using the TSO/E CONSOLE command. After the console session is active, use ADDRESS CONSOLE to issue MVS system and subsystem commands. The CONSOLE environment lets you issue MVS commands
Chapter 2. REXX general concepts

27

REXX General Concepts

from a REXX exec without having to repeatedly issue the CONSOLE command with the SYSCMD keyword. For more information about the CONSOLE environment and related TSO/E services, see Appendix C, Writing REXX Execs to perform MVS operator activities, on page 501. If you use ADDRESS CONSOLE and issue an MVS system or subsystem command before activating a console session, the CONSOLE environment will not be able to locate the command you issued. In this case, the REXX special variable RC is set to -3 and the FAILURE condition is raised. The -3 return code indicates that the host command environment could not locate the command you issued. In this case, the command could not be found because a console session is not active. Note that the value that can be set in the REXX special variable RC for the CONSOLE environment is a signed 31-bit number in the range -2,147,483,648 to +2,147,483,647.

The ISPEXEC and ISREDIT host command environments

The ISPEXEC and ISREDIT host command environments are available only to REXX execs that run in ISPF. Use the environments to invoke ISPF commands and services, and ISPF edit macros. When you invoke a REXX exec from ISPF, the default initial host command environment is TSO. You can use the ADDRESS instruction to use an ISPF service. For example, to use the ISPF SELECT service, use the following instruction:
ADDRESS ISPEXEC SELECT service

The ISREDIT environment lets you issue ISPF edit macros. To use ISREDIT, you must be in an edit session. Note that the value that can be set in the REXX special variable RC for the ISPEXEC and ISREDIT environments is a signed 24-bit number in the range -8,388,608 to +8,388,607.

The CPICOMM, LU62, and APPCMVS host command environments

The CPICOMM, LU62, and APPCMVS host command environments are available to REXX execs that run in any MVS address space. The CPICOMM environment lets you use the SAA common programming interface (CPI) Communications calls. The LU62 environment lets you use the APPC/MVS calls that are based on the SNA LU 6.2 architecture. The APPCMVS environment allows APPC transaction programs to invoke APPC/MVS server facilities callable services and callable services related to the testing of transaction programs (TPs). Using these environments, you can write APPC/MVS transaction programs (TPs) in the REXX programming language. Using CPICOMM, you can write transaction programs (TPs) in REXX that can be used in different SAA environments. The CPICOMM environment supports the starter set and advanced function set of the following SAA CPI Communications calls. For more information about each call and its parameters, see SAA Common Programming Interface Communications Reference. v CMACCP (Accept_Conversation) v CMALLC (Allocate) v CMCFM (Confirm) v CMCFMD (Confirmed)

28

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

v v v v v v v v v v v v v v v v v v v v v v v v v v v CMDEAL (Deallocate) CMECS (Extract_Conversation_State) CMECT (Extract_Conversation_Type) CMEMN (Extract_Mode_Name) CMEPLN (Extract_Partner_LU_Name) CMESL (Extract_Sync_Level) CMFLUS (Flush) CMINIT (Initialize_Conversation) CMPTR (Prepare_To_Receive) CMRCV (Receive) CMRTS (Request_To_Send) CMSCT (Set_Conversation_Type) CMSDT (Set_Deallocate_Type) CMSED (Set_Error_Direction) CMSEND (Send_Data) CMSERR (Send_Error) CMSF (Set_Fill) CMSLD (Set_Log_Data) CMSMN (Set_Mode_Name) CMSPLN (Set_Partner_LU_Name) CMSPTR (Set_Prepare_To_Receive_Type) CMSRC (Set_Return_Control) CMSRT (Set_Receive_Type) CMSSL (Set_Sync_Level) CMSST (Set_Send_Type) CMSTPN (Set_TP_Name) CMTRTS (Test_Request_To_Send_Received)

The LU62 environment supports the following APPC/MVS calls. These calls are based on the SNA LU 6.2 architecture and are referred to as APPC/MVS calls in this book. For more information about the calls and their parameters, see z/OS MVS Programming: Writing Transaction Programs for APPC/MVS. v ATBALLC (Allocate) v ATBCFM (Confirm) v ATBCFMD (Confirmed) v ATBDEAL (Deallocate) v ATBFLUS (Flush) v ATBGETA (Get_Attributes) v ATBGETC (Get_Conversation) v ATBGETP (Get_TP_Properties) v ATBGETT (Get_Type) v ATBPTR (Prepare_to_Receive) v ATBRCVI (Receive_Immediate) v ATBRCVW (Receive_and_Wait) v ATBRTS (Request_to_Send) v ATBSEND (Send_Data) v ATBSERR (Send_Error) The LU62 host command environment supports the following callable services that existed before MVS/SP 4.3.0, but have been updated: v ATBALC2 (Allocate) v ATBGTA2 (Get_Attributes) With TSO/E APAR OA08990, the REXX LU62 host command environment supports the following updated APPC version 3, 4, 5, and 6 callable services. (The APPC version is that which is returned by ATBVERS, the APPC_Version_Service.)
Chapter 2. REXX general concepts

29

REXX General Concepts

Version 3: v ATBEES3 (Error_Extract) Version 4: v ATBGTP4 (Get_TP_Properties) v ATBSSO4 (Set_Syncpt_Options) Version 5: v ATBALC5 (Allocate) v ATBSTO5 (Set_TimeOut_Value) Version 6: v ATBALC6 (Allocate) v ATBSTO6 (Set_TimeOut_Value) v ATBGTA6 (Get_Attributes) For more information about the new LU62 service calls and their parameters, see z/OS MVS Programming: Writing Transaction Programs for APPC/MVS. Note: In order to use the new version 6 services, the user must have the PTF for APAR OA08990 installed and must be running z/OS V1R7 or later. The APPCMVS host command environment supports the following advanced callable services: v ATBRFA2 (Register_for_Allocates) v ATBRAL2 (Receive_Allocate) v ATBRJC2 (Reject_Conversation) v ATBSTE2 (Set_Event_Notification) v ATBGTE2 (Get_Event) v ATBQAQ2 (Query_Allocate_Queue) v ATBSAQ2 (Set_Allocate_Queue_Attributes) v ATBSCA2 (Set_Conversation_Accounting_Information) v ATBURA2 (Unregister_for_Allocates) v ATBPOR2 (Post_on_Receipt) The APPCMVS host command environment supports the following advanced callable services: v ATBRFA2 (Register_for_Allocates) v ATBRAL2 (Receive_Allocate) v ATBTER1 (Register_Test) v ATBTEA1 (Accept_Test) v ATBTEU1 (Unregister_Test) v ATBCUC1 (Cleanup_TP (Unauthorized)) v ATBVERS (APPC_Version_Service) Restriction: If you use the APPC/MVS calls, be aware that TSO/E REXX does not support data spaces. In addition, the buffer length limit for ATBRCVI, ATBRCVW, and ATBSEND is 16 MB. You can request callable service asynchronous processing on services that provide it. This is specified on the parameter. To use either an SAA CPI Communications call or an APPC/MVS call, specify the name of the call followed by variable names for each of the parameters. Separate each variable name by one or more blanks. For example:
ADDRESS LU62 ATBCFMD conversation_ID notify_type return_code

30

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

You must enclose the entire call in single or double quotation marks. You must also pass a variable name for each parameter. Do not pass actual values for the parameters. By enclosing the call in quotation marks, the language processor does not evaluate any variables and simply passes the expression to the host command environment for processing. The CPICOMM or LU62 environment itself evaluates the variables and performs variable substitution. If you do not specify a variable for each parameter and enclose the call in quotation marks, you may have problems with variable substitution and receive unexpected results. As an example, the SAA CPI Communications call, CMINIT, has three parameters; conversation_id, sym_dest_name, and return_code. When you use CMINIT, specify three variables for the three parameters; for example, convid for the conversation_id parameter, symdest for the sym_dest_name parameter, and retcode for the return_code parameter. Before you use CMINIT, you can assign the value you want to use for the sym_dest_name parameter, such as CPINY17.
/* . REXX transaction program ... */ . . symdest = CPINY17 . . . ADDRESS CPICOMM "CMINIT convid symdest retcode" IF . retcode = CM_OK THEN . . ADDRESS CPICOMM "CMALLC convid retcode" IF . retcode = CM_OK THEN . . EXIT

In the example, you assign the variable symdest the value CPINY17. On the CMINIT call, you use the variable names for the parameters. The CPICOMM host command environment evaluates the variables and uses the value CPINY17 for the sym_dest_name parameter. When the call returns control to the language processor, the output variables whose names were specified on the call contain the returned values. In this example, the variable convid contains the value for the conversation_id parameter and retcode contains the value for the return_code parameter. On return, the REXX special variable RC is also set to one of the following: v A zero if the service is invoked successfully. v A -3 if the parameter list was incorrect or if the APPC/MVS call could not be found. Note that the value that can be set in the REXX special variable RC for the CPICOMM and LU62 environments is a signed 31-bit number in the range -2,147,483,648 to +2,147,483,647.

Pseudonym files
Both the SAA CPI Communications calls and the APPC/MVS calls use pseudonyms for actual calls, characteristics, variables, and so on. For example, the return_code parameter for SAA CPI Communications calls can be the pseudonym CM_OK. The integer value for the CM_OK pseudonym is 0. APPC/MVS provides pseudonym files in the header file data set SYS1.SIEAHDR.H that define the pseudonyms and corresponding integer values. The pseudonym files APPC/MVS provides are: v ATBPBREX for APPC/MVS calls
Chapter 2. REXX general concepts

31

REXX General Concepts

v ATBCMREX for SAA CPI Communications calls. v ATBCTREX for APPCMVS host command environment pseudonyms. The sample pseudonym files contain REXX assignment statements that simplify writing transaction programs (TPs) in REXX. You can copy either the entire pseudonym file or parts of the file into your transaction program. Alternatively, you can use EXECIO to read each assignment statement from the pseudonym file and then interpret the line to cause the pseudonym to be defined to your REXX Program.

Transaction program profiles

If you write a transaction program in REXX and you plan to run the program as an inbound TP, you have to create a transaction program (TP) profile for the exec. The profile is required for inbound or attached TPs. The transaction program (TP) profile consists of a set of JCL statements that you store in a TP profile data set on MVS. The following figures provide example JCL for transaction program (TP) profiles. For more information about TP profiles, see z/OS MVS Planning: APPC/MVS Management. Figure 2 shows example JCL for an exec that you write for non-TSO/E address spaces.

//JOBNAME //STEPNAME //SYSPRINT //SYSEXEC //SYSTSIN //SYSTSPRT

JOB EXEC DD DD DD DD

parameters PGM=IRXJCL,PARM=exec_member_name argument SYSOUT=A DSN=exec_data_set_name,DISP=SHR DSN=input_data_set_name,DISP=SHR DSN=output_data_set_name,DISP=SHR

Figure 2. Example JCL for TP profile for a Non-TSO/E REXX exec

Figure 3 shows example JCL for an exec that you write for a TSO/E address space.

//JOBNAME //STEPNAME //SYSPRINT //SYSEXEC //SYSTSPRT //SYSTSIN

JOB EXEC DD DD DD DD

parameters PGM=IKJEFT01,PARM=exec_member_name argument SYSOUT=A DSN=exec_data_set_name,DISP=SHR DSN=output_data_set_name,DISP=SHR DUMMY

Figure 3. Example JCL for TP profile for a TSO/E REXX exec

Sample Transaction programs

APPC/MVS provides sample transaction programs (TPs) written in REXX and related information in SYS1.SAMPLIB. Table 2 on page 33 lists the member names of the samples and their descriptions. For information about using the sample TPs, see the comments at the beginning of the outbound transaction program (TPs) for the particular sample. For the SAA CPI Communications sample, the outbound TP is in member ATBCAO. For the APPC/MVS sample (based on the SNA LU 6.2 architecture), the outbound TP is in member ATBLAO.

32

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

Table 2. Sample APPC/MVS transaction programs in SYS1.SAMPLIB Samplib member Description ATBCAJ ATBCAP ATBCAS ATBLAJ ATBLAP ATBCAI ATBCAO ATBCKRC ATBLAI ATBLAO JCL to run REXX SAA CPI Communications sample program A JCL to add a TP profile for REXX SAA CPI Communications sample program A JCL to add side information for REXX SAA CPI Communications sample program A JCL to run REXX APPC/MVS sample program A JCL to add a TP profile for REXX APPC/MVS sample program A REXX SAA CPI Communications sample program A; inbound REXX transaction program (TP) REXX SAA CPI Communications sample program A; outbound REXX transaction program (TP) REXX subroutine to check return codes; used by sample REXX transaction programs (TPs) REXX APPC/MVS sample program A; inbound REXX transaction program (TP) REXX APPC/MVS sample program A; outbound REXX transaction program (TP)

The MVS host command environment

The MVS host command environment is available in any MVS address space. When you run a REXX exec in a non-TSO/E address space, the default initial host command environment is MVS. Note: When you invoke an exec in a TSO/E address space, TSO is the initial host command environment. In ADDRESS MVS, you can use a subset of the TSO/E REXX commands as follows: v DELSTACK v NEWSTACK v QSTACK v QBUF v QELEM v EXECIO v MAKEBUF v DROPBUF v SUBCOM v TS v TE Chapter 10, TSO/E REXX commands, on page 215 describes the commands. In ADDRESS MVS, you can also invoke another REXX exec using the ADDRESS MVS EXEC command. Note that this command is not the same as the TSO/E EXEC command processor. You can use one of the following instructions to invoke an exec. The instructions in the following example assume the current host command environment is not MVS.

Chapter 2. REXX general concepts

33

REXX General Concepts

ADDRESS MVS "execname p1 p2 ..." ADDRESS MVS "EX execname p1 p2 ..." ADDRESS MVS "EXEC execname p1 p2 ..."

If you use the ADDRESS MVS EXEC command to invoke another REXX exec, the system searches only the DD from which the calling exec was loaded. If the exec is not found in that DD, the search for the exec ends and the REXX special variable RC is set to -3. Note that the value that can be set in the REXX special variable RC for the MVS environment is a signed 31-bit number in the range -2,147,483,648 to +2,147,483,647. To invoke an unauthorized program from an exec, use one of the link or attach host command environments that are described in Host command environments for linking to and attaching programs. All of the services that are available in ADDRESS MVS are also available in ADDRESS TSO. For example, if you run a REXX exec in TSO/E, you can use the TSO/E REXX commands (for example, MAKEBUF, NEWSTACK, QSTACK) in ADDRESS TSO.

Host command environments for linking to and attaching programs

TSO/E provides the LINK, LINKMVS, and LINKPGM host command environments that let you link to unauthorized programs on the same task level. TSO/E also provides the ATTACH, ATTCHMVS, and ATTCHPGM host command environments that let you attach unauthorized programs on a different task level. These link and attach environments are available to REXX execs that run in any address space. To link to or attach a program, specify the name of the program followed by any parameters you want to pass to the program. For example:
ADDRESS LINKMVS "program p1 p2 ... pn" ADDRESS ATTCHPGM "program p1 p2 ... pn"

Enclose the name of the program and any parameters in either single or double quotation marks. The host command environment routines for the environments use the following search order to locate the program: v Job pack area v ISPLLIB. If the user issued LIBDEF ISPLLIB ..., the system searches the new alternate library defined by LIBDEF followed by the ISPLLIB library. v Task library and all preceding task libraries v Step library. If there is no step library, the job library is searched, if one exists. v Link pack area (LPA) v Link library.

34

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

The differences between the environments are the format of the parameter list that the program receives, the capability of passing multiple parameters, variable substitution for the parameters, and the ability of the invoked program to update the parameters. v For the LINK and ATTACH environments, you can specify only a single character string that gets passed to the program. The LINK and ATTACH environments do not evaluate the character string and do not perform variable substitution. The environments simply pass the string to the invoked program. The program can use the character string it receives. However, the program cannot return an updated string to the exec. v For the LINKMVS, LINKPGM, ATTCHMVS, and ATTCHPGM environments, you can pass multiple parameters to the program. The environments evaluate the parameters you specify and perform variable substitution. That is, the environment determines the value of each variable. When the environment invokes the program, the environment passes the value of each variable to the program. The program can update the parameters it receives and return the updated values to the exec. After you link to or attach the program, the host command environment sets a return code in the REXX special variable RC. For all of the link and attach environments, the return code may be: v A -3 if the host command environment could not locate the program you specified v The return code that the linked or attached program set in register 15 Additionally, for the LINKMVS, ATTCHMVS, LINKPGM, and ATTCHPGM environments, the return code set in RC may be -2, which indicates that processing of the variables was not successful. Variable processing may have been unsuccessful because the host command environment could not: v Perform variable substitution before linking to or attaching the program v Update the variables after the program completed For LINKMVS and ATTCHMVS, you can also receive an RC value of -2 if the length of the value of the variable was larger than the length that could be specified in the signed halfword length field in the parameter list. The maximum value of the halfword length field is 32,767. Note that the value that can be set in the RC special variable for the LINK, LINKMVS, and LINKPGM environments is a signed 31-bit number in the range -2,147,483,648 to +2,147,483,647. The value that can be set in RC for the ATTACH, ATTCHMVS, and ATTCHPGM environments is a signed 24-bit number in the range -8,388,608 to +8,388,607. The following topics describe how to link to and attach programs using the different host command environments.

The LINK and ATTACH host command environments

For the LINK and ATTACH environments, you can pass only a single character string to the program. Enclose the name of the program and the character string in either single or double quotation marks to prevent the language processor from performing variable substitution. For example:
ADDRESS ATTACH TESTPGMA varid

Chapter 2. REXX general concepts

35

REXX General Concepts

If you want to pass the value of a variable, then it should not be enclosed in quotation marks. In this case the interpreter will perform the variable substitution before passing the string to the host command environment. The following excerpt from a REXX program would have identical results as the previous example:
parm_value = varid ADDRESS ATTACH TESTPGMA parm_value

The host command environment routines for LINK and ATTACH do not evaluate the character string you specify. The routine simply passes the character string to the program that it links to or attaches. The program can use the character string it receives. However, the program cannot return an updated string to the exec. Figure 4 shows how the LINK or ATTACH host command environment routine passes a character string to a program. Register 0 points to the ENVBLOCK under which the REXX exec issuing the ADDRESS LINK or ADDRESS ATTACH is running. Register 1 points to a list that consists of two addresses. The first address points to a fullword that contains the address of the character string. The second address points to a fullword that contains the length of the character string. The high- order bit of the last address in the parameter list is set to 1 to indicate the end of the parameter list.

R0

ENVBLOCK

R1

Parameter 1 * Parameter 2 * high order bit on

Address of character string Length of character string

Figure 4. Parameters for LINK and ATTACH environments

For example, suppose you use the following instruction:

ADDRESS LINK TESMODA numberid payid

When the LINK host command environment routine links to the TESMODA program, the address of the character string points to the string:
numberid payid

The length of the character string is 14. In this example, if numberid and payid were REXX variables, no substitution is performed by the LINK host command environment. You can use the LINK or ATTACH environments and not specify a character string. For example:
ADDRESS ATTACH "proga"

In this case, the address of the character string is 0 and the length of the string is 0.

36

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

The LINKMVS and ATTCHMVS host command environments

For the LINKMVS and ATTCHMVS environments, you can pass multiple parameters to the program. Specify the name of the program followed by variable names for each of the parameters. Separate each variable name by one or more blanks. For example:
ADDRESS ATTCHMVS TESTPGMA var1 var2 var3

For the parameters, specify variable names instead of the actual values. Enclose the name of the program and the variable names in either single or double quotation marks. By using the quotation marks, the language processor does not evaluate any variables. The language processor simply passes the expression to the host command environment for processing. The LINKMVS or ATTCHMVS environment itself evaluates the variables and performs variable substitution. If you do not use a variable for each parameter and enclose the expression in quotation marks, you may have problems with variable substitution and receive unexpected results. After the LINKMVS or ATTCHMVS environment routine evaluates the value of each variable, it builds a parameter list pointing to the values. The routine then links to or attaches the program and passes the parameter list to the program. Figure 5 on page 38 shows how the LINKMVS or ATTCHMVS host command environment routine passes the parameters to the program. Register 0 points to the ENVBLOCK under which the REXX exec issuing the ADDRESS LINKMVS or ADDRESS ATTCHMVS is running. Register 1 contains the address of a parameter list, which consists of a list of addresses. Each address in the parameter list points to a parameter. The high-order bit of the last address in the parameter list is set to 1 to indicate the end of the parameter list. Each parameter consists of a halfword length field followed by the parameter, which is the value of the variable you specified on the LINKMVS or ATTCHMVS instruction. The halfword length field contains the length of the parameter, which is the length of the value of the variable. The maximum value of the halfword length field is 32,767.

Chapter 2. REXX general concepts

37

REXX General Concepts

R0

ENVBLOCK

R1

Parameter List Parameter 1 Parameter 2 . . . . . * Parameter n * high order bit on

Figure 5. Parameters for LINKMVS and ATTCHMVS environments

length 1 length 2

Parameter 1 Parameter 2

length n

Parameter n

As an example, suppose you want to attach the RTNWORK program and you want to pass two parameters; an order number (43176) and a code (CDETT76). When you use the ADDRESS ATTCHMVS instruction, specify variable names for the two parameters; for example, ordernum for the order number, 43176, and codenum for the code, CDETT76. Before you use ADDRESS ATTCHMVS, assign the values to the variable names.
. . . ordernum = 43176 codenum = "CDETT76" . . . ADDRESS ATTCHMVS "RTNWORK ordernum codenum" . . . EXIT

In the example, you assign to the variable ordernum the value 43176 and you assign to the variable codenum the value CDETT76. On the ADDRESS ATTCHMVS instruction, you use the variable names for the two parameters. The ATTCHMVS host command environment evaluates the variables and passes the values of the variables to the RTNWORK program. In the parameter list, the length field for the first parameter (variable ordernum) is 5, followed by the character string 43176. The length field for the second parameter (variable codenum) is 7, followed by the character string CDETT76. On entry to the linked or attached program, the halfword length fields contain the actual length of the parameters. The linked or attached program can update the values of the parameters before it completes processing. The value that the program returns in the halfword length field determines the type of processing that LINKMVS or ATTCHMVS performs. When the LINKMVS or ATTCHMVS environment routine regains control, it determines whether to update the values of the REXX variables before returning to the REXX exec. To determine whether to update the value of a variable for a

38

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

specific parameter, the LINKMVS or ATTCHMVS environment checks the value in the halfword length field. Depending on the value in the length field, LINKMVS or ATTCHMVS updates the variable, does not update the variable, or sets the variable to the null string. v If the value in the length field is less than 0, the LINKMVS or ATTCHMVS environment does not update the variable for that parameter. v If the value in the length field is 0, the LINKMVS or ATTCHMVS environment sets the variable for that parameter to the null string. v If the value in the length field is greater than 0, the LINKMVS or ATTCHMVS environment updates the variable for that parameter with the value the program returned in the parameter list. If the length field is a positive number, LINKMVS or ATTCHMVS simply updates the variable using the length in the length field. If the length specified in the length field is less than 500, TSO/E provides a storage area of 500 bytes regardless of the length of the value of the variable. For example, if the length of the value of the variable on entry to the program were 8 bytes, the halfword length field would contain the value 8. However, there are 500 bytes of storage available for the parameter itself. This allows the program to increase the length of the variable without having to obtain storage. If the invoked program changes the length of the variable, it must also update the length field. If the original length of the value is greater than 500 bytes, there is no additional space. For example, suppose you specify a variable whose value has a length of 620 bytes. The invoked program can return a value with a maximum length of 620 bytes. TSO/E does not provide an additional buffer area. In this case, if you expect that the linked or attached program may want to return a larger value, pad the original value to the right with blanks. As an example, suppose you link to a program called PGMCODES and pass a variable pcode that has the value PC7177. The LINKMVS environment evaluates the value of the variable pcode (PC7177) and builds a parameter list pointing to the value. The halfword length field contains the length of the value, which is 6, followed by the value itself. Suppose the PGMCODES program updates the PC7177 value to the value PC7177ADC3. When the PGMCODES program returns control to the LINKMVS environment, the program must update the length value in the halfword length field to 10 to indicate the actual length of the value it is returning to the exec. You can use the LINKMVS or ATTCHMVS environments and not specify any parameters. For example:
ADDRESS ATTCHMVS workpgm

If you do not specify any parameters, register 1 contains an address that points to a parameter list. The high-order bit is on in the first parameter address. The parameter address points to a parameter that has a length of 0. An example using LINKMVS to specify user-defined Ddnames: In this example the user had the need to specify user-defined ddnames, instead of using SYSUT1 and SYSUT2, for an invocation of IEBGENER, an MVS data set utility program.
/* Rexx - Invoke IEBGENER with alternate ddnames. */ prog = IEBGENER parm = /* Standard PARM, as from JCL ddlist = copies(00x,8) ||, /* DDname 1 override: SYSLIN copies(00x,8) ||, /* DDname 2 override: n/a copies(00x,8) ||, /* DDname 3 override: SYSLMOD copies(00x,8) ||, /* DDname 4 override: SYSLIB left(CTL, 8) ||, /* DDname 5 override: SYSIN

*/ */ */ */ */ */

Chapter 2. REXX general concepts

39

REXX General Concepts

left(REP, 8) copies(00x,8) left(INP, 8) left(OUT, 8) copies(00x,8) copies(00x,8) copies(00x,8) copies(00x,8) copies(00x,8) ||, ||, ||, ||, ||, ||, ||, ||, /* /* /* /* /* /* /* /* /* DDname DDname DDname DDname DDname DDname DDname DDname DDname 6 7 8 9 10 11 12 13 14 override: override: override: override: override: override: override: override: override: SYSPRINT */ SYSPUNCH */ SYSUT1 */ SYSUT2 */ SYSUT3 */ SYSUT4 */ SYSTERM */ n/a */ SYSCIN */

address LINKMVS prog PARM DDLIST exit rc

The program to be invoked is specified in variable PROG as IEBGENER, the parameters for the IEBGENER program are specified in variables PARM and DDLIST. CTL, REP, INP, and OUT are the replaced ddnames. Examples of using LINKMVS, ATTCHMVS, and CALL to invoke a program: The LINKMVS and ATTCHMVS address environments can be used to invoke a program normally invoked as a batch job, as can the TSO CALL command. Table 3 shows various examples of invoking program MYWTO while passing a single parameter or while passing two parameters to the program. Note the varying effects of specifying the msg variable, either within quotation marks or not within quotation marks, on the LINKMVS (or ATTCHMVS) invocation. Examples 1, 2, 3, 4, and 6 show several different ways of invoking MYWTO while passing a single 9-character parameter string: A MESSAGE. Example 5 is similar to examples 14, and 6, however, an 11-character string 'A MESSAGE' is passed. The leading and trailing single quotation markers part of the string that is passed. Example 7 shows the passing of two parameters to the program, the value of variable A and the value of the variable MESSAGE. However, because these two variables were not initialized before the invocation, each variable has a value equal to its own name, in uppercase. The end result is that two parameter strings are passed to the program. The first parameter is the 1-character string A, and the second parameter is the 7-character string MESSAGE. In contrast, in example 9, two parameter strings are passed to the program, the value of variable A (namely, Value1) and the value of variable MESSAGE (namely, Value 2). Example 8 is similiar to example 6, in that both pass the same string A MESSAGE. In example 8, the fact that variables A and MESSAGE have values before the invocation is irrelevant, since the parameter string A MESSAGE is passed, not the values of variables A and MESSAGE.
Table 3. Examples of using LINKMVS, ATTCHMVS, and CALL to invoke a program 1 2 3 4 JCL TSO CLIST TSO REXX TSO REXX EXEC PGM= //* Call MYWTO, passing A MESSAGE*/ /stepname EXEC PGM=MYWTO,PARM='A MESSAGE' CALL command CALL command CALL command /* Call MYWTO, passing A MESSAGE */ CALL *(MYWTO) 'A MESSAGE' /* Call MYWTO, passing A MESSAGE */ Address TSO "CALL *(MYWTO) 'A MESSAGE'" /* REXX */ /* Call MYWTO, passing A MESSAGE */ msg = "'A MESSAGE'" Address TSO "CALL *(MYWTO)" msg

40

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

Table 3. Examples of using LINKMVS, ATTCHMVS, and CALL to invoke a program (continued) 5 TSO REXX LINKMVS or ATTCHMVS host command environment /* REXX */ /* Call MYWTO, passing 'A MESSAGE' */ msg = "'A MESSAGE'" /* single quotes part of value passed */ Address LINKMVS "MYWTO msg" Guideline: The variable name msg must be inside the quotation marks in order to pass a single parameter with the value 'A MESSAGE' to the called program. 6 TSO REXX LINKMVS or ATTCHMVS host command environment /* REXX */ /* Call MYWTO, passing A MESSAGE */ msg = "A MESSAGE" Address LINKMVS "MYWTO msg" /* msg inside quotation marks */ Guideline: The variable name msg must be inside the quotation marks in order to pass a single parameter with the value A MESSAGE to the called program. 7 TSO REXX LINKMVS or ATTCHMVS host command environment /* REXX */ /* Call MYWTO, passing two parameters */ /* - value of the variable A */ /* - value of the variable MESSAGE */ msg = "A MESSAGE" Address LINKMVS "MYWTO" msg /* msg outside quotes */ Guideline: The variable name msg is outside the double quotation marks, so the statement is equivalent to: Address LINKMVS "MYWTO A MESSAGE" The values of variables A and MESSAGE are passed to the called routine. Since these variables are uninitialized, their respective values are A and MESSAGE. Program MYWTO therefore is passed two parameters, the first with the value A and the second with the value MESSAGE. 8 TSO REXX LINKMVS or ATTCHMVS host command environment /* REXX */ /* Call MYWTO, passing A MESSAGE */ A = "Value1" MESSAGE = "Value2" msg = "A MESSAGE" Address LINKMVS "MYWTO msg" /* msg inside quotation marks */ Guideline: The variable name msg must be inside the quotation marks in order to pass a single parameter with the value A MESSAGE to the called program; the values of variables A and MESSAGE are not used in this example.

Chapter 2. REXX general concepts

41

REXX General Concepts

Table 3. Examples of using LINKMVS, ATTCHMVS, and CALL to invoke a program (continued) 9 TSO REXX LINKMVS or ATTCHMVS host command environment /* REXX */ /* Call MYWTO, passing two parameters */ /* - value of the variable A */ /* - value of the variable MESSAGE */ A = "Value1" MESSAGE = "Value2" msg = "A MESSAGE" Address LINKMVS "MYWTO" msg /* msg outside quotation marks */ Guideline: The variable name msg is outside the double quotation marks, so the statement is equivalent to: Address LINKMVS "MYWTO A MESSAGE" The values of variables A and MESSAGE are passed to the called routine. Program MYWTO therefore is passed two parameters, the first with the value Value1 and the second with the value Value 2.

The LINKPGM and ATTCHPGM host command environments

For the LINKPGM and ATTCHPGM environments, you can pass multiple parameters to the program. Specify the name of the program followed by variable names for each of the parameters. Separate each variable name by one or more blanks. For example:
ADDRESS LINKPGM "WKSTATS var1 var2"

For the parameters, specify variable names instead of the actual values. Enclose the name of the program and the variable names in either single or double quotation marks. By using the quotation marks, the language processor does not evaluate any variables and simply passes the expression to the host command environment for processing. The LINKPGM or ATTCHPGM environment itself evaluates the variables and performs variable substitution. If you do not use a variable for each parameter and enclose the expression in quotation marks, you may have problems with variable substitution and receive unexpected results. After the LINKPGM or ATTCHPGM environment routine evaluates the value of each variable, it builds a parameter list pointing to the values. The routine then links to or attaches the program and passes the parameter list to the program. Figure 6 on page 43 shows how the LINKPGM or ATTCHPGM host command environment routine passes the parameters to the program. Register 0 points to the ENVBLOCK under which the REXX exec issuing the ADDRESS LINKPGM or ADDRESS ATTCHPGM is running. Register 1 contains the address of a parameter list, which consists of a list of addresses. Each address in the parameter list points to a parameter. The high-order bit of the last address in the parameter list is set to 1 to indicate the end of the parameter list.

42

z/OS V1R13.0 TSO/E REXX Reference

REXX General Concepts

R0

ENVBLOCK

R1

Parameter List Parameter 1 Parameter 2 . . . . . * Parameter n * high order bit on

Figure 6. Parameters for LINKPGM and ATTCHPGM environments

Parameter 1 Parameter 2

Parameter n

Unlike the LINKMVS and ATTCHMVS host command environments, the parameters for the LINKPGM and ATTCHPGM environments do not have a length field. On output from the linked or attached routine, the value of the parameter is updated and the length of each parameter is considered to be the same as when the parameter list was created. The linked or attached routine cannot increase the length of the value of a variable that it receives. However, you can pad the length of the value of a variable with blanks to increase its length before you link to or attach a program. As an example, suppose you want to link to the RESLINE program and you want to pass one parameter, a reservation code of WK007816. When you use the ADDRESS LINKPGM instruction, specify a variable name for the parameter; for example, revcode for the reservation code, WK007816. Before you use ADDRESS LINKPGM, assign the value to the variable name.
/* . REXX program that links ... . . revcode = WK007816 . . . ADDRESS LINKPGM RESLINE revcode . . . EXIT */

In the example, you assign the variable revcode the value WK007816. On the ADDRESS LINKPGM instruction, you use the variable name for the parameter. The LINKPGM host command environment evaluates the variable and passes the value of the variable to the RESLINE program. The length of the parameter (variable revcode) is 8. If the RESLINE program wanted to update the value of the variable and return the updated value to the REXX exec, the program could not return a value that is greater than 8 bytes. To allow the linked program to return a larger value, you could pad the value of the original variable to the right with blanks. For example, in the exec you could add seven blanks and assign the value

Chapter 2. REXX general concepts

43

REXX General Concepts

WK007816 to the revcode variable. The length would then be 15 and the linked program could return an updated value that was up to 15 bytes. You can use the LINKPGM or ATTCHPGM environments and not specify any parameters. For example:
ADDRESS ATTCHPGM "monbill"

If you do not specify any parameters, register 1 contains an address that points to a parameter list. The high-order bit is on in the first parameter address, but the address itself is 0.

44

z/OS V1R13.0 TSO/E REXX Reference

Chapter 3. Keyword instructions

A keyword instruction is one or more clauses, the first of which starts with a keyword that identifies the instruction. Some keyword instructions affect the flow of control, while others provide services to the programmer. Some keyword instructions, like DO, can include nested instructions. In the syntax diagrams on the following pages, symbols (words) in capitals denote keywords or subkeywords; other words (such as expression) denote a collection of tokens as defined previously. Note, however, that the keywords and subkeywords are not case-dependent; the symbols if, If, and iF all have the same effect. Note also that you can usually omit most of the clause delimiters (;) shown because they are implied by the end of a line. A keyword instruction is recognized only if its keyword is the first token in a clause, and if the second token does not start with an = character (implying an assignment) or a colon (implying a label). The keywords ELSE, END, OTHERWISE, THEN, and WHEN are recognized in the same situation. Note that any clause that starts with a keyword defined by REXX cannot be a command. Therefore,
arg(fred) rest

is an ARG keyword instruction, not a command that starts with a call to the ARG built-in function. A syntax error results if the keywords are not in their correct positions in a DO, IF, or SELECT instruction. (The keyword THEN is also recognized in the body of an IF or WHEN clause.) In other contexts, keywords are not reserved and can be used as labels or as the names of variables (although this is generally not suggested). Certain other keywords, known as subkeywords, are reserved within the clauses of individual instructions. See Keyword instructions on page 19. For example, the symbols VALUE and WITH are subkeywords in the ADDRESS and PARSE instructions, respectively. For details, see the description of each instruction. For a general discussion on reserved keywords, see page 211. Blanks adjacent to keywords have no effect other than to separate the keyword from the subsequent token. One or more blanks following VALUE are required to separate the expression from the subkeyword in the example following:
ADDRESS VALUE expression

However, no blank is required after the VALUE subkeyword in the following example, although it would add to the readability:
ADDRESS VALUEENVIR||number

Copyright IBM Corp. 1988, 2011

45

ADDRESS

ADDRESS

ADDRESS environment expression expression1 VALUE

ADDRESS temporarily or permanently changes the destination of commands. Commands are strings sent to an external environment. You can send commands by specifying clauses consisting of only an expression or by using the ADDRESS instruction. How to enter commands to the host and the different host command environments TSO/E provides are described in Commands to external environments on page 24. To send a single command to a specified environment, code an environment, a literal string or a single symbol, which is taken to be a constant, followed by an expression. (The environment name is the name of an external procedure or process that can process commands.) The expression is evaluated, and the resulting string is routed to the environment to be processed as a command. (Enclose in quotation marks any part of the expression you do not want to be evaluated.) After execution of the command, environment is set back to whatever it was before, thus temporarily changing the destination for a single command. The special variable RC is set, just as it would be for other commands. (See page 25.) Errors and failures in commands processed in this way are trapped or traced as usual. Example:
ADDRESS LINK "routine p1 p2" /* TSO/E */

If you specify only environment, a lasting change of destination occurs: all commands that follow (clauses that are neither REXX instructions nor assignment instructions) are routed to the specified command environment, until the next ADDRESS instruction is processed. The previously selected environment is saved. Example:
Address MVS "QBUF" "MAKEBUF"

Similarly, you can use the VALUE form to make a lasting change to the environment. Here expression1 (which may be simply a variable name) is evaluated, and the result forms the name of the environment. You can omit the subkeyword VALUE if expression1 does not begin with a literal string or symbol (that is, if it starts with a special character, such as an operator character or parenthesis). Example:
ADDRESS (ENVIR||number) /* Same as ADDRESS VALUE ENVIR||number */

46

z/OS V1R13.0 TSO/E REXX Reference

ADDRESS
With no arguments, commands are routed back to the environment that was selected before the previous lasting change of environment was made, and the current environment name is saved. After changing the environment, repeated execution of ADDRESS alone, therefore, switches the command destination between two environments alternately. The two environment names are automatically saved across internal and external subroutine and function calls. See the CALL instruction (page 48) for more details. The address setting is the currently selected environment name. You can retrieve the current address setting by using the ADDRESS built-in function (see page 88). TSO/E REXX provides several host command environments that you can use with the ADDRESS instruction. The environments allow you to use different TSO/E, MVS, and ISPF services. See Host commands and host command environments on page 26. You can provide your own environments or routines that handle command processing in each environment. For more information, see Host command environment table on page 368.

ARG

ARG template_list

ARG retrieves the argument strings provided to a program or internal routine and assigns them to variables. It is a short form of the instruction:
PARSE UPPER ARG template_list ;

The template_list is often a single template but can be several templates separated by commas. If specified, each template is a list of symbols separated by blanks or patterns or both. Unless a subroutine or internal function is being processed, the strings passed as parameters to the program are parsed into variables according to the rules described in Chapter 5, Parsing, on page 169. If a subroutine or internal function is being processed, the data used will be the argument strings that the caller passes to the routine. In either case, the language processor translates the passed strings to uppercase (that is, lowercase az to uppercase AZ) before processing them. Use the PARSE ARG instruction if you do not want uppercase translation.

Chapter 3. Keyword instructions

47

ARG
You can use the ARG and PARSE ARG instructions repeatedly on the same source string or strings (typically with different templates). The source string does not change. The only restrictions on the length or content of the data parsed are those the caller imposes. Example:
/* String passed is "Easy Rider" Arg adjective noun . /* Now: ADJECTIVE contains EASY /* NOUN contains RIDER */ */ */

If you expect more than one string to be available to the program or routine, you can use a comma in the parsing template_list so each template is selected in turn. Example:
/* Function is called by Fred: FRED(data X,1,5) */

Arg string, num1, num2 STRING contains DATA X NUM1 contains 1 NUM2 contains 5 */ */ */

/* Now: /* /*

Notes: 1. The ARG built-in function can also retrieve or check the argument strings to a REXX program or internal routine. See page 89. 2. The source of the data being processed is also made available on entry to the program. See the PARSE instruction (SOURCE option) on page 66 for details.

CALL

, CALL name expression OFF ERROR FAILURE HALT ON ERROR FAILURE NAME HALT ;

trapname

CALL calls a routine (if you specify name) or controls the trapping of certain conditions (if you specify ON or OFF). To control trapping, you specify OFF or ON and the condition you want to trap. OFF turns off the specified condition trap. ON turns on the specified condition trap. All information about condition traps is contained in Chapter 7, Conditions and condition traps, on page 195.

48

z/OS V1R13.0 TSO/E REXX Reference

CALL
To call a routine, specify name, a literal string or symbol that is taken as a constant. The name must be a symbol, which is treated literally, or a literal string. The routine called can be: An internal routine A function or subroutine that is in the same program as the CALL instruction or function call that calls it. A function (which may be called as a subroutine) that is defined as part of the REXX language. A function or subroutine that is neither built-in nor in the same program as the CALL instruction or function call that calls it.

A built-in routine An external routine

If name is a string (that is, you specify name in quotation marks), the search for internal routines is bypassed, and only a built-in function or an external routine is called. Note that the names of built-in functions (and generally the names of external routines, too) are in uppercase; therefore, you should uppercase the name in the literal string. The called routine can optionally return a result, and when it does, the CALL instruction is functionally identical with the clause:
, result=name( expression ) ;

If the called routine does not return a result, then you will get an error if you call it as a function (as previously shown). If the subroutine returns a result, the result is stored in the REXX special variable RESULT, not the special variable RC. The REXX special variable RC is set when you enter host commands from a REXX program (see page 26), but RC is not set when you use the CALL instruction. See Chapter 9, Reserved keywords, special variables, and command names, on page 211 for descriptions of the three REXX special variables RESULT, RC, and SIGL. TSO/E supports specifying up to 20 expressions, separated by commas. The expressions are evaluated in order from left to right and form the argument strings during execution of the routine. Any ARG or PARSE ARG instruction or ARG built-in function in the called routine accesses these strings rather than any previously active in the calling program, until control returns to the CALL instruction. You can omit expressions, if appropriate, by including extra commas. The CALL then causes a branch to the routine called name, using exactly the same mechanism as function calls. (See Chapter 4, Functions, on page 81.) The search order is in the section on functions (see Search order on page 83) but briefly is as follows: Internal routines: These are sequences of instructions inside the same program, starting at the label that matches name in the CALL instruction. If you specify the routine name in quotation marks, then an internal routine is not considered for that search order. You can use SIGNAL and CALL together to call an internal routine whose name is determined at the time of execution; this is
Chapter 3. Keyword instructions

49

CALL
known as a multi-way call (see page 75). The RETURN instruction completes the execution of an internal routine. Built-in routines: These are routines built into the language processor for providing various functions. They always return a string that is the result of the routine (see page 87). External routines: Users can write or use routines that are external to the language processor and the calling program. You can code an external routine in REXX or in any language that supports the system-dependent interfaces. For information about using the system-dependent interfaces, see External functions and subroutines, and function packages on page 288. For information about the search order the system uses to locate external routines, see Search order on page 83. If the CALL instruction calls an external routine written in REXX as a subroutine, you can retrieve any argument strings with the ARG or PARSE ARG instructions or the ARG built-in function. During execution of an internal routine, all variables previously known are generally accessible. However, the PROCEDURE instruction can set up a local variables environment to protect the subroutine and caller from each other. The EXPOSE option on the PROCEDURE instruction can expose selected variables to a routine. Calling an external program as a subroutine is similar to calling an internal routine. The external routine, however, is an implicit PROCEDURE in that all the caller's variables are always hidden. The status of internal values (NUMERIC settings, and so forth) start with their defaults (rather than inheriting those of the caller). In addition, you can use EXIT to return from the routine. When control reaches an internal routine the line number of the CALL instruction is available in the variable SIGL (in the caller's variable environment). This may be used as a debug aid, as it is, therefore, possible to find out how control reached a routine. Note that if the internal routine uses the PROCEDURE instruction, then it needs to EXPOSE SIGL to get access to the line number of the CALL. Eventually the subroutine should process a RETURN instruction, and at that point control returns to the clause following the original CALL. If the RETURN instruction specified an expression, the variable RESULT is set to the value of that expression. Otherwise, the variable RESULT is dropped (becomes uninitialized). An internal routine can include calls to other internal routines, as well as recursive calls to itself. Example:
/* Recursive subroutine execution... */ arg z call factorial z say z! = result exit factorial: procedure arg n if n=0 then return 1 call factorial n-1 return result * n /* Calculate factorial by */ /* recursive invocation. */

50

z/OS V1R13.0 TSO/E REXX Reference

CALL
During internal subroutine (and function) execution, all important pieces of information are automatically saved and are then restored upon return from the routine. These are: v The status of DO loops and other structures: Executing a SIGNAL while within a subroutine is safe because DO loops, and so forth, that were active when the subroutine was called are not ended. (But those currently active within the subroutine are ended.) v Trace action: After a subroutine is debugged, you can insert a TRACE Off at the beginning of it, and this does not affect the tracing of the caller. Conversely, if you simply wish to debug a subroutine, you can insert a TRACE Results at the start and tracing is automatically restored to the conditions at entry (for example, Off) upon return. Similarly, ? (interactive debug) and ! (command inhibition) are saved across routines. v NUMERIC settings: The DIGITS, FUZZ, and FORM of arithmetic operations (in NUMERIC on page 63) are saved and are then restored on return. A subroutine can, therefore, set the precision, and so forth, that it needs to use without affecting the caller. v ADDRESS settings: The current and previous destinations for commands (see ADDRESS on page 46) are saved and are then restored on return. v Condition traps: (CALL ON and SIGNAL ON) are saved and then restored on return. This means that CALL ON, CALL OFF, SIGNAL ON, and SIGNAL OFF can be used in a subroutine without affecting the conditions the caller set up. v Condition information: This information describes the state and origin of the current trapped condition. The CONDITION built-in function returns this information. See CONDITION on page 93. v Elapsed-time clocks: A subroutine inherits the elapsed-time clock from its caller (see TIME on page 113), but because the time clock is saved across routine calls, a subroutine or internal function can independently restart and use the clock without affecting its caller. For the same reason, a clock started within an internal routine is not available to the caller. v OPTIONS settings: ETMODE and EXMODE are saved and are then restored on return. For more information, see OPTIONS on page 64. Implementation maximum: The total nesting of control structures, which includes internal routine calls, may not exceed a depth of 250.

Chapter 3. Keyword instructions

51

DO

DO

DO repetitor conditional

END

instruction ; name

repetitor:
name=expri TO exprt FOREVER exprr BY exprb FOR exprf

conditional:
WHILE exprw UNTIL expru

DO groups instructions together and optionally processes them repetitively. During repetitive execution, a control variable (name) can be stepped through some range of values. Syntax Notes: v The exprr, expri, exprb, exprt, and exprf options (if present) are any expressions that evaluate to a number. The exprr and exprf options are further restricted to result in a positive whole number or zero. If necessary, the numbers are rounded according to the setting of NUMERIC DIGITS. v The exprw or expru options (if present) can be any expression that evaluates to 1 or 0. v The TO, BY, and FOR phrases can be in any order, if used, and are evaluated in the order in which they are written. v The instruction can be any instruction, including assignments, commands, and keyword instructions (including any of the more complex constructs such as IF, SELECT, and the DO instruction itself). v The subkeywords WHILE and UNTIL are reserved within a DO instruction, in that they cannot be used as symbols in any of the expressions. Similarly, TO, BY, and FOR cannot be used in expri, exprt, exprb, or exprf. FOREVER is also reserved, but only if it immediately follows the keyword DO and an equal sign does not follow it. v The exprb option defaults to 1, if relevant.

Simple DO group
If you specify neither repetitor nor conditional, the construct merely groups a number of instructions together. These are processed one time.

52

z/OS V1R13.0 TSO/E REXX Reference

DO
In the following example, the instructions are processed one time. Example:
/* The two instructions between DO and END are both /* processed if A has the value "3". If a=3 then Do a=a+2 Say Smile! End */ */

Repetitive DO loops
If a DO instruction has a repetitor phrase or a conditional phrase or both, the group of instructions forms a repetitive DO loop. The instructions are processed according to the repetitor phrase, optionally modified by the conditional phrase. (See Conditional phrases (WHILE and UNTIL) on page 55).

Simple repetitive loops

A simple repetitive loop is a repetitive DO loop in which the repetitor phrase is an expression that evaluates to a count of the iterations. If repetitor is omitted but there is a conditional or if the repetitor is FOREVER, the group of instructions is nominally processed forever, that is, until the condition is satisfied or a REXX instruction is processed that ends the loop (for example, LEAVE). For a discussion on conditional phrases, see Conditional phrases (WHILE and UNTIL) on page 55. In the simple form of a repetitive loop, exprr is evaluated immediately (and must result in a positive whole number or zero), and the loop is then processed that many times. Example:
/* This displays "Hello" five times */ Do 5 say Hello end

Note that, similar to the distinction between a command and an assignment, if the first token of exprr is a symbol and the second token is (or starts with) =, the controlled form of repetitor is expected.

Controlled repetitive loops

The controlled form specifies name, a control variable that is assigned an initial value (the result of expri, formatted as though 0 had been added) before the first execution of the instruction list. The variable is then stepped (by adding the result of exprb) before the second and subsequent times that the instruction list is processed. The instruction list is processed repeatedly while the end condition (determined by the result of exprt) is not met. If exprb is positive or 0, the loop is ended when name is greater than exprt. If negative, the loop is ended when name is less than exprt. The expri, exprt, and exprb options must result in numbers. They are evaluated only one time, before the loop begins and before the control variable is set to its initial value. The default value for exprb is 1. If exprt is omitted, the loop runs indefinitely unless some other condition stops it.
Chapter 3. Keyword instructions

53

DO
Example:
Do I=3 to -2 by -1 say i end /* Displays: /* 3 /* 2 /* 1 /* 0 /* -1 /* -2 */ */ */ */ */ */ */

The numbers do not have to be whole numbers: Example:

I=0.3 Do Y=I to I+4 by 0.7 say Y end /* Displays: /* 0.3 /* 1.0 /* 1.7 /* 2.4 /* 3.1 /* 3.8 */ */ */ */ */ */ */

The control variable can be altered within the loop, and this may affect the iteration of the loop. Altering the value of the control variable is not usually considered good programming practice, though it may be appropriate in certain circumstances. Note that the end condition is tested at the start of each iteration (and after the control variable is stepped, on the second and subsequent iterations). Therefore, if the end condition is met immediately, the group of instructions can be skipped entirely. Note also that the control variable is referred to by name. If (for example) the compound name A.I is used for the control variable, altering I within the loop causes a change in the control variable. The execution of a controlled loop can be bounded further by a FOR phrase. In this case, you must specify exprf, and it must evaluate to a positive whole number or zero. This acts just like the repetition count in a simple repetitive loop, and sets a limit to the number of iterations around the loop if no other condition stops it. Like the TO and BY expressions, it is evaluated only one timewhen the DO instruction is first processed and before the control variable receives its initial value. Like the TO condition, the FOR condition is checked at the start of each iteration. Example:
Do Y=0.3 to 4.3 by 0.7 for 3 /* Displays: say Y /* 0.3 end /* 1.0 /* 1.7 */ */ */ */

In a controlled loop, the name describing the control variable can be specified on the END clause. This name must match name in the DO clause in all respects except case (note that no substitution for compound variables is carried out); a syntax error results if it does not. This enables the nesting of loops to be checked automatically, with minimal overhead. Example:
Do K=1 to 10 ... ... End k /* Checks that this is the END for K loop */

54

z/OS V1R13.0 TSO/E REXX Reference

DO
The NUMERIC settings may affect the successive values of the control variable, because REXX arithmetic rules apply to the computation of stepping the control variable.

Conditional phrases (WHILE and UNTIL)

A conditional phrase can modify the iteration of a repetitive DO loop. It may cause the termination of a loop. It can follow any of the forms of repetitor (none, FOREVER, simple, or controlled). If you specify WHILE or UNTIL, exprw or expru, respectively, is evaluated each time around the loop using the latest values of all variables (and must evaluate to either 0 or 1), and the loop is ended if exprw evaluates to 0 or expru evaluates to 1. For a WHILE loop, the condition is evaluated at the top of the group of instructions. For an UNTIL loop, the condition is evaluated at the bottombefore the control variable has been stepped. Example:
Do I=1 to 10 by 2 until i>6 say i end /* Displays: "1" "3" "5" "7" */

Tip: You can also modify the execution of repetitive loops by using the LEAVE or ITERATE instructions.

Chapter 3. Keyword instructions

55

DO

Evaluate exprr +0 or evaluate expri +0 and then exprt +0, exprb+0, and exprf +0 in order written.

Assign start value to control variable.

Use TO value ( exprt ) to test control variable for termination.

Discontinue execution of DO group if TO value is exceeded. Discontinue execution of DO group if number of iterations is exceeded. Discontinue execution of DO group if FOR value (number of iterations through the loop) is exceeded. Discontinue execution of DO group if WHILE condition is not met.

Use count of iterations ( exprr) to test for termination.

Use FOR value (exprf ) to test for termination.

Use WHILE expression (exprw ) to test for termination.

Execute instruction(s) in the DO group.

Use UNTIL expression (expru ) to test for termination.

Discontinue execution of DO group if UNTIL condition is met.

Use BY value (exprb ) to update control variable.

Figure 7. Concept of a DO loop

56

z/OS V1R13.0 TSO/E REXX Reference

DROP

DROP

DROP

name (name)

DROP unassigns variables, that is, restores them to their original uninitialized state. If name is not enclosed in parentheses, it identifies a variable you want to drop and must be a symbol that is a valid variable name, separated from any other name by one or more blanks or comments. If parentheses enclose a single name, then its value is used as a subsidiary list of variables to drop. (Blanks are not necessary either inside or outside the parentheses, but you can add them if desired.) This subsidiary list must follow the same rules as the original list (that is, be valid variable names, separated by blanks) except that no parentheses are allowed. Variables are dropped in sequence from left to right. It is not an error to specify a name more than one time or to DROP a variable that is not known. If an exposed variable is named, (see PROCEDURE on page 68), the variable in the older generation is dropped. Example:
j=4 Drop a z.3 z.j /* Drops the variables: A, Z.3, and Z.4 /* so that reference to them returns their names.

*/ */

Here, a variable name in parentheses is used as a subsidiary list. Example:

mylist='c d e' drop (mylist) f /* Drops the variables C, D, E, and F /* Does not drop MYLIST

*/ */

Specifying a stem (that is, a symbol that contains only one period, as the last character), drops all variables starting with that stem. Example:
Drop z. /* Drops all variables with names starting with Z. */

EXIT

EXIT expression

Chapter 3. Keyword instructions

57

EXIT
EXIT leaves a program unconditionally. Optionally EXIT returns a character string to the caller. The program is stopped immediately, even if an internal routine is currently being run. If no internal routine is active, RETURN (see page 72) and EXIT are identical in their effect on the program that is being run. If you specify expression, it is evaluated and the string resulting from the evaluation is passed back to the caller when the program stops. Example:
j=3 Exit j*4 /* Would exit with the string 12 */

If you do not specify expression, no data is passed back to the caller. If the program was called as an external function, this is detected as an erroreither immediately (if RETURN was used), or on return to the caller (if EXIT was used). Running off the end of the program is always equivalent to the instruction EXIT, in that it stops the whole program and returns no result string. Note: If the program was called through a command interface, an attempt is made to convert the returned value to a return code acceptable by the host. If the conversion fails, it is deemed to be a failure of the host interface and thus is not subject to trapping with SIGNAL ON SYNTAX. The returned string must be a whole number whose value fits in a general register (that is, must be in the range -2**31 through 2**31-1).

IF

IF expression ;

THEN ;

instruction

ELSE ;

instruction

IF conditionally processes an instruction or group of instructions depending on the evaluation of the expression. The expression is evaluated and must result in 0 or 1. The instruction after the THEN is processed only if the result is 1 (true). If you specify an ELSE, the instruction after the ELSE is processed only if the result of the evaluation is 0 (false). Example:
if answer=YES then say OK! else say Why not?

Remember that if the ELSE clause is on the same line as the last clause of the THEN part, you need a semicolon before the ELSE. Example:
if answer=YES then say OK!; else say Why not?

58

z/OS V1R13.0 TSO/E REXX Reference

IF
The ELSE binds to the nearest IF at the same level. You can use the NOP instruction to eliminate errors and possible confusion when IF constructs are nested, as in the following example. Example:
If answer = YES Then If name = FRED Then say OK, Fred. Else nop Else say Why not?

Notes: 1. The instruction can be any assignment, command, or keyword instruction, including any of the more complex constructs such as DO, SELECT, or the IF instruction itself. A null clause is not an instruction, so putting an extra semicolon (or label) after the THEN or ELSE is not equivalent to putting a dummy instruction (as it would be in PL/I). The NOP instruction is provided for this purpose. 2. The symbol THEN cannot be used within expression, because the keyword THEN is treated differently, in that it need not start a clause. This allows the expression on the IF clause to be ended by the THEN, without a ; being required. If this were not so, people who are accustomed to other computer languages would experience considerable difficulties.

INTERPRET

INTERPRET expression;

INTERPRET processes instructions that have been built dynamically by evaluating expression. The expression is evaluated and is then processed (interpreted) just as though the resulting string were a line inserted into the program (and bracketed by a DO; and an END;). Any instructions (including INTERPRET instructions) are allowed, but note that constructions such as DO...END and SELECT...END must be complete. For example, a string of instructions being interpreted cannot contain a LEAVE or ITERATE instruction (valid only within a repetitive DO loop) unless it also contains the whole repetitive DO...END construct. A semicolon is implied at the end of the expression during execution, if one was not supplied. Example:
data=FRED interpret data = 4 /* Builds the string "FRED = 4" and /* Processes: FRED = 4; /* Thus the variable FRED is set to "4"

*/ */ */

Chapter 3. Keyword instructions

59

INTERPRET
Example:
data=do 3; say "Hello there!"; end interpret data /* Displays: /* Hello there! /* Hello there! /* Hello there! */ */ */ */

Notes: 1. Label clauses are not permitted in an interpreted character string. 2. If you are new to the concept of the INTERPRET instruction and are getting results that you do not understand, you may find that executing it with TRACE R or TRACE I in effect is helpful. Example:
/* Here is a small REXX program. */ Trace Int name=Kitty indirect=name interpret say "Hello" indirect"!"

When this is run, it gives the trace:

kitty 3 *-* name=Kitty >L> "Kitty" 4 *-* indirect=name >L> "name" 5 *-* interpret say "Hello" indirect"!" >L> "say "Hello"" >V> "name" >O> "say "Hello" name" >L> ""!"" >O> "say "Hello" name"!"" *-* say "Hello" name"!" >L> "Hello" >V> "Kitty" >O> "Hello Kitty" >L> "!" >O> "Hello Kitty!" Hello Kitty!

Here, lines 3 and 4 set the variables used in line 5. Execution of line 5 then proceeds in two stages. First the string to be interpreted is built up, using a literal string, a variable (INDIRECT), and another literal string. The resulting pure character string is then interpreted, just as though it were actually part of the original program. Because it is a new clause, it is traced as such (the second *-* trace flag under line 5) and is then processed. Again a literal string is concatenated to the value of a variable (NAME) and another literal, and the final result (Hello Kitty!) is then displayed. 3. For many purposes, you can use the VALUE function (see page 117) instead of the INTERPRET instruction. The following line could, therefore, have replaced line 5 in the last example:
say "Hello" value(indirect)"!"

INTERPRET is usually required only in special cases, such as when two or more statements are to be interpreted together, or when an expression is to be evaluated dynamically.

60

z/OS V1R13.0 TSO/E REXX Reference

ITERATE

ITERATE

ITERATE name

ITERATE alters the flow within a repetitive DO loop (that is, any DO construct other than that with a simple DO). Execution of the group of instructions stops, and control is passed to the DO instruction. The control variable (if any) is incremented and tested, as usual, and the group of instructions is processed again, unless the DO instruction ends the loop. The name is a symbol, taken as a constant. If name is not specified, ITERATE steps the innermost active repetitive loop. If name is specified, it must be the name of the control variable of a currently active loop (which may be the innermost), and this is the loop that is stepped. Any active loops inside the one selected for iteration are ended (as though by a LEAVE instruction). Example:
do i=1 to 4 if i=2 then iterate say i end /* Displays the numbers:

"1" "3" "4" */

Notes: 1. If specified, name must match the symbol naming the control variable in the DO clause in all respects except case. No substitution for compound variables is carried out when the comparison is made. 2. A loop is active if it is currently being processed. If a subroutine is called (or an INTERPRET instruction is processed) during execution of a loop, the loop becomes inactive until the subroutine has returned or the INTERPRET instruction has completed. ITERATE cannot be used to step an inactive loop. 3. If more than one active loop uses the same control variable, ITERATE selects the innermost loop.

LEAVE

LEAVE name

LEAVE causes an immediate exit from one or more repetitive DO loops (that is, any DO construct other than a simple DO).

Chapter 3. Keyword instructions

61

LEAVE
Processing of the group of instructions is ended, and control is passed to the instruction following the END clause. The control variable (if any) will contain the value it had when the LEAVE instruction was processed. The name is a symbol, taken as a constant. If name is not specified, LEAVE ends the innermost active repetitive loop. If name is specified, it must be the name of the control variable of a currently active loop (which may be the innermost), and that loop (and any active loops inside it) is then ended. Control then passes to the clause following the END that matches the DO clause of the selected loop. Example:
do i=1 to 5 say i if i=3 then leave end /* Displays the numbers:

"1" "2" "3" */

Notes: 1. If specified, name must match the symbol naming the control variable in the DO clause in all respects except case. No substitution for compound variables is carried out when the comparison is made. 2. A loop is active if it is currently being processed. If a subroutine is called (or an INTERPRET instruction is processed) during execution of a loop, the loop becomes inactive until the subroutine has returned or the INTERPRET instruction has completed. LEAVE cannot be used to end an inactive loop. 3. If more than one active loop uses the same control variable, LEAVE selects the innermost loop.

NOP

NOP;

NOP is a dummy instruction that has no effect. It can be useful as the target of a THEN or ELSE clause: Example:
Select when a=c then nop when a>c then say A > C otherwise say A < C end /* Do nothing */

Tip: Putting an extra semicolon instead of the NOP would merely insert a null clause, which would be ignored. The second WHEN clause would be seen as the first instruction expected after the THEN, and would, therefore, be treated as a syntax error. NOP is a true instruction, however, and is, therefore, a valid target for the THEN clause.

62

z/OS V1R13.0 TSO/E REXX Reference

NUMERIC

NUMERIC

NUMERIC

DIGITS expression1 SCIENTIFIC FORM ENGINEERING expression2 VALUE FUZZ expression3

NUMERIC changes the way in which a program carries out arithmetic operations. See 185-193 for the options of this instruction, but in summary: NUMERIC DIGITS controls the precision to which arithmetic operations and arithmetic built-in functions are evaluated. If you omit expression1, the precision defaults to 9 digits. Otherwise, expression1 must evaluate to a positive whole number and must be larger than the current NUMERIC FUZZ setting. There is no limit to the value for DIGITS (except the amount of storage available), but note that high precisions are likely to require a good deal of processing time. It is suggested that you use the default value wherever possible. You can retrieve the current NUMERIC DIGITS setting with the DIGITS built-in function. See DIGITS on page 99. NUMERIC FORM controls which form of exponential notation REXX uses for the result of arithmetic operations and arithmetic built-in functions. This may be either SCIENTIFIC (in which case only one, nonzero digit appears before the decimal point) or ENGINEERING (in which case the power of 10 is always a multiple of 3). The default is SCIENTIFIC. The subkeywords SCIENTIFIC or ENGINEERING set the FORM directly, or it is taken from the result of evaluating the expression (expression2) that follows VALUE. The result in this case must be either SCIENTIFIC or ENGINEERING. You can omit the subkeyword VALUE if expression2 does not begin with a symbol or a literal string (that is, if it starts with a special character, such as an operator character or parenthesis). You can retrieve the current NUMERIC FORM setting with the FORM built-in function. See FORM on page 102. NUMERIC FUZZ controls how many digits, at full precision, are ignored during a numeric comparison operation. (See 191.) If you omit expression3, the default is 0 digits. Otherwise, expression3 must evaluate to 0 or a positive whole number, rounded if necessary according to the current NUMERIC DIGITS setting, and must be smaller than the current NUMERIC DIGITS setting. NUMERIC FUZZ temporarily reduces the value of NUMERIC DIGITS by the NUMERIC FUZZ value during every numeric comparison. The numbers are subtracted under a precision of DIGITS minus FUZZ digits during the comparison and are then compared with 0.
Chapter 3. Keyword instructions

63

NUMERIC
You can retrieve the current NUMERIC FUZZ setting with the FUZZ built-in function. See FUZZ on page 103. The three numeric settings are automatically saved across internal and external subroutine and function calls. See 48 for more details about the CALL instruction.

OPTIONS

OPTIONS expression;

OPTIONS passes special requests or parameters to the language processor. For example, these may be language processor options or perhaps define a special character set. The expression is evaluated, and the result is examined one word at a time. The language processor converts the words to uppercase. If the language processor recognizes the words, then they are obeyed. Words that are not recognized are ignored and assumed to be instructions to a different processor. The language processor recognizes the following words: ETMODE specifies that literal strings and symbols and comments containing DBCS characters are checked for being valid DBCS strings. If you use this option, it must be the first instruction of the program. If the expression is an external function call, for example OPTIONS GETETMOD(), and the program contains DBCS literal strings, enclose the name of the function in quotation marks to ensure that the entire program is not scanned before the option takes effect. It is not suggested to use internal function calls to set ETMODE because of the possibility of errors in interpreting DBCS literal strings in the program. NOETMODE specifies that literal strings and symbols and comments containing DBCS characters are not checked for being valid DBCS strings. NOETMODE is the default. The language processor ignores this option unless it is the first instruction in a program. EXMODE specifies that instructions, operators, and functions handle DBCS data in mixed strings on a logical character basis. DBCS data integrity is maintained.

NOEXMODE specifies that any data in strings is handled on a byte basis. The integrity of DBCS characters, if any, may be lost. NOEXMODE is the default. Notes: 1. Because of the language processor's scanning procedures, you must place an OPTIONS 'ETMODE' instruction as the first instruction in a program containing DBCS characters in literal strings, symbols, or comments. If you do not place OPTIONS ETMODE as the first instruction and you use it later in the program, you receive error message IRX0033I. If you do place it as the first instruction of your program, all subsequent uses are ignored. If the expression contains anything that would start a label search, all clauses tokenized during the label

64

z/OS V1R13.0 TSO/E REXX Reference

OPTIONS
search process are tokenized within the current setting of ETMODE. Therefore, if this is the first statement in the program, the default is NOETMODE. To ensure proper scanning of a program containing DBCS literals and DBCS comments, enter the words ETMODE, NOETMODE, EXMODE, and NOEXMODE as literal strings (that is, enclosed in quotation marks) in the OPTIONS instruction. The EXMODE setting is saved and restored across subroutine and function calls. To distinguish DBCS characters from 1-byte EBCDIC characters, sequences of DBCS characters are enclosed with a shift-out (SO) character and a shift-in (SI) character. The hexadecimal values of the SO and SI characters are X'0E' and X'0F', respectively. When you specify OPTIONS 'ETMODE', DBCS characters within a literal string are excluded from the search for a closing quotation mark in literal strings. The words ETMODE, NOETMODE, EXMODE, and NOEXMODE can appear several times within the result. The one that takes effect is determined by the last valid one specified between the pairs ETMODE-NOETMODE and EXMODE-NOEXMODE.

2.

3. 4.

5. 6.

PARSE

PARSE UPPER

ARG EXTERNAL NUMERIC PULL SOURCE VALUE expression VAR name VERSION

; template_list

WITH

PARSE assigns data (from various sources) to one or more variables according to the rules of parsing (see Chapter 5, Parsing, on page 169). The template_list is often a single template but may be several templates separated by commas. If specified, each template is a list of symbols separated by blanks or patterns or both. Each template is applied to a single source string. Specifying multiple templates is never a syntax error, but only the PARSE ARG variant can supply more than one non-null source string. See 178 for information about parsing multiple source strings. If you do not specify a template, no variables are set but action is taken to prepare the data for parsing, if necessary. Thus for PARSE PULL, a data string is removed from the queue, and for PARSE VALUE, expression is evaluated. For PARSE VAR, the specified variable is accessed. If it does not have a value, the NOVALUE condition is raised, if it is enabled.

Chapter 3. Keyword instructions

65

PARSE
If you specify the UPPER option, the data to be parsed is first translated to uppercase (that is, lowercase az to uppercase AZ). Otherwise, no uppercase translation takes place during the parsing. The following list describes the data for each variant of the PARSE instruction. PARSE ARG parses the string or strings passed to a program or internal routine as input arguments. See 47 for details and examples of the ARG instruction. Tip: You can also retrieve or check the argument strings to a REXX program or internal routine with the ARG built-in function (see 88). PARSE EXTERNAL In TSO/E, PARSE EXTERNAL reads from the: v Terminal (TSO/E foreground) v Input stream, which is SYSTSIN (TSO/E background). In non-TSO/E address spaces, PARSE EXTERNAL reads from the input stream as defined by the file name in the INDD field in the module name table (see 364). The system default is SYSTSIN. PARSE EXTERNAL returns a field based on the record that is read from the INDD file. If SYSTSIN has no data, the PARSE EXTERNAL instruction returns a null string. PARSE NUMERIC The current numeric controls (as set by the NUMERIC instruction) are available (see page63). These controls are in the order DIGITS FUZZ FORM. Example:
Parse Numeric Var1

After this instruction, Var1 would be equal to: 9 0 SCIENTIFIC. See NUMERIC on page 63 and the built-in functions DIGITS on page 99, FORM on page 102, and FUZZ on page 103. PARSE PULL parses the next string from the external data queue. If the external data queue is empty, PARSE PULL reads a line from the default input stream (the user's terminal), and the program pauses, if necessary, until a line is complete. You can add data to the head or tail of the queue by using the PUSH and QUEUE instructions, respectively. You can find the number of lines currently in the queue with the QUEUED built-in function. (See 109.) Other programs in the system can alter the queue and use it as a means of communication with programs written in REXX. See also 70 for the PULL instruction. PULL and PARSE PULL read from the data stack. In TSO/E, if the data stack is empty, PULL and PARSE PULL read from the: v Terminal (TSO/E foreground) v Input stream, which is SYSTSIN (TSO/E background). In non-TSO/E address spaces, if the data stack is empty, PULL and PARSE PULL read from the input stream as defined by the file name in the INDD field in the module name table (see 364). The system default is SYSTSIN. If SYSTSIN has no data, the PULL and PARSE PULL instructions return a null string. PARSE SOURCE parses data describing the source of the program running. The language processor returns a string that is fixed (does not change) while the program is running. The source string contains the following tokens:

66

z/OS V1R13.0 TSO/E REXX Reference

PARSE
1. The characters TSO 2. The string COMMAND, FUNCTION, or SUBROUTINE depending on whether the program was called as some kind of host command (for example, as an exec from TSO/E READY mode), or from a function call in an expression, or using the CALL instruction. 3. Usually, name of the exec in uppercase. If the name is not known, this token is a question mark (?). If the name is an extended execname, this field is the full name, possibly greater than 8-characters and not converted to uppercase. If the execname contains any blank characters (which is possible in an execname of file system), the blank characters are replaced by null characters (X'00') within this token. See Format of the exec block on page 447 and Format of the in-storage control block on page 449 for more information about how the exec load routine can load an extended execname. 4. Name of the DD from which the exec was loaded. If the name is not known, this token is a question mark (?). 5. Name of the data set from which the exec was loaded. If the name is not known, this token is a question mark (?). If the name contains any blank characters (which is possible in a dsname of file system), the blank characters are replaced by null characters (X'00') within this token. 6. Name of the exec as it was called, that is, the name is not folded to uppercase. If the name is not known, this token is a question mark (?). If the name returned in token3 is an extended name, this token is a question mark (?). 7. Initial (default) host command environment in uppercase. For example, this token may be TSO or MVS. 8. Name of the address space in uppercase. For example, the value may be MVS (non-TSO/E) or TSO/E or ISPF. If the exec was called from ISPF, the address space name is ISPF. The value is taken from the parameter block (see 358). Note that the initialization exit routines may change the name specified in the parameters module. If the name of the address space is not known, this token is a question mark (?). 9. Eight character user token. This is the token that is specified in the PARSETOK field in the parameters module (see 356). For example, the string parsed might look like one of the following:
TSO COMMAND PROGA SYSXR07 EGGERS.ECE.EXEC ? TSO TSO/E ? TSO SUBROUTINE PROGSUB SYSEXEC ? ? TSO ISPF ? TSO SUBROUTINE /u/cmddir/pgm.cmd PATH /u/cmddir/pgm.cmd ? SH OMVS OpenMVS

PARSE VALUE parses the data that is the result of evaluating expression. If you specify no expression, then the null string is used. Note that WITH is a subkeyword in this context and cannot be used as a symbol within expression. Thus, for example:
PARSE VALUE time() WITH hours : mins : secs

gets the current time and splits it into its constituent parts. PARSE VAR name parses the value of the variable name. The name must be a symbol that is valid
Chapter 3. Keyword instructions

67

PARSE
as a variable name (that is, it cannot start with a period or a digit). Note that the variable name is not changed unless it appears in the template, so that for example:
PARSE VAR string word1 string

removes the first word from string, puts it in the variable word1, and assigns the remainder back to string. Similarly
PARSE UPPER VAR string word1 string

in addition translates the data from string to uppercase before it is parsed. PARSE VERSION parses information describing the language level and the date of the language processor. This information consists of five blank-delimited words: 1. A word describing the language, which is the string REXX370 2. The language level description, for example, 3.46 3. Three tokens describing the language processor release date, for example, 31 May 2001.

PROCEDURE

PROCEDURE

EXPOSE

name (name)

PROCEDURE, within an internal routine (subroutine or function), protects variables by making them unknown to the instructions that follow it. After a RETURN instruction is processed, the original variables environment is restored and any variables used in the routine (that were not exposed) are dropped. (An exposed variable is one belonging to a caller of a routine that the PROCEDURE instruction has exposed. When the routine refers to or alters the variable, the original (caller's) copy of the variable is used.) An internal routine need not include a PROCEDURE instruction; in this case the variables it is manipulating are those the caller owns. If used, the PROCEDURE instruction must be the first instruction processed after the CALL or function invocation; that is, it must be the first instruction following the label. If you use the EXPOSE option, any variable specified by name is exposed. Any reference to it (including setting and dropping) refers to the variables environment the caller owns. Hence, the values of existing variables are accessible, and any changes are persistent even on RETURN from the routine. If name is not enclosed in parentheses, it identifies a variable you want to expose and must be a symbol that is a valid variable name, separated from any other name with one or more blanks. If parentheses enclose a single name, then, after the variable name is exposed, the value of name is immediately used as a subsidiary list of variables. (Blanks are not necessary either inside or outside the parentheses, but you can add them if

68

z/OS V1R13.0 TSO/E REXX Reference

PROCEDURE
desired.) This subsidiary list must follow the same rules as the original list (that is, valid variable names, separated by blanks) except that no parentheses are allowed. Variables are exposed in sequence from left to right. It is not an error to specify a name more than one time, or to specify a name that the caller has not used as a variable. Any variables in the main program that are not exposed are still protected. Therefore, some limited set of the caller's variables can be made accessible, and these variables can be changed (or new variables in this set can be created). All these changes are visible to the caller upon RETURN from the routine. Example:
/* This is the main REXX program */ j=1; z.1=a call toft say j k m /* Displays "1 7 M" exit /* This is a subroutine */ toft: procedure expose j k z.j say j k z.j /* Displays "1 K a" k=7; m=3 /* Note: M is not exposed return

*/

*/ */

Note that if Z.J in the EXPOSE list had been placed before J, the caller's value of J would not have been visible at that time, so Z.1 would not have been exposed. The variables in a subsidiary list are also exposed from left to right. Example:
/* This is the main REXX program */ j=1;k=6;m=9 a =j k m call test exit /* This is a subroutine test: procedure expose (a) say a j k m return */ /* Exposes A, J, K, and M /* Displays "j k m 1 6 9" */ */

You can use subsidiary lists to more easily expose a number of variables at one time or, with the VALUE built-in function, to manipulate dynamically named variables. Example:
/* This is the main REXX program */ c=11; d=12; e=13 Showlist=c d /* but not E */ call Playvars say c d e f /* Displays "11 New 13 9" */ exit /* This is a subroutine */ Playvars: procedure expose (showlist) f say word(showlist,2) /* Displays "d" */ say value(word(showlist,2),New) /* Displays "12" and sets new value */

Chapter 3. Keyword instructions

69

PROCEDURE
say value(word(showlist,2)) e=8 f=9 return /* Displays "New" /* E is not exposed /* F was explicitly exposed */ */ */

Specifying a stem as name exposes this stem and all possible compound variables whose names begin with that stem. (See page 23 for information about stems.) Example:
/* This is the main REXX program */ a.=11; i=13; j=15 i = i + 1 C.5 = FRED call lucky7 say a. a.1 i j c. c.5 say You should see 11 7 14 15 C. FRED exit lucky7:Procedure Expose i j a. c. /* This exposes I, J, and all variables whose /* names start with A. or C. A.1=7 /* This sets A.1 in the callers /* environment, even if it did not /* previously exist. return

*/ */ */ */ */

Variables may be exposed through several generations of routines, if desired, by ensuring that they are included on all intermediate PROCEDURE instructions. See page 48 and page 81 for details and examples of how routines are called.

PULL

PULL template_list

PULL reads a string from the head of the external data queue. It is just a short form of the instruction:
PARSE UPPER PULL template_list ;

The current head-of-queue is read as one string. Without a template_list specified, no further action is taken (and the string is thus effectively discarded). If specified, a template_list is usually a single template, which is a list of symbols separated by blanks or patterns or both. (The template_list can be several templates separated by commas, but PULL parses only one source string; if you specify several comma-separated templates, variables in templates other than the first one are assigned the null string.) The string is translated to uppercase (that is, lowercase az to uppercase AZ) and then parsed into variables according to the rules described in the section on parsing (see 169). Use the PARSE PULL instruction if you do not desire uppercase translation.

70

z/OS V1R13.0 TSO/E REXX Reference

PULL
The TSO/E implementation of the external data queue is the data stack. REXX execs that run in TSO/E and non-TSO/E address spaces can use the data stack. In TSO/E, if the data stack is empty, PULL reads from the: v Terminal (TSO/E foreground) v Input stream, which is SYSTSIN (TSO/E background). In non-TSO/E address spaces, if the data stack is empty, PULL reads from the input stream as defined by the file name in the INDD field in the module name table (see 364). The system default is SYSTSIN. If SYSTSIN has no data, the PULL instruction returns a null string. The length of each element you can place onto the data stack can be up to one byte less than 16 megabytes. Example:
Say Do you want to erase the file? Answer Yes or No: Pull answer . if answer=NO then say The file will not be erased.

Here the dummy placeholder, a period (.), is used on the template to isolate the first word the user enters. The QUEUED built-in function (see 109) returns the number of lines currently in the external data queue.

PUSH

PUSH expression

PUSH stacks the string resulting from the evaluation of expression LIFO (Last In, First Out) onto the external data queue. If you do not specify expression, a null string is stacked. Note: The TSO/E implementation of the external data queue is the data stack. The length of an element in the data stack can be up to one byte less than 16 megabytes. The data stack contains one buffer initially, but you can create additional buffers using the TSO/E REXX command MAKEBUF. Example:
a=Fred push push a 2 /* Puts a null line onto the queue */ /* Puts "Fred 2" onto the queue */

See 109 for the QUEUED built-in function that returns the number of lines currently in the external data queue.

Chapter 3. Keyword instructions

71

QUEUE

QUEUE

QUEUE expression

QUEUE appends the string resulting from expression to the tail of the external data queue. That is, it is added FIFO (First In, First Out). If you do not specify expression, a null string is queued. Note: The TSO/E implementation of the external data queue is the data stack. The length of an element in the data stack can be up to one byte less than 16 megabytes. The data stack contains one buffer initially, but you can create additional buffers using the TSO/E REXX command MAKEBUF. Example:
a=Toft queue a 2 /* Enqueues "Toft 2" */ queue /* Enqueues a null line behind the last */

See 109 for the QUEUED built-in function that returns the number of lines currently in the external data queue.

RETURN

RETURN expression

RETURN returns control (and possibly a result) from a REXX program or internal routine to the point of its invocation. If no internal routine (subroutine or function) is active, RETURN and EXIT are identical in their effect on the program that is being run. (See 58.) If a subroutine is being run (see the CALL instruction), expression (if any) is evaluated, control passes back to the caller, and the REXX special variable RESULT is set to the value of expression. If expression is omitted, the special variable RESULT is dropped (becomes uninitialized). The various settings saved at the time of the CALL (tracing, addresses, and so forth) are also restored. (See 48.) If a function is being processed, the action taken is identical, except that expression must be specified on the RETURN instruction. The result of expression is then used in the original expression at the point where the function was called. See 81 for more details.

72

z/OS V1R13.0 TSO/E REXX Reference

RETURN
If a PROCEDURE instruction was processed within the routine (subroutine or internal function), all variables of the current generation are dropped (and those of the previous generation are exposed) after expression is evaluated and before the result is used or assigned to RESULT.

SAY

SAY expression

SAY writes a line to the output stream. This typically displays it to the user, but the output destination can depend on the implementation. The result of expression may be of any length. If you omit expression, the null string is written. If a REXX exec runs in TSO/E foreground, SAY displays the expression on the terminal. The result from the SAY instruction is formatted to the current terminal line width (as defined by the TSO/E TERMINAL command) minus 1 character. In TSO/E background, SAY writes the expression to the output stream, which is SYSTSPRT. In either case, when the length is undefined (LINESIZE() returns 0), SAY uses a default line size of 80. If an exec runs in a non-TSO/E address space, SAY writes the expression to the output stream as defined by the OUTDD field in the module name table (see 364). The system default is SYSTSPRT. The ddname may be changed on an application basis or on a system basis. Example:
data=100 Say data divided by 4 => data/4 /* Displays: "100 divided by 4 => 25"

*/

SELECT

SELECT;

WHEN

expression ;

THEN ; END ;

instruction

OTHERWISE ; instruction

SELECT conditionally calls one of several alternative instructions.

Chapter 3. Keyword instructions

73

SELECT
Each expression after a WHEN is evaluated in turn and must result in 0 or 1. If the result is 1, the instruction following the associated THEN (which may be a complex instruction such as IF, DO, or SELECT) is processed and control then passes to the END. If the result is 0, control passes to the next WHEN clause. If none of the WHEN expressions evaluates to 1, control passes to the instructions, if any, after OTHERWISE. In this situation, the absence of an OTHERWISE causes an error (but note that you can omit the instruction list that follows OTHERWISE). Example:
balance=100 check=50 balance = balance - check Select when balance > 0 then say Congratulations! You still have balance dollars left. when balance = 0 then do say Attention, Balance is now zero! STOP all spending. say "You cut it close this month! Hope you do not have any" say "checks left outstanding." end Otherwise say "You have just overdrawn your account." say "Your balance now shows" balance "dollars." say "Oops! Hope the bank does not close your account." end /* Select */

Notes: 1. The instruction can be any assignment, command, or keyword instruction, including any of the more complex constructs such as DO, IF, or the SELECT instruction itself. 2. A null clause is not an instruction, so putting an extra semicolon (or label) after a THEN clause is not equivalent to putting a dummy instruction. The NOP instruction is provided for this purpose. 3. The symbol THEN cannot be used within expression, because the keyword THEN is treated differently, in that it need not start a clause. This allows the expression on the WHEN clause to be ended by the THEN without a ; (delimiter) being required.

SIGNAL

SIGNAL

labelname expression VALUE OFF ERROR FAILURE HALT NOVALUE SYNTAX ON ERROR FAILURE HALT NOVALUE SYNTAX

NAME

trapname

74

z/OS V1R13.0 TSO/E REXX Reference

SIGNAL
SIGNAL causes an unusual change in the flow of control (if you specify labelname or VALUE expression), or controls the trapping of certain conditions (if you specify ON or OFF). To control trapping, you specify OFF or ON and the condition you want to trap. OFF turns off the specified condition trap. ON turns on the specified condition trap. All information about condition traps is contained in Chapter 7, Conditions and condition traps, on page 195. To change the flow of control, a label name is derived from labelname or taken from the result of evaluating the expression after VALUE. The labelname you specify must be a literal string or symbol that is taken as a constant. If you use a symbol for labelname, the search is independent of alphabetic case. If you use a literal string, the characters should be in uppercase. This is because the language processor translates all labels to uppercase, regardless of how you enter them in the program. Similarly, for SIGNAL VALUE, the expression must evaluate to a string in uppercase or the language processor does not find the label. You can omit the subkeyword VALUE if expression does not begin with a symbol or literal string (that is, if it starts with a special character, such as an operator character or parenthesis). All active pending DO, IF, SELECT, and INTERPRET instructions in the current routine are then ended (that is, they cannot be resumed). Control then passes to the first label in the program that matches the given name, as though the search had started from the top of the program. Example:
Signal fred; /* Transfer control to label FRED below */ .... .... Fred: say Hi!

Because the search effectively starts at the top of the program, if duplicates are present, control always passes to the first occurrence of the label in the program. When control reaches the specified label, the line number of the SIGNAL instruction is assigned to the special variable SIGL. This can aid debugging because you can use SIGL to determine the source of a transfer of control to a label. Using SIGNAL VALUE The VALUE form of the SIGNAL instruction allows a branch to a label whose name is determined at the time of execution. This can safely effect a multi-way CALL (or function call) to internal routines because any DO loops, and so forth, in the calling routine are protected against termination by the call mechanism. Example:
fred=PETE call multiway fred, 7 .... .... exit Multiway: procedure arg label .

signal value label .... Pete: say arg(1) '!' arg(2) /* Displays: "PETE ! 7" return

/* One word, uppercase */ /* Can add checks for valid labels here */ /* Transfer control to wherever */ */

Chapter 3. Keyword instructions

75

TRACE

TRACE

TRACE number Normal All Commands Error Failure Intermediates Labels Off Results Scan

? !

Or, alternatively:

TRACE string symbol expression VALUE

TRACE controls the tracing action (that is, how much is displayed to the user) during processing of a REXX program. (Tracing describes some or all of the clauses in a program, producing descriptions of clauses as they are processed.) TRACE is mainly used for debugging. Its syntax is more concise than that of other REXX instructions because TRACE is usually entered manually during interactive debugging. (This is a form of tracing in which the user can interact with the language processor while the program is running.) For this use, economy of key strokes is especially convenient. If specified, the number must be a whole number. The string or expression evaluates to: v A numeric option v One of the valid prefix or alphabetic character (word) options described later v Null The symbol is taken as a constant, and is, therefore: v A numeric option v One of the valid prefix or alphabetic character (word) options described later The option that follows TRACE or the result of evaluating expression determines the tracing action. You can omit the subkeyword VALUE if expression does not begin with a symbol or a literal string (that is, if it starts with a special character, such as an operator or parenthesis).

76

z/OS V1R13.0 TSO/E REXX Reference

TRACE

Alphabetic character (word) options

Although you can enter the word in full, only the capitalized and highlighted letter is needed; all characters following it are ignored. That is why these are referred to as alphabetic character options. TRACE actions correspond to the alphabetic character options as follows: All Commands Traces (that is, displays) all clauses before execution. Traces all commands before execution. If the command results in an error or failure, 3 then tracing also displays the return code from the command. Traces any command resulting in an error or failure 3 after execution, together with the return code from the command. Traces any command resulting in a failure 3 after execution, together with the return code from the command. This is the same as the Normal option. Traces all clauses before execution. Also traces intermediate results during evaluation of expressions and substituted names. Traces only labels passed during execution. This is especially useful with debug mode, when the language processor pauses after each label. It also helps the user to note all internal subroutine calls and transfers of control because of the SIGNAL instruction. Traces any command resulting in a negative return code after execution, together with the return code from the command. This is the default setting. Traces nothing and resets the special prefix options (described later) to OFF. Please consider the Note given with the description of the MSG function (see 140. Traces all clauses before execution. Displays final results (contrast with Intermediates, preceding) of evaluating an expression. Also displays values assigned during PULL, ARG, and PARSE instructions. This setting is suggested for general debugging. Traces all remaining clauses in the data without them being processed. Basic checking (for missing ENDs and so forth) is carried out, and the trace is formatted as usual. This is valid only if the TRACE S clause itself is not nested in any other instruction (including INTERPRET or interactive debug) or in an internal routine.

Error Failure

Intermediates Labels

Normal

Off

Results

Scan

Prefix options
The prefixes ! and ? are valid either alone or with one of the alphabetic character options. You can specify both prefixes, in any order, on one TRACE instruction. You can specify a prefix more than one time, if desired. Each occurrence of a prefix on an instruction reverses the action of the previous prefix. The prefix(es) must immediately precede the option (no intervening blanks). The prefixes ! and ? modify tracing and execution as follows: ! Inhibits host command execution. During regular execution, a TRACE

3. See 25 for definitions of error and failure. Chapter 3. Keyword instructions

77

TRACE
instruction with a prefix of ! suspends execution of all subsequent host commands. For example, TRACE !C causes commands to be traced but not processed. As each command is bypassed, the REXX special variable RC is set to 0. You can use this action for debugging potentially destructive programs. (Note that this does not inhibit any commands entered manually while in interactive debug. These are always processed.) You can switch off command inhibition, when it is in effect, by issuing a TRACE instruction with a prefix !. Repeated use of the ! prefix, therefore, switches you alternately in or out of command inhibition mode. Or, you can turn off command inhibition at any time by issuing TRACE O or TRACE with no options. ? Controls interactive debug. During usual execution, a TRACE option with a prefix of ? causes interactive debug to be switched on. (See Interactive debugging of programs on page 251 for full details of this facility.) While interactive debug is on, interpretation pauses after most clauses that are traced. For example, the instruction TRACE ?E makes the language processor pause for input after executing any command that returns an error (that is, a nonzero return code). Any TRACE instructions in the program being traced are ignored. (This is so that you are not taken out of interactive debug unexpectedly.) You can switch off interactive debug in several ways: v Entering TRACE O turns off all tracing. v Entering TRACE with no options restores the defaultsit turns off interactive debug but continues tracing with TRACE Normal (which traces any failing command after execution) in effect. v Entering TRACE ? turns off interactive debug and continues tracing with the current option. v Entering a TRACE instruction with a ? prefix before the option turns off interactive debug and continues tracing with the new option. Using the ? prefix, therefore, switches you alternately in or out of interactive debug. (Because the language processor ignores any further TRACE statements in your program after you are in interactive debug, use CALL TRACE ? to turn off interactive debug.) Tip: The TSO/E REXX immediate command TS and the EXECUTIL TS command can also be used to enter interactive debug. See Chapter 10, TSO/E REXX commands, on page 215.

Numeric options
If interactive debug is active and if the option specified is a positive whole number (or an expression that evaluates to a positive whole number), that number indicates the number of debug pauses to be skipped over. (See separate section in Interactive debugging of programs on page 251, for further information.) However, if the option is a negative whole number (or an expression that evaluates to a negative whole number), all tracing, including debug pauses, is temporarily inhibited for the specified number of clauses. For example, TRACE -100 means that the next 100 clauses that would usually be traced are not, in fact, displayed. After that, tracing resumes as before.

Tracing tips
1. When a loop is being traced, the DO clause itself is traced on every iteration of the loop.

78

z/OS V1R13.0 TSO/E REXX Reference

TRACE
2. You can retrieve the trace actions currently in effect by using the TRACE built-in function (see TRACE on page 115). 3. If available at the time of execution, comments associated with a traced clause are included in the trace, as are comments in a null clause, if you specify TRACE A, R, I, or S. 4. Commands traced before execution always have the final value of the command (that is, the string passed to the environment), and the clause generating it produced in the traced output. 5. Trace actions are automatically saved across subroutine and function calls. See the CALL instruction (48) for more details.

A typical example
One of the most common traces you will use is:
TRACE ?R /* Interactive debug is switched on if it was off, */ /* and tracing Results of expressions begins. */

Tracing may be switched on, without requiring modification to a program, by using the EXECUTIL TS command. Tracing may also be turned on or off asynchronously, (that is, while an exec is running) using the TS and TE immediate commands from attention mode. See 253 for the description of these facilities.

Format of TRACE output

Every clause traced appears with automatic formatting (indentation) according to its logical depth of nesting and so forth. The language processor may replace any control codes in the encoding of data (for example, EBCDIC values less than '40'x) with a question mark (?) to avoid console interference. Results (if requested) are indented an extra two spaces and are enclosed in double quotation marks so that leading and trailing blanks are apparent. A line number precedes the first clause traced on any line. If the line number is greater than 99999, the language processor truncates it on the left, and the ? prefix indicates the truncation. For example, the line number 100354 appears as ?00354. All lines displayed during tracing have a three-character prefix to identify the type of data being traced. These can be: *-* +++ Identifies the source of a single clause, that is, the data actually in the program. Identifies a trace message. This may be the nonzero return code from a command, the prompt message when interactive debug is entered, an indication of a syntax error when in interactive debug, or the traceback clauses after a syntax error in the program (see below). Identifies the result of an expression (for TRACE R) or the value assigned to a variable during parsing, or the value returned from a subroutine call. Identifies the value assigned to a placeholder during parsing (see 170).

>>> >.>

The following prefixes are used only if TRACE Intermediates is in effect: >C> The data traced is the name of a compound variable, traced after substitution and before use, provided that the name had the value of a variable substituted into it. The data traced is the result of a function call.

>F>

Chapter 3. Keyword instructions

79

TRACE
>L> >O> >P> >V> The data traced is a literal (string, uninitialized variable, or constant symbol). The data traced is the result of an operation on two terms. The data traced is the result of a prefix operation. The data traced is the contents of a variable.

If no option is specified on a TRACE instruction, or if the result of evaluating the expression is null, the default tracing actions are restored. The defaults are TRACE N, command inhibition (!) off, and interactive debug (?) off. Following a syntax error that SIGNAL ON SYNTAX does not trap, the clause in error is always traced. Any CALL or INTERPRET or function invocations active at the time of the error are also traced. If an attempt to transfer control to a label that could not be found caused the error, that label is also traced. The special trace prefix +++ identifies these traceback lines.

UPPER

UPPER

variable

UPPER translates the contents of one or more variables to uppercase. The variables are translated in sequence from left to right. The variable is a symbol, separated from any other variables by one or more blanks or comments. Specify only simple symbols and compound symbols. (See 21.) Using this instruction is more convenient than repeatedly invoking the TRANSLATE built-in function. Example:
a1=Hello; Upper a1 b1 say a1 b1 b1=there /* Displays "HELLO THERE" */

An error is signalled if a constant symbol or a stem is encountered. Using an uninitialized variable is not an error, and has no effect, except that it is trapped if the NOVALUE condition (SIGNAL ON NOVALUE) is enabled.

80

z/OS V1R13.0 TSO/E REXX Reference

Chapter 4. Functions
A function is an internal, built-in, or external routine that returns a single result string. (A subroutine is a function that is an internal, built-in, or external routine that may or may not return a result and that is called with the CALL instruction.)

Syntax
A function call is a term in an expression that calls a routine that carries out some procedures and returns a string. This string replaces the function call in the continuing evaluation of the expression. You can include function calls to internal and external routines in an expression anywhere that a data term (such as a string) would be valid, using the notation:
, function_name( expression )

The function_name is a literal string or a single symbol, which is taken to be a constant. There can be up to an implementation-defined maximum number of expressions, separated by commas, between the parentheses. In TSO/E, the implementation maximum is up to 20 expressions. These expressions are called the arguments to the function. Each argument expression may include further function calls. Note that the left parenthesis must be adjacent to the name of the function, with no blank in between, or the construct is not recognized as a function call. (A blank operator would be assumed at this point instead.) Only a comment (which has no effect) can appear between the name and the left parenthesis. The arguments are evaluated in turn from left to right and the resulting strings are all then passed to the function. This then runs some operation (usually dependent on the argument strings passed, though arguments are not mandatory) and eventually returns a single character string. This string is then included in the original expression just as though the entire function reference had been replaced by the name of a variable whose value is that returned data. For example, the function SUBSTR is built-in to the language processor (see page 112) and could be used as:
N1=abcdefghijk Z1=Part of N1 is: substr(N1,2,7) /* Sets Z1 to Part of N1 is: bcdefgh */

A function may have a variable number of arguments. You need to specify only those that are required. For example, SUBSTR(ABCDEF,4) would return DEF.

Copyright IBM Corp. 1988, 2011

81

Functions

Functions and subroutines

The function calling mechanism is identical with that for subroutines. The only difference between functions and subroutines is that functions must return data, whereas subroutines need not. The following types of routines can be called as functions: Internal If the routine name exists as a label in the program, the current processing status is saved, so that it is later possible to return to the point of invocation to resume execution. Control is then passed to the first label in the program that matches the name. As with a routine called by the CALL instruction, various other status information (TRACE and NUMERIC settings and so forth) is saved too. See the CALL instruction (page 48) for details about this. You can use SIGNAL and CALL together to call an internal routine whose name is determined at the time of execution; this is known as a multi-way call (see page 75). If you are calling an internal routine as a function, you must specify an expression in any RETURN instruction to return from it. This is not necessary if it is called as a subroutine. Example:
/* Recursive internal function execution... */ arg x say x! = factorial(x) exit factorial: procedure /* Calculate factorial by arg n /* recursive invocation. if n=0 then return 1 return factorial(n-1) * n */ */

FACTORIAL is unusual in that it calls itself (this is recursive invocation). The PROCEDURE instruction ensures that a new variable n is created for each invocation. Note: When there is a search for a routine, the language processor currently scans the statements in the REXX program to locate the internal label. During the search, the language processor may encounter a syntax error. As a result, a syntax error may be raised on a statement different from the original line being processed. Built-in External These functions are always available and are defined in the next section of this manual. (See pages 87 to 123.) You can write or use functions that are external to your program and to the language processor. An external routine can be written in any language (including REXX) that supports the system-dependent interfaces the language processor uses to call it. You can call a REXX program as a function and, in this case, pass more than one argument string. The ARG or PARSE ARG instructions or the ARG built-in function can retrieve these argument strings. When called as a function, a program must return data to the caller. For information about writing external functions and subroutines and the system dependent interfaces, see External functions and subroutines, and function packages on page 288.

82

z/OS V1R13.0 TSO/E REXX Reference

Functions
Notes: 1. Calling an external REXX program as a function is similar to calling an internal routine. The external routine is, however, an implicit PROCEDURE in that all the caller's variables are always hidden and the status of internal values (NUMERIC settings and so forth) start with their defaults (rather than inheriting those of the caller). 2. Other REXX programs can be called as functions. You can use either EXIT or RETURN to leave the called REXX program, and in either case you must specify an expression. 3. With care, you can use the INTERPRET instruction to process a function with a variable function name. However, you should avoid this if possible because it reduces the clarity of the program.

Search order
The search order for functions is: internal routines take precedence, then built-in functions, and finally external functions. Internal routines are not used if the function name is given as a literal string (that is, specified in quotation marks); in this case the function must be built-in or external. This lets you usurp the name of, say, a built-in function to extend its capabilities, yet still be able to call the built-in function when needed. Example:
/* This internal DATE function modifies the /* default for the DATE function to standard date. date: procedure arg in if in= then in=Standard return DATE(in) */ */

Built-in functions have uppercase names, and so the name in the literal string must be in uppercase for the search to succeed, as in the example. The same is usually true of external functions. The search order for external functions and subroutines follows. 1. Check the following function packages defined for the language processor environment: v User function packages v Local function packages v System function packages 2. If a match to the function name is not found, the function search order flag (FUNCSOFL) is checked. The FUNCSOFL flag (see page 359) indicates whether load libraries are searched before the search for a REXX exec. If the flag is off, check the load libraries. If a match to the function name is not found, search for a REXX program. If the flag is on, search for a REXX program. If a match to the function name is not found, check the load libraries. By default, the FUNCSOFL flag is off, which means that load libraries are searched before the search for a REXX exec. You can use TSO/E EXECUTIL RENAME to change functions in a function package directory. For more information, see EXECUTIL RENAME on page 235. 3. TSO/E uses the following order to search the load libraries:
Chapter 4. Functions

83

Functions
v Job pack area v ISPLLIB. If the user entered LIBDEF ISPLLIB ..., the system searches the new alternate library defined by LIBDEF followed by the ISPLLIB library. v Task library and all preceding task libraries v Step library. If there is no step library, the job library is searched, if one exists. v Link pack area (LPA) v Link library 4. The following list describes the steps used to search for a REXX exec for a function or subroutine call: Restriction: VLF is not searched for REXX execs called as functions or subroutines. a. Search the ddname from which the exec that is calling the function or subroutine was loaded. For example, if the calling exec was loaded from the DD MYAPPL, the system searches MYAPPL for the function or subroutine. Note: If the calling exec is running in a non-TSO/E address space and the exec (function or subroutine) being searched for was not found, the search for an exec ends. Note that depending on the setting of the FUNCSOFL flag, the load libraries may or may not have already been searched at this point. b. Search any exec libraries as defined by the TSO/E ALTLIB command c. Check the setting of the NOLOADDD flag (see page 362). v If the NOLOADDD flag is off, search any data sets that are allocated to SYSEXEC. (SYSEXEC is the default system file in which you can store REXX execs; it is the default ddname specified in the LOADDD field in the module name table. See page 364). If the function or subroutine is not found, search the data sets allocated to SYSPROC. If the function or subroutine is not found, the search for an exec ends. Note that depending on the setting of the FUNCSOFL flag, the load libraries may or may not have already been searched at this point. v If the NOLOADDD flag is on, search any data sets that are allocated to SYSPROC. If the function or subroutine is not found, the search for an exec ends. Note that depending on the setting of the FUNCSOFL flag, the load libraries may or may not have already been searched at this point. Note: With the defaults that TSO/E provides, the NOLOADDD flag is off. This means that SYSEXEC is searched before SYSPROC. You can control the NOLOADDD flag using the TSO/E REXX EXECUTIL command. For more information, see EXECUTIL on page 231. Figure 8 illustrates how a call to an external function or subroutine is handled. After the user, local, and system function packages, and optionally, the load libraries are searched, if the function or subroutine was not found, the system searches for a REXX exec. The search for an exec is shown in part 2 of the figure.

84

z/OS V1R13.0 TSO/E REXX Reference

Functions
START

Search: 1. User packages 2. Local packages 3. System packages

Yes

Was a match to the function name found? No

Is FUNCSOFL flag on or off? Off

On

Search for an exec.

Search load libraries.

If exec was not found, search load libraries.

Yes

Was function found? No

Search for an exec.

Yes

Was function found? No

Finish

Error

Figure 8. External routine resolution and execution (Part 1 of 2)

Chapter 4. Functions

85

Functions

SEARCH FOR AN EXEC

Search DD from which calling exec was loaded.

If exec was not found, is the calling exec executing in a TSO/E address space? Yes

No

Search for exec ends. Exec not found.

Search any exec libraries as defined by ALTLIB (for example, SYSUPROC).

If exec was not found, is NOLOADDD flag on or off? Off

On

Search SYSPROC.

Search library defined in LOADDD field (for example, SYSEXEC).

If exec was not found, search SYSPROC.

Figure 8. External routine resolution and execution (Part 2 of 2)

Errors during execution

If an external or built-in function detects an error of any kind, the language processor is informed, and a syntax error results. Execution of the clause that included the function call is, therefore, ended. Similarly, if an external function fails to return data correctly, the language processor detects this and reports it as an error. If a syntax error occurs during the execution of an internal function, it can be trapped (using SIGNAL ON SYNTAX) and recovery may then be possible. If the error is not trapped, the program is ended.

86

z/OS V1R13.0 TSO/E REXX Reference

Functions

Built-in functions
REXX provides a rich set of built-in functions, including character manipulation, conversion, and information functions. There are six other built-in functions that TSO/E provides: EXTERNALS, FIND, INDEX, JUSTIFY, LINESIZE, and USERID. If you plan to write REXX programs that run on other SAA environments, note that these functions are not available to all the environments. In this section, these six built-in functions are identified as non-SAA functions. In addition to the built-in functions, TSO/E also provides TSO/E external functions that you can use to perform different tasks. These functions are described in TSO/E external functions on page 123. The following are general notes on the built-in functions: v The parentheses in a function are always needed, even if no arguments are required. The first parenthesis must follow the name of the function with no space in between. v The built-in functions work internally with NUMERIC DIGITS 9 and NUMERIC FUZZ 0 and are unaffected by changes to the NUMERIC settings, except where stated. This is not true for RANDOM. v Any argument named as a string may be a null string. v If an argument specifies a length, it must be a positive whole number or zero. If it specifies a start character or word in a string, it must be a positive whole number, unless otherwise stated. v Where the last argument is optional, you can always include a comma to indicate you have omitted it; for example, DATATYPE(1,), like DATATYPE(1), would return NUM. v If you specify a pad character, it must be exactly one character long. (A pad character extends a string, usually on the right. For an example, see the LEFT built-in function on page 105.) v If a function has an option you can select by specifying the first character of a string, that character can be in upper- or lowercase. v A number of the functions described in this chapter support DBCS. A complete list and descriptions of these functions are in Appendix A, Double-byte character set (DBCS) support, on page 481.

ABBREV (Abbreviation)

ABBREV(information,info ,length

returns 1 if info is equal to the leading characters of information and the length of info is not less than length. Returns 0 if either of these conditions is not met. If you specify length, it must be a positive whole number or zero. The default for length is the number of characters in info. Here are some examples:
Chapter 4. Functions

87

Functions
ABBREV(Print,Pri) ABBREV(PRINT,Pri) ABBREV(PRINT,PRI,4) ABBREV(PRINT,PRY) ABBREV(PRINT,) ABBREV(PRINT,,1) -> -> -> -> -> -> 1 0 0 0 1 0

Example: A null string always matches if a length of 0 (or the default) is used. This allows a default keyword to be selected automatically if desired; for example:
say Enter option:; pull option . select /* keyword1 is to be the default */ when abbrev(keyword1,option) then ... when abbrev(keyword2,option) then ... ... otherwise nop; end;

ABS (Absolute Value)

ABS(number)

returns the absolute value of number. The result has no sign and is formatted according to the current NUMERIC settings. Here are some examples:
ABS(12.3) ABS( -0.307) -> -> 12.3 0.307

ADDRESS

ADDRESS()

returns the name of the environment to which commands are currently being submitted. See the ADDRESS instruction (page 46) for more information. Trailing blanks are removed from the result. Here are some examples:
ADDRESS() ADDRESS() -> -> TSO MVS /* default under TSO/E */ /* default under MVS */

ARG (Argument)

ARG( n ,option

88

z/OS V1R13.0 TSO/E REXX Reference

Functions
returns an argument string or information about the argument strings to a program or internal routine. If you do not specify n, the number of arguments passed to the program or internal routine is returned. If you specify only n, the nth argument string is returned. If the argument string does not exist, the null string is returned. The n must be a positive whole number. If you specify option, ARG tests for the existence of the nth argument string. The following are valid options. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.) Exists Omitted returns 1 if the nth argument exists; that is, if it was explicitly specified when the routine was called. Returns 0 otherwise. returns 1 if the nth argument was omitted; that is, if it was not explicitly specified when the routine was called. Returns 0 otherwise.

Here are some examples:

/* following ARG() ARG(1) ARG(2) ARG(1,e) ARG(1,O) /* following ARG() ARG(1) ARG(2) ARG(3) ARG(n) ARG(1,e) ARG(2,E) ARG(2,O) ARG(3,o) ARG(4,o) "Call -> -> -> -> -> "Call -> -> -> -> -> -> -> -> -> -> name;" (no arguments) */ 0 0 1 name a,,b;" */ 3 a b /* for n>=4 */ 1 0 1 0 1

Notes: 1. The number of argument strings is the largest number n for which ARG(n,e) would return 1 or 0 if there are no explicit argument strings. That is, it is the position of the last explicitly specified argument string. 2. Programs called as commands can have only 0 or 1 argument strings. The program has 0 argument strings if it is called with the name only and has 1 argument string if anything else (including blanks) is included with the command. 3. You can retrieve and directly parse the argument strings to a program or internal routine with the ARG or PARSE ARG instructions. (See pages 47, 65, and 169.)

Chapter 4. Functions

89

Functions

BITAND (Bit by Bit AND)

BITAND(string1 , string2 ,pad

returns a string composed of the two input strings logically ANDed together, bit by bit. (The encoding of the strings are used in the logical operation.) The length of the result is the length of the longer of the two strings. If no pad character is provided, the AND operation stops when the shorter of the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial result. If pad is provided, it extends the shorter of the two strings on the right before carrying out the logical operation. The default for string2 is the zero length (null) string. Here are some examples:
BITAND(12x) BITAND(73x,27x) BITAND(13x,5555x) BITAND(13x,5555x,74x) BITAND(pQrS,,BFx) -> -> -> -> -> 12x 23x 1155x 1154x pqrs

/* EBCDIC

*/

BITOR (Bit by Bit OR)

BITOR(string1 , string2 ,pad

returns a string composed of the two input strings logically inclusive-ORed together, bit by bit. (The encoding of the strings are used in the logical operation.) The length of the result is the length of the longer of the two strings. If no pad character is provided, the OR operation stops when the shorter of the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial result. If pad is provided, it extends the shorter of the two strings on the right before carrying out the logical operation. The default for string2 is the zero length (null) string. Here are some examples:
BITOR(12x) BITOR(15x,24x) BITOR(15x,2456x) BITOR(15x,2456x,F0x) BITOR(1111x,,4Dx) BITOR(Fred,,40x) -> -> -> -> -> -> 12x 35x 3556x 35F6x 5D5Dx FRED

/* EBCDIC

*/

90

z/OS V1R13.0 TSO/E REXX Reference

Functions

BITXOR (Bit by Bit Exclusive OR)

BITXOR(string1 , string2 ,pad

returns a string composed of the two input strings logically eXclusive-ORed together, bit by bit. (The encoding of the strings are used in the logical operation.) The length of the result is the length of the longer of the two strings. If no pad character is provided, the XOR operation stops when the shorter of the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial result. If pad is provided, it extends the shorter of the two strings on the right before carrying out the logical operation. The default for string2 is the zero length (null) string. Here are some examples:
BITXOR(12x) BITXOR(12x,22x) BITXOR(1211x,22x) BITXOR(1111x,444444x) BITXOR(1111x,444444x,40x) BITXOR(1111x,,4Dx) BITXOR(C711x,222222x, ) -> 12x -> 30x -> 3011x -> 555544x -> 555504x -> 5C5Cx -> E53362x /* EBCDIC */

B2X (Binary to Hexadecimal)

B2X(binary_string)

returns a string, in character format, that represents binary_string converted to hexadecimal. The binary_string is a string of binary (0 or 1) digits. It can be of any length. You can optionally include blanks in binary_string (at four-digit boundaries only, not leading or trailing) to aid readability; they are ignored. The returned string uses uppercase alphabetics for the values AF, and does not include blanks. If binary_string is the null string, B2X returns a null string. If the number of binary digits in binary_string is not a multiple of four, then up to three 0 digits are added on the left before the conversion to make a total that is a multiple of four. Here are some examples:
B2X(11000011) B2X(10111) B2X(101) B2X(1 1111 0000) -> -> -> -> C3 17 5 1F0

Chapter 4. Functions

91

Functions
You can combine B2X with the functions X2D and X2C to convert a binary number into other forms. For example:
X2D(B2X(10111)) -> 23 /* decimal 23 */

CENTER/CENTRE

CENTER( CENTRE(

string,length ,pad

returns a string of length length with string centered in it, with pad characters added as necessary to make up length. The length must be a positive whole number or zero. The default pad character is blank. If the string is longer than length, it is truncated at both ends to fit. If an odd number of characters are truncated or added, the right-hand end loses or gains one more character than the left-hand end. Here are some examples:
CENTER(abc,7) CENTER(abc,8,-) CENTRE(The blue sky,8) CENTRE(The blue sky,7) -> -> -> -> ABC --ABC--- e blue s e blue

To avoid errors because of the difference between British and American spellings, this function can be called either CENTRE or CENTER.

COMPARE

COMPARE(string1,string2 ,pad

returns 0 if the strings, string1 and string2, are identical. Otherwise, returns the position of the first character that does not match. The shorter string is padded on the right with pad if necessary. The default pad character is a blank. Here are some examples:
COMPARE(abc,abc) COMPARE(abc,ak) COMPARE(ab ,ab) COMPARE(ab ,ab, ) COMPARE(ab ,ab,x) COMPARE(ab-- ,ab,-) -> -> -> -> -> -> 0 2 0 0 3 5

92

z/OS V1R13.0 TSO/E REXX Reference

Functions

CONDITION

CONDITION( option

returns the condition information associated with the current trapped condition. (See Chapter 7, Conditions and condition traps, on page 195 for a description of condition traps.) You can request the following pieces of information: v The name of the current trapped condition v Any descriptive string associated with that condition v The instruction processed as a result of the condition trap (CALL or SIGNAL) v The status of the trapped condition. To select the information to return, use the following options. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.) Condition name Description returns the name of the current trapped condition. returns any descriptive string associated with the current trapped condition. See page 199 for the list of possible strings. If no description is available, returns a null string. returns either CALL or SIGNAL, the keyword for the instruction processed when the current condition was trapped. This is the default if you omit option. returns the status of the current trapped condition. This can change during processing, and is either: ON - the condition is enabled OFF - the condition is disabled DELAY - any new occurrence of the condition is delayed or ignored.

Instruction

Status

If no condition has been trapped, then the CONDITION function returns a null string in all four cases. Here are some examples:
CONDITION() CONDITION(C) CONDITION(I) CONDITION(D) CONDITION(S) -> -> -> -> -> CALL /* perhaps */ FAILURE CALL FailureTest OFF /* perhaps */

The CONDITION function returns condition information that is saved and restored across subroutine calls (including those a CALL ON condition trap causes). Therefore, after a subroutine called with CALL ON trapname has returned, the current trapped condition reverts to the condition that was current before the CALL took place (which may be none). CONDITION returns the values it returned before the condition was trapped.

Chapter 4. Functions

93

Functions

COPIES

COPIES(string,n)

returns n concatenated copies of string. The n must be a positive whole number or zero. Here are some examples:
COPIES(abc,3) COPIES(abc,0) -> -> abcabcabc

C2D (Character to Decimal)

C2D(string ,n

returns the decimal value of the binary representation of string. If the result cannot be expressed as a whole number, an error results. That is, the result must not have more digits than the current setting of NUMERIC DIGITS. If you specify n, it is the length of the returned result. If you do not specify n, string is processed as an unsigned binary number. If string is null, returns 0. Here are some examples:
C2D(09X) C2D(81X) C2D(FF81X) C2D() C2D(a) -> -> -> -> -> 9 129 65409 0 129

/*

EBCDIC

*/

If you specify n, the string is taken as a signed number expressed in n characters. The number is positive if the leftmost bit is off, and negative, in two's complement notation, if the leftmost bit is on. In both cases, it is converted to a whole number, which may, therefore, be negative. The string is padded on the left with '00'x characters (note, not sign-extended), or truncated on the left to n characters. This padding or truncation is as though RIGHT(string,n,00x) had been processed. If n is 0, C2D always returns 0. Here are some examples:
C2D(81X,1) C2D(81X,2) C2D(FF81X,2) C2D(FF81X,1) C2D(FF7FX,1) C2D(F081X,2) C2D(F081X,1) C2D(0031X,0) -> -> -> -> -> -> -> -> -127 129 -127 -127 127 -3967 -127 0

94

z/OS V1R13.0 TSO/E REXX Reference

Functions
Implementation maximum: The input string cannot have more than 250 characters that are significant in forming the final result. Leading sign characters ('00'x and 'FF'x) do not count toward this total.

C2X (Character to Hexadecimal)

C2X(string)

returns a string, in character format, that represents string converted to hexadecimal. The returned string contains twice as many bytes as the input string. For example, on an EBCDIC system, C2X(1) returns F1 because the EBCDIC representation of the character 1 is 'F1'X. The string returned uses uppercase alphabetics for the values AF and does not include blanks. The string can be of any length. If string is null, returns a null string. Here are some examples:
C2X(72s) C2X(0123X) -> -> F7F2A2 /* C6F7C6F2C1F2X in EBCDIC */ 0123 /* F0F1F2F3X in EBCDIC */

DATATYPE

DATATYPE(string ,type

returns NUM if you specify only string and if string is a valid REXX number that can be added to 0 without error; returns CHAR if string is not a valid number. If you specify type, returns 1 if string matches the type; otherwise returns 0. If string is null, the function returns 0 (except when type is X, which returns 1 for a null string). The following are valid types. (Only the capitalized and highlighted letter is needed; all characters following it are ignored. Note that for the hexadecimal option, you must start your string specifying the name of the option with x rather than h.) Alphanumeric returns 1 if string contains only characters from the ranges az, AZ, and 09. Binary C Dbcs Lowercase Mixed case returns 1 if string contains only the characters 0 or 1 or both. returns 1 if string is a mixed SBCS/DBCS string. returns 1 if string is a DBCS-only string enclosed by SO and SI bytes. returns 1 if string contains only characters from the range az. returns 1 if string contains only characters from the ranges az and AZ.
Chapter 4. Functions

95

Functions
Number Symbol returns 1 if string is a valid REXX number. returns 1 if string contains only characters that are valid in REXX symbols. (See page 10.) Note that both uppercase and lowercase alphabetics are permitted. returns 1 if string contains only characters from the range AZ. returns 1 if string is a REXX whole number under the current setting of NUMERIC DIGITS. heXadecimal returns 1 if string contains only characters from the ranges af, AF, 09, and blank (as long as blanks appear only between pairs of hexadecimal characters). Also returns 1 if string is a null string, which is a valid hexadecimal string.

Uppercase Whole number

Here are some examples:

DATATYPE( 12 ) DATATYPE() DATATYPE(123*) DATATYPE(12.3,N) DATATYPE(12.3,W) DATATYPE(Fred,M) DATATYPE(,M) DATATYPE(Fred,L) DATATYPE(?20K,s) DATATYPE(BCd3,X) DATATYPE(BC d3,X) -> -> -> -> -> -> -> -> -> -> -> NUM CHAR CHAR 1 0 1 0 0 1 1 1

The DATATYPE function tests the meaning or type of characters in a string, independent of the encoding of those characters (for example, ASCII or EBCDIC).

DATE

DATE ( date_format1 ,input_date ,date_format2 ,input_date ,date_format2

returns, by default, the local date in the format: dd mon yyyy (day, month, yearfor example, 25 Dec 2001), with no leading zero or blank on the day. Otherwise, the string input_date is converted to the format specified by date_format1. date_format2 can be specified to define the current format of input_date. The default for date_format1 and date_format2 is Normal. input_date must not have a leading zero or blank. You can use the following options to obtain specific date formats. (Only the bold character is needed; all other characters are ignored.) Base the number of complete days (that is, not including the current day) since and including the base date, 1 January 0001, in the format: dddddd (no leading zeros or blanks). The expression

96

z/OS V1R13.0 TSO/E REXX Reference

Functions
DATE('B')//7 returns a number in the range 06 that corresponds to the current day of the week, where 0 is Monday and 6 is Sunday. Thus, this function can be used to determine the day of the week independent of the national language in which you are working. Note: The base date of 1 January 0001 is determined by extending the current Gregorian calendar backward (365 days each year, with an extra day every year that is divisible by 4 except century years that are not divisible by 400). It does not take into account any errors in the calendar system that created the Gregorian calendar originally. Century the number of days, including the current day, since and including January 1 of the last year that is a multiple of 100 in the form: ddddd (no leading zeros). Example: A call to DATE(C) on March 13, 1992, returns 33675, the number of days from 1 January 1900 to 13 March 1992. Similarly, a call to DATE(C) on November 20, 2001, returns 690, the number of days from 1 January 2000 to 20 November 2001. Note: When used for date_format1, this option is valid when input_date is not specified. Days European Julian the number of days, including the current day, so far in this year in the format: ddd (no leading zeros or blanks). date in the format: dd/mm/yy date in the format: yyddd. Note: When used for date_format1, this option is valid only when input_date is not specified. Month Normal full English name of the current month, in mixed casefor example, August. Only valid for date_format1. date in the format: dd mon yyyy, in mixed case. This is the default. If the active language has an abbreviated form of the month name, then it is usedfor example, Jan, Feb, and so on. If Normal is specified (or allowed to default) for date_format2, the input_date must have the month (mon) specified in the English abbreviated form of the month name in mixed case. date in the format: yy/mm/dd (suitable for sorting, and so forth). date in the format: yyyymmdd (suitable for sorting, and so forth). date in the format: mm/dd/yy. the English name for the day of the week, in mixed casefor example, Tuesday. Only valid for date_format1.

Ordered Standard Usa Weekday

Here are some examples, assuming today is November 20, 2001:

DATE() DATE(,20020609,S) DATE(B) DATE(B,25 Sep 2001) DATE(C) DATE(E) DATE(J) -> -> -> -> -> -> -> 20 Nov 2001 9 Jun 2002 730808 730752 690 20/11/01 01324
Chapter 4. Functions

97

Functions
DATE(M) DATE(N) DATE(N,1438,C) DATE(O) DATE(S) DATE(U) DATE(U,25 May 2001) DATE(U,25 MAY 2001) DATE(W) -> -> -> -> -> -> -> -> -> November 20 Nov 2001 8 Dec 2003 01/11/20 20011120 11/20/01 05/25/01 ERROR,month not in mixed case Tuesday

Notes: 1. The first call to DATE or TIME in one clause causes a time stamp to be made that is then used for all calls to these functions in that clause. Therefore, multiple calls to any of the DATE or TIME functions or both in a single expression or clause are guaranteed to be consistent with each other. 2. Input dates given in 2-digit year formats (i.e. European, Julian, Ordered, Usa) are interpreted as being within a 100 year window as calculated by: (current_year 50) = low end of window (current_year + 49) = high end of window DATE conversion requires that the input_date conforms exactly to one of the syntax forms that could have been output by the DATE function. For example, the following invocations of DATE would fail. The incorrect specification of input_date in each case would result in the same error message, IRX0040I.
DATE(B,7 MAY 2001) DATE(B, 7 May 2001) DATE(B,07 May 2001) -> -> -> IRX0040I IRX0040I IRX0040I (input is not mixed case) (input has a leading blank) (input has a leading zero)

DBCS (double-byte character set functions)

The following are all part of DBCS processing functions. See page 481.
DBADJUST DBBRACKET DBCENTER DBCJUSTIFY DBLEFT DBRIGHT DBRLEFT DBRRIGHT DBTODBCS DBTOSBCS DBUNBRACKET DBVALIDATE DBWIDTH

DELSTR (Delete String)

DELSTR(string,n ,length

returns string after deleting the substring that begins at the nth character and is of length characters. If you omit length, or if length is greater than the number of characters from n to the end of string, the function deletes the rest of string (including the nth character). The length must be a positive whole number or zero. The n must be a positive whole number. If n is greater than the length of string, the function returns string unchanged. Here are some examples:

98

z/OS V1R13.0 TSO/E REXX Reference

Functions
DELSTR(abcd,3) DELSTR(abcde,3,2) DELSTR(abcde,6) -> -> -> ab abe abcde

DELWORD (Delete Word)

DELWORD(string,n ,length

returns string after deleting the substring that starts at the nth word and is of length blank-delimited words. If you omit length, or if length is greater than the number of words from n to the end of string, the function deletes the remaining words in string (including the nth word). The length must be a positive whole number or zero. The n must be a positive whole number. If n is greater than the number of words in string, the function returns string unchanged. The string deleted includes any blanks following the final word involved but none of the blanks preceding the first word involved. Here are some examples:
DELWORD(Now DELWORD(Now DELWORD(Now DELWORD(Now is the time,2,2) is the time ,3) is the time,5) is the time,3,1) -> -> -> -> Now Now Now Now time is is the time is time

DIGITS

DIGITS()

returns the current setting of NUMERIC DIGITS. See the NUMERIC instruction on page 63 for more information. Here is an example:
DIGITS() -> 9 /* by default */

D2C (Decimal to Character)

D2C(wholenumber ,n

returns a string, in character format, that represents wholenumber, a decimal number, converted to binary. If you specify n, it is the length of the final result in characters; after conversion, the input string is sign-extended to the required length. If the number is too big to fit into n characters, then the result is truncated on the left. The n must be a positive whole number or zero.
Chapter 4. Functions

99

Functions
If you omit n, wholenumber must be a positive whole number or zero, and the result length is as needed. Therefore, the returned result has no leading '00'x characters. Here are some examples:
D2C(9) D2C(129) D2C(129,1) D2C(129,2) D2C(257,1) D2C(-127,1) D2C(-127,2) D2C(-1,4) D2C(12,0) -> -> -> -> -> -> -> -> -> a a a a a /* /* /* /* /* /* /* /* /* /* 09x is unprintable in EBCDIC 81x is an EBCDIC a 81x is an EBCDIC a 0081x is EBCDIC a 01x is unprintable in EBCDIC 81x is EBCDIC a FFx is unprintable EBCDIC; 81x is EBCDIC a FFFFFFFFx is unprintable in EBCDIC is a null string */ */ */ */ */ */ */ */ */ */

Implementation maximum: The output string may not have more than 250 significant characters, though a longer result is possible if it has additional leading sign characters ('00'x and 'FF'x).

D2X (Decimal to Hexadecimal)

D2X(wholenumber ,n

returns a string, in character format, that represents wholenumber, a decimal number, converted to hexadecimal. The returned string uses uppercase alphabetics for the values AF and does not include blanks. If you specify n, it is the length of the final result in characters; after conversion the input string is sign-extended to the required length. If the number is too big to fit into n characters, it is truncated on the left. The n must be a positive whole number or zero. If you omit n, wholenumber must be a positive whole number or zero, and the returned result has no leading zeros. Here are some examples:
D2X(9) D2X(129) D2X(129,1) D2X(129,2) D2X(129,4) D2X(257,2) D2X(-127,2) D2X(-127,4) D2X(12,0) -> -> -> -> -> -> -> -> -> 9 81 1 81 0081 01 81 FF81

Implementation maximum: The output string may not have more than 500 significant hexadecimal characters, though a longer result is possible if it has additional leading sign characters (0 and F).

100

z/OS V1R13.0 TSO/E REXX Reference

Functions

ERRORTEXT

ERRORTEXT(n)

returns the REXX error message associated with error number n. The n must be in the range 099, and any other value is an error. Returns the null string if n is in the allowed range but is not a defined REXX error number. Error numbers produced by syntax errors during processing of REXX execs correspond to TSO/E REXX messages (described in z/OS TSO/E Messages.) For example, error 26 corresponds to message number IRX0026I. The error number is also the value that is placed in the REXX special variable RC when SIGNAL ON SYNTAX event is trapped. Here are some examples:
ERRORTEXT(16) ERRORTEXT(60) -> -> Label not found

EXTERNALS
(Non-SAA Function) EXTERNALS is a non-SAA built-in function provided only by TSO/E and VM.
EXTERNALS()

always returns a 0. For example:

EXTERNALS() -> 0 /* Always */

The EXTERNALS function returns the number of elements in the terminal input buffer (system external event queue). In TSO/E, there is no equivalent buffer. Therefore, in the TSO/E implementation of REXX, the EXTERNALS function always returns a 0.

FIND
(Non-SAA Function) FIND is a non-SAA built-in function provided only by TSO/E and VM. WORDPOS is the preferred built-in function for this type of word search. See page 120 for a complete description.

FIND(string,phrase)

returns the word number of the first word of phrase found in string or returns 0 if phrase is not found or if there are no words in phrase. The phrase is a sequence of
Chapter 4. Functions

101

Functions
blank-delimited words. Multiple blanks between words in phrase or string are treated as a single blank for the comparison. Here are some examples:
FIND(now is the time,is the time) FIND(now is the time,is the) FIND(now is the time,is time ) -> -> -> 2 2 0

FORM

FORM()

returns the current setting of NUMERIC FORM. See the NUMERIC instruction on page 63 for more information. Here is an example:
FORM() -> SCIENTIFIC /* by default */

FORMAT

FORMAT(number , before , after , expp ,expt

returns number, rounded and formatted. The number is first rounded according to standard REXX rules, just as though the operation number+0 had been carried out. The result is precisely that of this operation if you specify only number. If you specify any other options, the number is formatted as follows. The before and after options describe how many characters are used for the integer and decimal parts of the result, respectively. If you omit either or both of these, the number of characters used for that part is as needed. If before is not large enough to contain the integer part of the number (plus the sign for a negative number), an error results. If before is larger than needed for that part, the number is padded on the left with blanks. If after is not the same size as the decimal part of the number, the number is rounded (or extended with zeros) to fit. Specifying 0 causes the number to be rounded to an integer. Here are some examples:
FORMAT(3,4) FORMAT(1.73,4,0) FORMAT(1.73,4,3) FORMAT(-.76,4,1) -> -> -> -> 3 2 1.730 -0.8

102

z/OS V1R13.0 TSO/E REXX Reference

Functions
FORMAT(3.03,4) FORMAT( - 12.73,,4) FORMAT( - 12.73) FORMAT(0.000) -> -> -> -> 3.03 -12.7300 -12.73 0

The first three arguments are as described previously. In addition, expp and expt control the exponent part of the result, which, by default, is formatted according to the current NUMERIC settings of DIGITS and FORM. The expp sets the number of places for the exponent part; the default is to use as many as needed (which may be zero). The expt sets the trigger point for use of exponential notation. The default is the current setting of NUMERIC DIGITS. If expp is 0, no exponent is supplied, and the number is expressed in simple form with added zeros as necessary. If expp is not large enough to contain the exponent, an error results. If the number of places needed for the integer or decimal part exceeds expt or twice expt, respectively, exponential notation is used. If expt is 0, exponential notation is always used unless the exponent would be 0. (If expp is 0, this overrides a 0 value of expt.) If the exponent would be 0 when a nonzero expp is specified, then expp+2 blanks are supplied for the exponent part of the result. If the exponent would be 0 and expp is not specified, simple form is used. Here are some examples:
FORMAT(12345.73,,,2,2) FORMAT(12345.73,,3,,0) FORMAT(1.234573,,3,,0) FORMAT(12345.73,,,3,6) FORMAT(1234567e5,,3,0) -> -> -> -> -> 1.234573E+04 1.235E+4 1.235 12345.73 123456700000.000

FUZZ

FUZZ()

returns the current setting of NUMERIC FUZZ. See the NUMERIC instruction on page 63 for more information. Here is an example:
FUZZ() -> 0 /* by default */

GETMSG
GETMSG is a TSO/E external function. See page 124.

INDEX
(Non-SAA Function) INDEX is a non-SAA built-in function provided only by TSO/E and VM. POS is the preferred built-in function for obtaining the position of one string in another. See page 108 for a complete description.

Chapter 4. Functions

103

Functions
INDEX(haystack,needle ,start )

returns the character position of one string, needle, in another, haystack, or returns 0 if the string needle is not found or is a null string. By default the search starts at the first character of haystack (start has the value 1). You can override this by specifying a different start point, which must be a positive whole number. Here are some examples:
INDEX(abcdef,cd) INDEX(abcdef,xd) INDEX(abcdef,bc,3) INDEX(abcabc,bc,3) INDEX(abcabc,bc,6) -> -> -> -> -> 3 0 0 5 0

INSERT

INSERT(new,target , n , length ,pad

inserts the string new, padded or truncated to length length, into the string target after the nth character. The default value for n is 0, which means insert before the beginning of the string. If specified, n and length must be positive whole numbers or zero. If n is greater than the length of the target string, padding is added before the string new also. The default value for length is the length of new. If length is less than the length of the string new, then INSERT truncates new to length length. The default pad character is a blank. Here are some examples:
INSERT( ,abcdef,3) INSERT(123,abc,5,6) INSERT(123,abc,5,6,+) INSERT(123,abc) INSERT(123,abc,,5,-) -> -> -> -> -> abc def abc 123 abc++123+++ 123abc 123--abc

JUSTIFY
(Non-SAA Function) JUSTIFY is a non-SAA built-in function provided only by TSO/E and VM.

JUSTIFY(string,length ,pad

104

z/OS V1R13.0 TSO/E REXX Reference

Functions
returns string formatted by adding pad characters between blank-delimited words to justify to both margins. This is done to width length (length must be a positive whole number or zero). The default pad character is a blank. The first step is to remove extra blanks as though SPACE(string) had been run (that is, multiple blanks are converted to single blanks, and leading and trailing blanks are removed). If length is less than the width of the changed string, the string is then truncated on the right and any trailing blank is removed. Extra pad characters are then added evenly from left to right to provide the required length, and the pad character replaces the blanks between words. Here are some examples:
JUSTIFY(The JUSTIFY(The JUSTIFY(The JUSTIFY(The blue blue blue blue sky,14) sky,8) sky,9) sky,9,+) -> -> -> -> The blue sky The blue The blue The++blue

LASTPOS (Last Position)

LASTPOS(needle,haystack ,start

returns the position of the last occurrence of one string, needle, in another, haystack. (See also the POS function.) Returns 0 if needle is the null string or is not found. By default the search starts at the last character of haystack and scans backward. You can override this by specifying start, the point at which the backward scan starts. start must be a positive whole number and defaults to LENGTH(haystack) if larger than that value or omitted. Here are some examples:
LASTPOS( ,abc def ghi) LASTPOS( ,abcdefghi) LASTPOS(xy,efgxyz) LASTPOS( ,abc def ghi,7) -> -> -> -> 8 0 4 4

LEFT

LEFT(string,length ,pad

returns a string of length length, containing the leftmost length characters of string. The string returned is padded with pad characters (or truncated) on the right as needed. The default pad character is a blank. length must be a positive whole number or zero. The LEFT function is exactly equivalent to:
SUBSTR(string,1,length ,pad )

Chapter 4. Functions

105

Functions
Here are some examples:
LEFT(abc d,8) LEFT(abc d,8,.) LEFT(abc def,7) -> -> -> abc d abc d... abc de

LENGTH

LENGTH(string)

returns the length of string. Here are some examples:

LENGTH(abcdefgh) LENGTH(abc defg) LENGTH() -> -> -> 8 8 0

LINESIZE
(Non-SAA Function) LINESIZE is a non-SAA built-in function provided only by TSO/E and VM.

LINESIZE()

returns the current terminal line width minus 1 (the point at which the language processor breaks lines displayed using the SAY instruction). If the REXX exec is running in TSO/E background (that is, on the JCL EXEC statement PGM=IKJEFT01), LINESIZE always returns the value 131. If the REXX exec is running in TSO/E foreground, the LINESIZE function always returns the current terminal width (as defined by the TSO/E TERMINAL command) minus one character. If the exec is running in a non-TSO/E address space, LINESIZE returns the logical record length of the OUTDD file (the default file is SYSTSPRT). The OUTDD file is specified in the module name table (see page 364).

LISTDSI
LISTDSI is a TSO/E external function. See 130.

106

z/OS V1R13.0 TSO/E REXX Reference

Functions

MAX (Maximum)

, MAX( number )

returns the largest number from the list specified, formatted according to the current NUMERIC settings. Here are some examples:
MAX(12,6,7,9) MAX(17.3,19,17.03) MAX(-7,-3,-4.3) MAX(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,MAX(20,21)) -> -> -> -> 12 19 -3 21

Implementation maximum: You can specify up to 20 numbers, and can nest calls to MAX if more arguments are needed.

MIN (Minimum)
, MIN( number )

returns the smallest number from the list specified, formatted according to the current NUMERIC settings. Here are some examples:
MIN(12,6,7,9) MIN(17.3,19,17.03) MIN(-7,-3,-4.3) MIN(21,20,19,18,17,16,15,14,13,12,11,10,9,8,7,6,5,4,3,MIN(2,1)) -> 6 -> 17.03 -> -7 -> 1

Implementation maximum: You can specify up to 20 numbers, and can nest calls to MIN if more arguments are needed.

MSG
MSG is a TSO/E external function. See 140.

MVSVAR
MVSVAR is a TSO/E external function. See 141.

OUTTRAP
OUTTRAP is a TSO/E external function. See 145.

Chapter 4. Functions

107

Functions

OVERLAY

OVERLAY(new,target , n , length ,pad

returns the string target, which, starting at the nth character, is overlaid with the string new, padded or truncated to length length. (The overlay may extend beyond the end of the original target string.) If you specify length, it must be a positive whole number or zero. The default value for length is the length of new. If n is greater than the length of the target string, padding is added before the new string. The default pad character is a blank, and the default value for n is 1. If you specify n, it must be a positive whole number. Here are some examples:
OVERLAY( ,abcdef,3) OVERLAY(.,abcdef,3,2) OVERLAY(qq,abcd) OVERLAY(qq,abcd,4) OVERLAY(123,abc,5,6,+) -> -> -> -> -> ab def ab. ef qqcd abcqq abc+123+++

POS (Position)

POS(needle,haystack ,start

returns the position of one string, needle, in another, haystack. (See also the INDEX and LASTPOS functions.) Returns 0 if needle is the null string or is not found or if start is greater than the length of haystack. By default the search starts at the first character of haystack (that is, the value of start is 1). You can override this by specifying start (which must be a positive whole number), the point at which the search starts. Here are some examples:
POS(day,Saturday) POS(x,abc def ghi) POS( ,abc def ghi) POS( ,abc def ghi,5) -> -> -> -> 6 0 4 8

PROMPT
PROMPT is a TSO/E external function. See 152.

108

z/OS V1R13.0 TSO/E REXX Reference

Functions

QUEUED

QUEUED()

returns the number of lines remaining in the external data queue when the function is called. The TSO/E implementation of the external data queue is the data stack. Here is an example:
QUEUED() -> 5 /* Perhaps */

RANDOM

RANDOM( max min, ,

max

,seed

returns a quasi-random nonnegative whole number in the range min to max inclusive. If you specify max or min or both, max minus min cannot exceed 100000. The min and max default to 0 and 999, respectively. To start a repeatable sequence of results, use a specific seed as the third argument, as described in Note 1. This seed must be a positive whole number ranging from 0 to 999999999. Here are some examples:
RANDOM() RANDOM(5,8) RANDOM(2) RANDOM(,,1983) -> -> -> -> 305 7 0 /* 0 to 2 */ 123 /* reproducible */

Notes: 1. To obtain a predictable sequence of quasi-random numbers, use RANDOM a number of times, but specify a seed only the first time. For example, to simulate 40 throws of a 6-sided, unbiased die:
sequence = RANDOM(1,6,12345) /* any number would */ /* do for a seed */

do 39 sequence = sequence RANDOM(1,6) end say sequence

The numbers are generated mathematically, using the initial seed, so that as far as possible they appear to be random. Running the program again produces the same sequence; using a different initial seed almost certainly produces a different sequence. If you do not supply a seed, the first time RANDOM is called, an arbitrary seed is used. Hence, your program usually gives different results each time it is run.

Chapter 4. Functions

109

Functions
2. The random number generator is global for an entire program; the current seed is not saved across internal routine calls.

REVERSE

REVERSE(string)

returns string, swapped end for end. Here are some examples:
REVERSE(ABc.) REVERSE(XYZ ) -> -> .cBA ZYX

RIGHT

RIGHT(string,length ,pad

returns a string of length length containing the rightmost length characters of string. The string returned is padded with pad characters (or truncated) on the left as needed. The default pad character is a blank. The length must be a positive whole number or zero. Here are some examples:
RIGHT(abc d,8) RIGHT(abc def,5) RIGHT(12,5,0) -> -> -> abc d c def 00012

SETLANG
SETLANG is a TSO/E external function. See 155.

SIGN
SIGN(number)

returns a number that indicates the sign of number. The number is first rounded according to standard REXX rules, just as though the operation number+0 had been carried out. Returns -1 if number is less than 0; returns 0 if it is 0; and returns 1 if it is greater than 0. Here are some examples:
SIGN(12.3) SIGN( -0.307) SIGN(0.0) -> -> -> 1 -1 0

110

z/OS V1R13.0 TSO/E REXX Reference

Functions

SOURCELINE

SOURCELINE( n

returns the line number of the final line in the program if you omit n or 0 if the implementation does not allow access to the source lines. If you specify n, returns the nth line in the program if available at the time of execution; otherwise, returns the null string. If specified, n must be a positive whole number and must not exceed the number that a call to SOURCELINE with no arguments returns. Here are some examples:
SOURCELINE() SOURCELINE(1) -> -> 10 /* This is a 10-line REXX program */

SPACE

SPACE(string , n ,pad

returns the blank-delimited words in string with n pad characters between each word. If you specify n, it must be a positive whole number or zero. If it is 0, all blanks are removed. Leading and trailing blanks are always removed. The default for n is 1, and the default pad character is a blank. Here are some examples:
SPACE(abc def ) SPACE( abc def,3) SPACE(abc def ,1) SPACE(abc def ,0) SPACE(abc def ,2,+) -> -> -> -> -> abc def abc def abc def abcdef abc++def

STORAGE
STORAGE is a TSO/E external function. See 157.

STRIP

STRIP(string , option ,char

Chapter 4. Functions

111

Functions
returns string with leading or trailing characters or both removed, based on the option you specify. The following are valid options. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.) Both Leading Trailing removes both leading and trailing characters from string. This is the default. removes leading characters from string. removes trailing characters from string.

The third argument, char, specifies the character to be removed, and the default is a blank. If you specify char, it must be exactly one character long. Here are some examples:
STRIP( ab c ) STRIP( ab c ,L) STRIP( ab c ,t) STRIP(12.7000,,0) STRIP(0012.700,,0) -> -> -> -> -> ab c ab c ab c 12.7 12.7

SUBSTR (Substring)

SUBSTR(string,n , length ,pad

returns the substring of string that begins at the nth character and is of length length, padded with pad if necessary. The n must be a positive whole number. If n is greater than LENGTH(string), then only pad characters are returned. If you omit length, the rest of the string is returned. The default pad character is a blank. Here are some examples:
SUBSTR(abc,2) SUBSTR(abc,2,4) SUBSTR(abc,2,6,.) -> -> -> bc bc bc....

Note: In some situations the positional (numeric) patterns of parsing templates are more convenient for selecting substrings, especially if more than one substring is to be extracted from a string. See also the LEFT and RIGHT functions.

SUBWORD

SUBWORD(string,n ,length

112

z/OS V1R13.0 TSO/E REXX Reference

Functions
returns the substring of string that starts at the nth word, and is up to length blank-delimited words. The n must be a positive whole number. If you omit length, it defaults to the number of remaining words in string. The returned string never has leading or trailing blanks, but includes all blanks between the selected words. Here are some examples:
SUBWORD(Now is the time,2,2) SUBWORD(Now is the time,3) SUBWORD(Now is the time,5) -> -> -> is the the time

SYMBOL

SYMBOL(name)

returns the state of the symbol named by name. Returns BAD if name is not a valid REXX symbol. Returns VAR if it is the name of a variable (that is, a symbol that has been assigned a value). Otherwise returns LIT, indicating that it is either a constant symbol or a symbol that has not yet been assigned a value (that is, a literal). As with symbols in REXX expressions, lowercase characters in name are translated to uppercase and substitution in a compound name occurs if possible. You should specify name as a literal string (or it should be derived from an expression) to prevent substitution before it is passed to the function. Here are some examples:
/* following: Drop A.3; J=3 */ SYMBOL(J) -> VAR SYMBOL(J) -> LIT /* has tested "3" SYMBOL(a.j) -> LIT /* has tested A.3 SYMBOL(2) -> LIT /* a constant symbol SYMBOL(*) -> BAD /* not a valid symbol

*/ */ */ */

SYSCPUS
SYSCPUS is a TSO/E external function. See 158.

SYSDSN
SYSDSN is a TSO/E external function. See page 159.

SYSVAR
SYSVAR is a TSO/E external function. See 161.

TIME

TIME( option

Chapter 4. Functions

113

Functions
returns the local time in the 24-hour clock format: hh:mm:ss (hours, minutes, and seconds) by default, for example, 04:41:37. You can use the following options to obtain alternative formats, or to gain access to the elapsed-time clock. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.) Civil returns the time in Civil format: hh:mmxx. The hours may take the values 1 through 12, and the minutes the values 00 through 59. The minutes are followed immediately by the letters am or pm. This distinguishes times in the morning (12 midnight through 11:59 a.m.appearing as 12:00am through 11:59am) from noon and afternoon (12 noon through 11:59 p.m.appearing as 12:00pm through 11:59pm). The hour has no leading zero. The minute field shows the current minute (rather than the nearest minute) for consistency with other TIME results. returns sssssssss.uuuuuu, the number of seconds.microseconds since the elapsed-time clock (described later) was started or reset. The number has no leading zeros or blanks, and the setting of NUMERIC DIGITS does not affect the number. The fractional part always has six digits. returns up to two characters giving the number of hours since midnight in the format: hh (no leading zeros or blanks, except for a result of 0). returns time in the format: hh:mm:ss.uuuuuu (uuuuuu is the fraction of seconds, in microseconds). The first eight characters of the result follow the same rules as for the Normal form, and the fractional part is always six digits. returns up to four characters giving the number of minutes since midnight in the format: mmmm (no leading zeros or blanks, except for a result of 0). returns the time in the default format hh:mm:ss, as described previously. The hours can have the values 00 through 23, and minutes and seconds, 00 through 59. All these are always two digits. Any fractions of seconds are ignored (times are never rounded up). This is the default. returns sssssssss.uuuuuu, the number of seconds.microseconds since the elapsed-time clock (described later) was started or reset and also resets the elapsed-time clock to zero. The number has no leading zeros or blanks, and the setting of NUMERIC DIGITS does not affect the number. The fractional part always has six digits. returns up to five characters giving the number of seconds since midnight in the format: sssss (no leading zeros or blanks, except for a result of 0).

Elapsed

Hours

Long

Minutes

Normal

Reset

Seconds

Here are some examples, assuming that the time is 4:54 p.m.:
TIME() TIME(C) TIME(H) TIME(L) TIME(M) TIME(N) TIME(S) -> -> -> -> -> -> -> 16:54:22 4:54pm 16 16:54:22.123456 /* Perhaps */ 1014 /* 54 + 60*16 */ 16:54:22 60862 /* 22 + 60*(54+60*16) */

114

z/OS V1R13.0 TSO/E REXX Reference

Functions
The elapsed-time clock: You can use the TIME function to measure real (elapsed) time intervals. On the first call in a program to TIME(E) or TIME(R), the elapsed-time clock is started, and either call returns 0. From then on, calls to TIME(E) and to TIME(R) return the elapsed time since that first call or since the last call to TIME(R). The clock is saved across internal routine calls, which is to say that an internal routine inherits the time clock its caller started. Any timing the caller is doing is not affected, even if an internal routine resets the clock. An example of the elapsed-time clock:
time(E) /* pause of time(E) /* pause of time(R) /* pause of time(R) -> 0 /* one second here */ -> 1.002345 /* one second here */ -> 2.004690 /* one second here */ -> 1.002345 /* The first call */ or thereabouts */ or thereabouts */ or thereabouts */

Restriction: See the note under DATE about consistency of times within a single clause. The elapsed-time clock is synchronized to the other calls to TIME and DATE, so multiple calls to the elapsed-time clock in a single clause always return the same result. For the same reason, the interval between two usual TIME/DATE results may be calculated exactly using the elapsed-time clock. Implementation maximum: If the number of seconds in the elapsed time exceeds nine digits (equivalent to over 31.6 years), an error results.

TRACE

TRACE( option

returns trace actions currently in effect and, optionally, alters the setting. If you specify option, it selects the trace setting. It must be one of the valid prefixes ? or ! or one of the alphabetic character options associated with the TRACE instruction (that is, starting with A, C, E, F, I, L, N, O, R, or S) or both. (See the TRACE instruction on page 77 for full details.) Unlike the TRACE instruction, the TRACE function alters the trace action even if interactive debug is active. Also unlike the TRACE instruction, option cannot be a number. Here are some examples:
TRACE() TRACE(O) TRACE(?I) -> -> -> ?R /* maybe */ ?R /* also sets tracing off */ O /* now in interactive debug */

Chapter 4. Functions

115

Functions

TRANSLATE

TRANSLATE(string , tableo , tablei ,pad

returns string with each character translated to another character or unchanged. You can also use this function to reorder the characters in string. The output table is tableo and the input translation table is tablei. TRANSLATE searches tablei for each character in string. If the character is found, then the corresponding character in tableo is used in the result string; if there are duplicates in tablei, the first (leftmost) occurrence is used. If the character is not found, the original character in string is used. The result string is always the same length as string. The tables can be of any length. If you specify neither translation table and omit pad, string is simply translated to uppercase (that is, lowercase az to uppercase AZ), but, if you include pad, the language processor translates the entire string to pad characters. tablei defaults to XRANGE(00x,FFx), and tableo defaults to the null string and is padded with pad or truncated as necessary. The default pad is a blank. Here are some examples:
TRANSLATE(abcdef) TRANSLATE(abbc,&,b) TRANSLATE(abcdef,12,ec) TRANSLATE(abcdef,12,abcd,.) TRANSLATE(APQRV,,PR) TRANSLATE(APQRV,XRANGE(00X,Q)) TRANSLATE(4123,abcd,1234) -> -> -> -> -> -> -> ABCDEF a&&c ab2d1f 12..ef A Q V APQ dabc

The last example shows how to use the TRANSLATE function to reorder the characters in a string. In the example, the last character of any four-character string specified as the second argument would be moved to the beginning of the string.

TRUNC (Truncate)

TRUNC(number ,n

returns the integer part of number and n decimal places. The default n is 0 and returns an integer with no decimal point. If you specify n, it must be a positive whole number or zero. The number is first rounded according to standard REXX rules, just as though the operation number+0 had been carried out. The number is then truncated to n decimal places (or trailing zeros are added if needed to make up the specified length). The result is never in exponential form.

116

z/OS V1R13.0 TSO/E REXX Reference

Functions
Here are some examples:
TRUNC(12.3) TRUNC(127.09782,3) TRUNC(127.1,3) TRUNC(127,2) -> -> -> -> 12 127.097 127.100 127.00

The number is rounded according to the current setting of NUMERIC DIGITS if necessary before the function processes it.

USERID
(Non-SAA Function) USERID is a non-SAA built-in function provided only by TSO/E and VM.

USERID()

returns the TSO/E user ID, if the REXX exec is running in the TSO/E address space. For example:
USERID() -> ARTHUR /* Maybe */

If the exec is running in a non-TSO/E address space, USERID returns one of the following values: v User ID specified (provided that the value specified is between one and seven characters in length) v Stepname specified v Jobname specified The value that USERID returns is the first one that does not have a null value. For example, if the user ID is null but the stepname is specified, USERID returns the value of the stepname. TSO/E lets you replace the routine (module) that is called to determine the value the USERID function returns. This is known as the user ID replaceable routine and is described in User ID routine on page 474. You can replace the routine only in non-TSO/E address spaces. Chapter 16, Replaceable routines and exits describes replaceable routines in detail and any exceptions to this rule.

VALUE

VALUE(name , newvalue

returns the value of the symbol that name (often constructed dynamically) represents and optionally assigns it a new value. By default, VALUE refers to the current REXX-variables environment. If you use the function to refer to REXX variables, then name must be a valid REXX symbol. (You can confirm this by using

Chapter 4. Functions

117

Functions
the SYMBOL function.) Lowercase characters in name are translated to uppercase. Substitution in a compound name (see Compound symbols on page 21) occurs if possible. If you specify newvalue, then the named variable is assigned this new value. This does not affect the result returned; that is, the function returns the value of name as it was before the new assignment. Here are some examples:
/* After: Drop A3; VALUE(ak) -> VALUE(fred) -> VALUE(fred) -> VALUE(fred,5) -> A33=7; K=3; fred=K; list.5=Hi */ A3 /* looks up A3 */ K /* looks up FRED */ 3 /* looks up K */ 3 /* looks up K and */ /* then sets K=5 */ VALUE(fred) -> 5 /* looks up K */ VALUE(LIST.k) -> Hi /* looks up LIST.5 */

Guideline: If the VALUE function refers to an uninitialized REXX variable then the default value of the variable is always returned; the NOVALUE condition is not raised. If you specify the name as a single literal the symbol is a constant and so the string between the quotation marks can usually replace the whole function call. (For example, fred=VALUE('k'); is identical with the assignment fred=k;, unless the NOVALUE condition is being trapped. See Chapter 7, Conditions and condition traps, on page 195.)

VERIFY

VERIFY(string,reference , option ,start

returns a number that, by default, indicates whether string is composed only of characters from reference; returns 0 if all characters in string are in reference, or returns the position of the first character in string not in reference. The option can be either Nomatch (the default) or Match. (Only the capitalized and highlighted letter is needed. All characters following it are ignored, and it can be in upper- or lowercase, as usual.) If you specify Match, the function returns the position of the first character in string that is in reference, or returns 0 if none of the characters are found. The default for start is 1; thus, the search starts at the first character of string. You can override this by specifying a different start point, which must be a positive whole number. If string is null, the function returns 0, regardless of the value of the third argument. Similarly, if start is greater than LENGTH(string), the function returns 0. If reference is null, the function returns 0 if you specify Match; otherwise the function returns the start value. Here are some examples:

118

z/OS V1R13.0 TSO/E REXX Reference

Functions
VERIFY(123,1234567890) VERIFY(1Z3,1234567890) VERIFY(AB4T,1234567890) VERIFY(AB4T,1234567890,M) VERIFY(AB4T,1234567890,N) VERIFY(1P3Q4,1234567890,,3) VERIFY(123,,N,2) VERIFY(ABCDE,,,3) VERIFY(AB3CD5,1234567890,M,4) -> -> -> -> -> -> -> -> -> 0 2 1 3 1 4 2 3 6

WORD

WORD(string,n)

returns the nth blank-delimited word in string or returns the null string if fewer than n words are in string. The n must be a positive whole number. This function is exactly equivalent to SUBWORD(string,n,1). Here are some examples:
WORD(Now is the time,3) WORD(Now is the time,5) -> -> the

WORDINDEX

WORDINDEX(string,n)

returns the position of the first character in the nth blank-delimited word in string or returns 0 if fewer than n words are in string. The n must be a positive whole number. Here are some examples:
WORDINDEX(Now is the time,3) WORDINDEX(Now is the time,6) -> -> 8 0

WORDLENGTH

WORDLENGTH(string,n)

returns the length of the nth blank-delimited word in string or returns 0 if fewer than n words are in string. The n must be a positive whole number. Here are some examples:

Chapter 4. Functions

119

Functions
WORDLENGTH(Now is the time,2) WORDLENGTH(Now comes the time,2) WORDLENGTH(Now is the time,6) -> -> -> 2 5 0

WORDPOS (Word Position)

WORDPOS(phrase,string ,start

returns the word number of the first word of phrase found in string or returns 0 if phrase contains no words or if phrase is not found. Multiple blanks between words in either phrase or string are treated as a single blank for the comparison, but otherwise the words must match exactly. By default the search starts at the first word in string. You can override this by specifying start (which must be positive), the word at which to start the search. Here are some examples:
WORDPOS(the,now is the time) WORDPOS(The,now is the time) WORDPOS(is the,now is the time) WORDPOS(is the,now is the time) WORDPOS(is time ,now is the time) WORDPOS(be,To be or not to be) WORDPOS(be,To be or not to be,3) -> -> -> -> -> -> -> 3 0 2 2 0 2 6

WORDS

WORDS(string)

returns the number of blank-delimited words in string. Here are some examples:
WORDS(Now is the time) WORDS( ) -> -> 4 0

XRANGE (Hexadecimal Range)

XRANGE( start ,end

returns a string of all valid 1-byte encodings (in ascending order) between and including the values start and end. The default value for start is '00'x, and the

120

z/OS V1R13.0 TSO/E REXX Reference

Functions
default value for end is 'FF'x. If start is greater than end, the values wrap from 'FF'x to '00'x. If specified, start and end must be single characters. Here are some examples:
XRANGE(a,f) XRANGE(03x,07x) XRANGE(,04x) XRANGE(i,j) XRANGE(FEx,02x) XRANGE(i,j) -> -> -> -> -> -> abcdef 0304050607x 0001020304x 898A8B8C8D8E8F9091x FEFF000102x ij

/* EBCDIC */ /* ASCII */

X2B (Hexadecimal to Binary)

X2B(hexstring)

returns a string, in character format, that represents hexstring converted to binary. The hexstring is a string of hexadecimal characters. It can be of any length. Each hexadecimal character is converted to a string of four binary digits. You can optionally include blanks in hexstring (at byte boundaries only, not leading or trailing) to aid readability; they are ignored. The returned string has a length that is a multiple of four, and does not include any blanks. If hexstring is null, the function returns a null string. Here are some examples:
X2B(C3) X2B(7) X2B(1 C1) -> 11000011 -> 0111 -> 000111000001

You can combine X2B with the functions D2X and C2X to convert numbers or character strings into binary form. Here are some examples:
X2B(C2X(C3x)) X2B(D2X(129)) X2B(D2X(12)) -> 11000011 -> 10000001 -> 1100

X2C (Hexadecimal to Character)

X2C(hexstring)

returns a string, in character format, that represents hexstring converted to character. The returned string is half as many bytes as the original hexstring. hexstring can be of any length. If necessary, it is padded with a leading 0 to make an even number of hexadecimal digits.

Chapter 4. Functions

121

Functions
You can optionally include blanks in hexstring (at byte boundaries only, not leading or trailing) to aid readability; they are ignored. If hexstring is null, the function returns a null string. Here are some examples:
X2C(F7F2 A2) X2C(F7f2a2) X2C(F) -> -> -> 72s 72s /* EBCDIC */ /* EBCDIC */ /* 0F is unprintable EBCDIC */

X2D (Hexadecimal to Decimal)

X2D(hexstring ,n

returns the decimal representation of hexstring. The hexstring is a string of hexadecimal characters. If the result cannot be expressed as a whole number, an error results. That is, the result must not have more digits than the current setting of NUMERIC DIGITS. You can optionally include blanks in hexstring (at byte boundaries only, not leading or trailing) to aid readability; they are ignored. If hexstring is null, the function returns 0. If you do not specify n, hexstring is processed as an unsigned binary number. Here are some examples:
X2D(0E) -> 14 X2D(81) X2D(F81) X2D(FF81) X2D(F0) X2D(c6 f0X)

-> -> -> -> ->

129 3969 65409 240 240

X2D(C6F0)

->

61646

/* C6 F0X is equivalent toF0.*/ /* See discussion elsewhere of hexadecimal strings.*/ /* C6F0is a 4 digit hex number.*/

If you specify n, the string is taken as a signed number expressed in n hexadecimal digits. If the leftmost bit is off, then the number is positive; otherwise, it is a negative number in two's complement notation. In both cases it is converted to a whole number, which may, therefore, be negative. If n is 0, the function returns 0. If necessary, hexstring is padded on the left with 0 characters (note, not sign-extended), or truncated on the left to n characters. Here are some examples:
X2D(81,2) X2D(81,4) X2D(F081,4) -> -> -> -127 129 -3967

122

z/OS V1R13.0 TSO/E REXX Reference

Functions
X2D(F081,3) X2D(F081,2) X2D(F081,1) X2D(0031,0) -> -> -> -> 129 -127 1 0

Implementation maximum: The input string may not have more than 500 hexadecimal characters that will be significant in forming the final result. Leading sign characters (0 and F) do not count towards this total.

TSO/E external functions

TSO/E provides the following external functions you can use to perform different tasks: v DBCJUSTIFY v EXTERNALS v FIND v GETMSG v INDEX v JUSTIFY v LINESIZE v LISTDSI v MSG v MVSVAR v OUTTRAP v PROMPT v SETLANG v STORAGE v SYSCPUS v SYSDSN v SYSVAR v USERID You can use the MVSVAR, SETLANG, STORAGE and SYSCPUS external functions in REXX execs that run in any address space, TSO/E and non-TSO/E. You can use the other external functions only in REXX execs that run in the TSO/E address space. The following topics describe the TSO/E external functions. For general information about the syntax of function calls, see Syntax on page 81. In this section, examples are provided that show how to use the TSO/E external functions. The examples may include data set names. When an example includes a data set name that is enclosed in single quotation marks, the prefix is added to the data set name. In the examples, the user ID is the prefix. Guideline: If you customize REXX processing and use the initialization routine IRXINIT, you can initialize a language processor environment that is not integrated into TSO/E (see page 352). You can use the SETLANG and STORAGE external functions in any type of language processor environment. You can use the other TSO/E external functions only if the environment is integrated into TSO/E. Chapter 13, TSO/E REXX customizing services describes customization and language processor environments in more detail.

Chapter 4. Functions

123

Functions

GETMSG

GETMSG(msgstem , msgtype , cart , mask , time

GETMSG returns a function code that replaces the function call and retrieves, in variables, a message that has been issued during a console session. Table 4 on page 125 lists the function codes that GETMSG returns. Use GETMSG during an extended MCS console session that you established using the TSO/E CONSOLE command. Use GETMSG to retrieve messages that are routed to the user's console but that are not being displayed at the user's terminal. The message can be either solicited (a command response) or unsolicited (other system messages), or either. GETMSG retrieves only one message at a time. The message itself may be more than one line. Each line of message text is stored in successive variables. For more information, see the description of the msgstem argument on page 125. To use GETMSG, you must: v Have CONSOLE command authority v Have solicited or unsolicited messages stored rather than displayed at the terminal during a console session. Your installation may have set up a console profile for you so that the messages are not displayed. You can also use the TSO/E CONSPROF command to specify that solicited or unsolicited messages should not be displayed during a console session. v Issue the TSO/E CONSOLE command to activate a console session. You can use the GETMSG function only in REXX execs that run in the TSO/E address space.

Environment Customization Considerations If you use IRXINIT to initialize language processor environments, note that you can use GETMSG only in environments that are integrated into TSO/E (see page 352). Responses to commands sent through the network to another system might be affected as follows: v The responses might not be returned as solicited even if a CART was specified and preserved; UNSOLDISPLAY(YES) may be required. v If the receiving system does not preserve the extended console identifier, ROUTCODE(ALL) and UNSOLDISPLAY(YES) might be required to receive the responses.

124

z/OS V1R13.0 TSO/E REXX Reference

Functions
For information about ROUTCODE, see z/OS MVS Initialization and Tuning Reference. For information about UNSOLDISPLAY, see z/OS TSO/E System Programming Command Reference. Table 4 lists the function codes that replace the function call. The GETMSG function raises the SYNTAX condition if you specify an incorrect argument on the function call or you specify too many arguments. A SYNTAX condition is also raised if a severe error occurs during GETMSG processing.
Table 4. Function codes for GETMSG that replace the function call Function code 0 4 Description GETMSG processing was successful. GETMSG retrieved the message. GETMSG processing was successful. However, GETMSG did not retrieve the message. There are several reasons why GETMSG may not be able to retrieve the message based on the arguments you specify on the function call. GETMSG returns a function code of 4 if one of the following occurs: v No messages were available to be retrieved v The messages did not match the search criteria you specified on the function call v You specified the time argument and the time limit expired before the message was available. 8 GETMSG processing was successful. However, you pressed the attention interrupt key during GETMSG processing. GETMSG did not retrieve the message. GETMSG processing was not successful. A console session is not active. The system issues a message that describes the error. You must issue the TSO/E CONSOLE command to activate a console session. GETMSG processing was not successful. The console session was being deactivated while GETMSG was processing. The system issues a message that describes the error.

12

16

The arguments you can specify on the GETMSG function are: msgstem the stem of the list of variables into which GETMSG places the message text. To place the message text into compound variables, which allow for indexing, msgstem should end with a period (for example, messg.). GETMSG places each line of the retrieved message into successive variables. For example, if GETMSG retrieves a message that has three lines of text, GETMSG places each line of message text into the variables messg.1, messg.2, messg.3. GETMSG stores the number of lines of message text in the variable ending in 0, messg.0. Note: If messg.0=0, no lines are associated with this message. This message might be a delete operator message (DOM) request. For more information about the DOM macro, see z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN. If msgstem does not end with a period, the variable names are appended with consecutive numbers. For example, suppose you specify msgstem as conmsg (without a period). If GETMSG retrieves a message that has two lines of message text, GETMSG
Chapter 4. Functions

125

Functions
places the text into the variables conmsg1 and conmsg2. The variable conmsg0 contains the number of lines of message text, which is 2. In addition to the variables into which GETMSG places the retrieved message text, GETMSG also sets additional variables. The additional variables relate to the field names in the message data block (MDB) for MVS/ESA System Product. For more information about these variables, see Appendix D, Additional variables that GETMSG sets, on page 507. msgtype the type of message you want to retrieve. Specify one of the following values for msgtype: v SOL indicates that you want to retrieve a solicited message. A solicited message is the response from an MVS system or subsystem command. v UNSOL indicates that you want to retrieve an unsolicited message. An unsolicited message is any message that is not issued in response to an MVS system or subsystem command. For example, an unsolicited message may be a message that another user sends you or a broadcast message. v EITHER indicates that you want to retrieve either type of message (solicited or unsolicited). If you do not specify the msgtype argument, EITHER is the default. cart the command and response token (CART). The CART is a token that lets you associate MVS system commands and subcommands with their responses. When you issue an MVS system or subsystem command, you can specify a CART on the command invocation. To use GETMSG to retrieve a particular message that is in direct response to the command invoked, specify the same CART value. GETMSG uses the CART you specify as a search argument to obtain the message. If you specify a CART, GETMSG compares the CART you specify with the CARTs for the messages that have been routed to the user's console. GETMSG retrieves the message, only if the CART you specify matches the CART associated with the message. Otherwise, no message is retrieved. The cart argument is used only if you are retrieving solicited messages, that is, the value for the msgtype argument is SOL. The CART is ignored if you specify UNSOL or EITHER for msgtype. The cart argument is optional. If you do not specify a CART, GETMSG retrieves the oldest message that is available. The type of message retrieved depends on the msgtype argument. For cart, you can specify a character string of 1-8 characters or a hexadecimal string of 1-16 hexadecimal digits. For example:
C1D7D7C1F4F9F4F1X

If you specify less than 8 characters or less than 16 hexadecimal digits, the value is padded on the right with blanks. If you specify more than 8 characters or more than 16 hexadecimal digits, the value is truncated to the first 8 characters or 16 digits and no error message is issued.

126

z/OS V1R13.0 TSO/E REXX Reference

Functions
For more information, see Using the command and response token (CART) and mask on page 128. mask search argument that GETMSG uses as a mask with the cart argument for obtaining a message. If you specify a mask, GETMSG ANDs the mask value with the CART value that you specify on the GETMSG function. GETMSG also ANDs the mask with the CARTs associated with the messages that have been routed to the user's console. GETMSG then compares the results of the AND operations. If a comparison matches, GETMSG retrieves the message. Otherwise, no message is retrieved. The mask argument is valid only if you are retrieving solicited messages and are using a CART. That is, mask is valid only if you specify SOL for msgtype and you specify the cart argument. The mask argument is optional. If you do not specify a mask, GETMSG does not use a mask value when comparing CART values. For mask, you can specify a character string of 1-8 characters or a hexadecimal string of 1-16 hexadecimal digits. For example:
FFFFFFFF00000000X

If you specify less than 8 characters or less than 16 hexadecimal digits, the value is padded on the right with blanks. If you specify more than eight characters or more than 16 hexadecimal digits, the value is truncated to the first eight characters or 16 digits and no error message is issued. For more information, see Using the command and response token (CART) and mask on page 128. time the amount of time, in seconds, that GETMSG should wait, if the requested message has not yet been routed to the user's console. If you specify a time value and the time expires before the message is routed to the user's console, GETMSG does not retrieve the message. Otherwise, if the message is available before the time expires, GETMSG retrieves the message. If you do not specify time, GETMSG uses a time value of 0 seconds. If the message has not been routed to the user's console, GETMSG does not retrieve the message.

Overview of using GETMSG during a console session

You can use the GETMSG external function with the TSO/E CONSOLE and CONSPROF commands and the CONSOLE host command environment to write REXX execs that perform MVS operator activities from TSO/E. Using the TSO/E CONSOLE command, you can activate an extended MCS console session with MCS console services. After you activate a console session, you can then use the TSO/E CONSOLE command and the CONSOLE host command envi