CICS TS For VSE/ESA: REXX Guide Ibm Panels

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 481 [warning: Documents this large are best viewed by clicking the View PDF Link!]

CICS Transaction Server for VSE/ESA
REXX Guide
SC34-5764-01

CICS Transaction Server for VSE/ESA
REXX Guide
SC34-5764-01

Note!
Before using this information and the product it supports, be sure to read the general information under “Notices” on page
443.
This edition applies to Release 1 of CICS Transaction Server for VSE/ESA, program number 5648-054, and to all
subsequent versions, releases, and modifications until otherwise indicated in new editions. Make sure you are using
the correct edition for the level of the product.
© Copyright IBM Corporation 1992, 2010.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Preface ....................................xix
What this book is about ..............................xix
Who this book is for ...............................xix
What you need to know to understand this book .....................xix
Prerequisites .................................xix
Part 1. User's Guide..............................1
Chapter 1. Introduction ..............................3
What is REXX?..................................3
Features of REXX.................................3
Ease of use ..................................3
Free format ..................................3
Convenient built-in functions ............................3
Debugging capabilities ..............................3
Interpreted language ...............................3
Extensive parsing capabilities ...........................3
Components of REXX ...............................4
Chapter 2. Writing and Running a REXX Program ....................5
What you need to run a REXX Program? ........................5
What is a REXX Program? .............................5
Syntax of REXX Instructions .............................6
The Format of REXX Instructions ..........................6
The Letter Case of REXX Instructions ........................6
Types of REXX Clauses .............................9
Programs Using Double-Byte Character Set Names ....................10
Typing in a Program ...............................11
Running a Program ...............................11
Interpreting Error Messages ............................12
How to Prevent Translation to Uppercase .......................13
Characters within a program ...........................13
Characters Input to a program...........................14
Exercises - Running and Modifying the Example Programs ................14
Passing Information to a program ..........................14
Getting Information from the Program Stack or Terminal Input Device ............14
Specifying Values When Calling a program ......................15
Preventing Translation of Input to Uppercase .....................16
Passing Arguments ...............................16
Chapter 3. Using Variables and Expressions .....................19
Program Variables ................................19
Using Variables .................................19
Variable Names ................................19
Variable Values ................................20
Using Expressions ................................21
Arithmetic Operators ..............................21
Comparison Operators .............................23
Logical (Boolean) Operators ...........................25
Concatenation Operators.............................27
Priority of Operators ..............................28
Tracing Expressions with the TRACE Instruction .....................29
Tracing Operations ...............................29
© Copyright IBM Corp. 1992, 2010 iii
Tracing Results ................................30
Exercises - Using the TRACE Instruction .......................30
Chapter 4. Controlling the Flow within a program ...................33
Conditional, Looping, and Interrupt Instructions .....................33
Using Conditional Instructions ............................33
IF...THEN...ELSE Instructions ...........................33
Nested IF...THEN...ELSE Instructions ........................34
SELECT WHEN...OTHERWISE...END Instruction....................37
Using Looping Instructions .............................39
Repetitive Loops ................................39
Conditional Loops ...............................42
Combining Types of Loops ............................46
Nested DO Loops ...............................46
Using Interrupt Instructions .............................48
EXIT Instruction ................................48
CALL and RETURN Instructions ..........................49
SIGNAL Instruction ...............................50
Chapter 5. Using Functions ............................51
What is a Function? ...............................51
Example of a Function .............................51
Built-In Functions ................................52
Arithmetic Functions ..............................53
Comparison Functions..............................53
Conversion Functions ..............................53
Formatting Functions ..............................53
String Manipulating Functions ...........................54
Miscellaneous Functions .............................54
Testing Input with Built-In Functions.........................55
Chapter 6. Writing Subroutines and Functions.....................57
What are Subroutines and Functions? .........................57
When to Write Subroutines Rather Than Functions ...................57
Writing Subroutines and Functions ..........................58
When to Use Internal Versus External Subroutines or Functions ..............60
Passing Information ..............................60
Receiving Information from a Subroutine or Function ..................66
Subroutines and Functions—Similarities and Differences ..................70
Chapter 7. Manipulating Data ...........................71
Using Compound Variables and Stems ........................71
What Is a Compound Variable? ..........................71
Using Stems .................................72
Parsing Data ..................................73
Parsing Instructions...............................73
More about Parsing into Words ..........................75
Parsing with Patterns ..............................75
Parsing Multiple Strings as Arguments ........................78
Chapter 8. Using Commands from a program .....................81
Types of Commands ...............................81
Using Quotations Marks in Commands .......................81
Using Variables in Commands ...........................81
Calling Another REXX Program as a Command ....................82
Issuing Commands from a program ..........................82
iv CICS TS for VSE/ESA: REXX Guide
What is a Host Command Environment? .......................82
How Is a Command Passed to the Host Environment?..................83
Changing the Host Command Environment ......................83
Chapter 9. Diagnosing Problems within a program ...................85
Debugging Programs ...............................85
Tracing Commands with the TRACE Instruction ....................85
Using REXX Special Variables RC and SIGL .....................85
Tracing with the Interactive Debug Facility ......................86
Saving Interactive TRACE Output .........................87
Chapter 10. Programming Style and Techniques ....................89
Consider the Data ................................89
Test Yourself... ................................89
Happy Hour ..................................90
Designing a Program ...............................92
Methods for Designing Loops ...........................93
The Conclusion ................................93
What Do We Have So Far?............................94
Stepwise Refinement: An Example .........................94
Reconsider the Data ..............................95
Correcting Your Program ..............................95
Modifying Your Program .............................95
Tracing Your Program ..............................95
Coding Style ..................................96
Part 2. Reference ..............................101
Chapter 11. Introduction .............................103
Who Should Read This Reference..........................103
How to Use This Reference ............................103
Overview of Product Features ...........................104
SAA Level 2 REXX Language Support Under REXX/CICS ................104
Support for the Interpretive Execution of REXX Execs .................104
CICS-Based Text Editor for REXX Execs and Data ..................104
VSAM-Based File System for REXX Execs and Data ..................104
VSE Librarian Sublibraries............................104
Dynamic Support for EXEC CICS Commands ....................105
REXX Interface to CEDA and CEMT Transaction Programs ...............105
High-level Client/Server Support .........................105
Support for Commands Written in REXX ......................105
Command Definition of REXX Commands ......................105
Support for System and User Profile Execs .....................105
Shared Execs in Virtual Storage .........................105
SQL Interface ................................106
How to Read the Syntax Diagrams .........................106
Chapter 12. REXX General Concepts ........................109
Structure and General Syntax ...........................109
Characters .................................110
Comments .................................110
Tokens ...................................111
Implied Semicolons ..............................114
Continuations ................................115
Expressions and Operators ............................115
Expressions .................................115
Contents v
Operators ..................................115
Parentheses and Operator Precedence .......................118
Clauses and Instructions .............................120
Null Clauses .................................120
Labels ...................................120
Instructions .................................120
Assignments .................................120
Keyword Instructions ..............................120
Commands .................................120
Assignments and Symbols.............................121
Constant Symbols ...............................121
Simple Symbols ...............................121
Compound Symbols ..............................122
Stems ...................................123
Commands to External Environments ........................124
Environment .................................124
Commands .................................124
Basic Structure of REXX Running Under CICS .....................125
REXX Exec Invocation .............................125
Where Execs Execute .............................126
Locating and Loading Execs ...........................126
Editing Execs ................................126
REXX File System ..............................126
Control of Exec Execution Search Order ......................127
Adding User Written Commands .........................127
Support of Standard REXX Features .........................127
SAY and TRACE Statements...........................127
PULL and PARSE EXTERNAL Statements......................127
REXX Stack Support..............................127
REXX Function Support ............................127
REXX Command Environment Support ........................128
Adding REXX Host Command Environments .....................128
Support of Standard CICS Features/Facilities......................128
CICS Mapped I/O Support............................128
Dataset I/O Services ..............................128
Interfaces to CICS Facilities and Services ......................128
Issuing User Applications From Execs .......................128
REXX Interfaces to CICS Storage Queues......................128
Pseudo-conversational Transaction Support .....................128
Interfaces to Other Programming Languages ......................129
DBCS Support ................................129
Miscellaneous Features.............................129
Chapter 13. Keyword Instructions .........................131
ADDRESS ..................................132
ARG.....................................134
CALL ....................................135
DO.....................................138
DROP ....................................142
EXIT.....................................143
IF......................................144
INTERPRET ..................................145
ITERATE ...................................147
LEAVE....................................148
NOP.....................................149
NUMERIC...................................150
vi CICS TS for VSE/ESA: REXX Guide
OPTIONS ...................................151
PARSE ....................................152
PROCEDURE .................................155
PULL ....................................158
PUSH ....................................159
QUEUE ...................................160
RETURN ...................................161
SAY.....................................162
SELECT ...................................163
SIGNAL ...................................164
TRACE....................................166
UPPER....................................170
Chapter 14. Functions ..............................171
Syntax ....................................171
Functions and Subroutines ............................171
Search Order ................................172
Errors During Execution ............................173
Built-in Functions ................................174
ABBREV (Abbreviation).............................175
ABS (Absolute Value) .............................175
ADDRESS .................................175
ARG (Argument) ...............................175
BITAND (Bit by Bit AND) ............................176
BITOR (Bit by Bit OR) .............................177
BITXOR (Bit by Bit Exclusive OR) .........................177
B2X (Binary to Hexadecimal)...........................177
CENTER/CENTRE ..............................178
COMPARE .................................178
CONDITION .................................178
COPIES ..................................179
C2D (Character to Decimal) ...........................179
C2X (Character to Hexadecimal) .........................180
DATATYPE .................................180
DATE...................................181
DBCS (Double-Byte Character Set Functions) ....................183
DELSTR (Delete String) ............................183
DELWORD (Delete Word) ............................183
DIGITS ...................................183
D2C (Decimal to Character) ...........................184
D2X (Decimal to Hexadecimal) ..........................184
ERRORTEXT ................................185
EXTERNALS ................................185
FIND ...................................185
FORM ...................................185
FORMAT ..................................185
FUZZ ...................................186
INDEX ...................................187
INSERT ..................................187
JUSTIFY ..................................187
LASTPOS (Last Position) ............................188
LEFT ...................................188
LENGTH ..................................188
LINESIZE ..................................188
MAX (Maximum) ...............................189
MIN (Minimum) ................................189
Contents vii
OVERLAY..................................189
POS (Position) ................................190
QUEUED ..................................190
RANDOM ..................................190
REVERSE .................................191
RIGHT ...................................191
SIGN ...................................191
SOURCELINE ................................191
SPACE...................................192
STORAGE .................................192
STRIP ...................................192
SUBSTR (Substring) ..............................192
SUBWORD .................................193
SYMBOL ..................................193
TIME ...................................194
TRACE...................................195
TRANSLATE.................................195
TRUNC (Truncate) ..............................196
USERID ..................................196
VALUE ...................................196
VERIFY ..................................197
WORD ...................................198
WORDINDEX ................................198
WORDLENGTH ...............................198
WORDPOS (Word Position) ...........................198
WORDS ..................................199
XRANGE (Hexadecimal Range)..........................199
X2B (Hexadecimal to Binary)...........................199
X2C (Hexadecimal to Character) .........................200
X2D (Hexadecimal to Decimal) ..........................200
External Functions Provided in REXX/CICS ......................201
STORAGE .................................201
SYSSBA ..................................201
Chapter 15. Parsing...............................203
General Description ...............................203
Simple Templates for Parsing into Words ......................203
Templates Containing String Patterns........................205
Templates Containing Positional (Numeric) Patterns ..................206
Parsing with Variable Patterns ..........................209
Using UPPER ................................209
Parsing Instructions Summary ..........................210
Parsing Instructions Examples ..........................210
Advanced Topics in Parsing ............................211
Parsing Multiple Strings .............................211
Combining String and Positional Patterns: A Special Case ................212
Parsing with DBCS Characters ..........................212
Details of Steps in Parsing ...........................213
Chapter 16. Numbers and Arithmetic ........................217
Introduction ..................................217
Definition ...................................218
Numbers ..................................218
Precision ..................................218
Arithmetic Operators ..............................218
Arithmetic Operation Rules—Basic Operators.....................219
viii CICS TS for VSE/ESA: REXX Guide
Arithmetic Operation Rules—Additional Operators ...................220
Numeric Comparisons .............................222
Exponential Notation ..............................222
Numeric Information ..............................224
Whole Numbers ...............................224
Numbers Used Directly by REXX .........................224
Errors ...................................224
Chapter 17. Conditions and Condition Traps .....................225
Action Taken When a Condition Is Not Trapped .....................226
Action Taken When a Condition Is Trapped ......................226
Condition Information ..............................228
Descriptive Strings ..............................228
Special Variables ................................228
The Special Variable RC ............................228
The Special Variable SIGL............................228
Chapter 18. REXX/CICS Text Editor ........................231
Invocation ...................................231
Screen Format .................................232
Prefix Commands ................................232
Individual Line Commands............................232
Consecutive Block Commands ..........................233
Destination Commands .............................233
Macros Under the REXX/CICS Editor ........................233
Command Line Commands ............................234
ARBCHAR .................................234
ARGS ...................................234
BACKWARD .................................235
BOTTOM ..................................235
CANCEL ..................................236
CASE ...................................236
CHANGE ..................................237
CMDLINE ..................................237
CTLCHAR .................................238
CURLINE ..................................238
DISPLAY ..................................239
DOWN ...................................239
EDIT....................................240
EXEC ...................................241
FILE ....................................241
FIND ...................................242
FORWARD.................................243
GET....................................243
GETLIB ..................................243
INPUT ...................................244
JOIN....................................244
LEFT ...................................245
LINEADD ..................................245
LPREFIX ..................................245
MACRO ..................................246
MSGLINE ..................................246
NULLS ...................................247
NUMBERS .................................247
PFKEY ...................................248
PFKLINE ..................................248
Contents ix
QQUIT ...................................249
QUERY ..................................249
QUIT ...................................250
RESERVED .................................250
RESET ...................................251
RIGHT ...................................251
SAVE...................................252
SORT...................................252
SPLIT ...................................253
STRIP ...................................253
SYNONYM .................................254
TOP....................................254
TRUNC...................................254
UP....................................255
Chapter 19. REXX/CICS File System ........................257
File Pools, Directories, and Files ..........................257
Current Directory and Path ............................258
Security ...................................259
RFS commands ................................259
AUTH ...................................259
CKDIR ...................................260
CKFILE ..................................260
COPY ...................................261
DELETE ..................................261
DISKR ...................................261
DISKW ...................................262
GETDIR..................................262
MKDIR ...................................263
RDIR ...................................263
RENAME ..................................264
File List Utility .................................264
Invocation ..................................264
Macros under the REXX/CICS File List Utility......................265
FLST Commands ................................265
CANCEL ..................................265
CD....................................266
COPY ...................................266
DELETE ..................................267
DOWN ...................................267
END....................................267
EXEC ...................................267
FLST ...................................268
MACRO ..................................269
PFKEY ...................................269
REFRESH .................................270
RENAME ..................................270
SORT...................................271
SYNONYM .................................271
UP....................................272
FLST Return Codes ...............................272
Running Execs and Transactions from FLST ......................272
Chapter 20. REXX/CICS List System ........................273
Directories and Lists ...............................273
Current Directory and Path ............................274
xCICS TS for VSE/ESA: REXX Guide
Security ...................................274
RLS commands ................................274
CKDIR ...................................275
DELETE ..................................275
LPULL ...................................275
LPUSH ...................................276
LQUEUE ..................................276
MKDIR ...................................277
READ ...................................277
VARDROP .................................278
VARGET ..................................278
VARPUT ..................................279
WRITE ...................................279
Chapter 21. REXX/CICS Command Definition .....................281
Background ..................................281
Highlights ...................................281
Accomplishing Command Definition .........................281
Command Arguments Passed to REXX Programs ....................282
Command Arguments Passed to Assembler Programs ..................282
CICPARMS Control Block .............................283
Non-REXX Language Interfaces ..........................284
CICGETV - Call to Get, Set, or Drop a REXX Variable ..................284
Operands ..................................284
Notes ...................................284
Chapter 22. REXX/CICS DB2 Interface .......................285
Programming Considerations............................285
Embedding SQL Statements ............................285
Receiving the Results .............................287
Using the SQL Communications Area .......................288
Example Using SQL Statements .........................288
Chapter 23. REXX/CICS High-level Client/Server Support ................291
Overview ...................................291
High-level, Natural, Transparent REXX Client Interface .................291
Support for REXX-based Application Clients and Servers ................291
Value of REXX in Client/Server Computing.......................291
REXX/CICS Client Exec Example ..........................292
REXX/CICS Server Exec Example..........................293
Chapter 24. REXX/CICS Panel Facility .......................295
Facility ....................................295
Example of Panel Definition ...........................295
Defining Panels.................................296
Defining the Field Control Characters with the '.DEFINE' Verb ...............296
.DEFINE ...................................297
Default field control characters ..........................297
Operands ..................................298
Options...................................298
Defining the Actual PANEL Layout with the '.PANEL' Verb .................299
.PANEL....................................300
Operands ..................................301
Panel Generation and Panel Input/Output .......................301
PANEL RUNTIME ................................302
Operands ..................................303
Contents xi
Options...................................304
PANEL Variables ...............................305
Panel Facility Return Code Information .......................306
Return Codes ................................307
System Error Reason Codes ...........................307
Programmer Introduced Warning/Error Reason Codes .................307
State Codes and Input Codes ..........................308
Location Codes................................310
Examples of Sample Panels ............................310
Example 1 .................................310
Example 2 .................................311
Example 3 .................................311
Example 4 .................................312
Example 5 .................................312
Example of a REXX Panel Program .........................312
Chapter 25. REXX/CICS Commands ........................319
AUTHUSER ..................................320
Operands ..................................320
Return Codes ................................320
Example ..................................320
Notes ...................................320
CD.....................................321
Operands ..................................321
Return Codes ................................321
Examples ..................................321
Note ....................................321
CEDA ....................................323
Operands ..................................323
Return Codes ................................323
Example ..................................323
CEMT ....................................324
Operands ..................................324
Return Codes ................................324
Example ..................................324
CLD.....................................325
Operands ..................................325
Return Codes ................................325
Examples ..................................325
Notes ...................................325
CONVTMAP ..................................326
Operands ..................................326
Return Codes ................................326
Example ..................................326
COPYR2S ..................................327
Operands ..................................327
Return Codes ................................328
Examples ..................................328
COPYS2R ..................................329
Operands ..................................329
Return Codes ................................330
Example ..................................330
Notes ...................................330
C2S.....................................331
Operands ..................................331
Return Codes ................................331
xii CICS TS for VSE/ESA: REXX Guide
Example ..................................331
Notes ...................................331
DEFCMD ...................................332
Operands ..................................332
Return Codes ................................333
Example ..................................333
Notes ...................................333
DEFSCMD ..................................335
Operands ..................................335
Return Codes ................................336
Example ..................................336
Notes ...................................336
DEFTRNID ..................................338
Operands ..................................338
Return Codes ................................338
Example ..................................338
Notes ...................................338
DIR.....................................339
Operands ..................................339
Return Codes ................................339
Examples ..................................339
Note ....................................339
EDIT.....................................340
Operands ..................................340
Return Codes ................................340
Example ..................................340
Note ....................................340
EXEC ....................................341
Operands ..................................341
Return Codes ................................341
Example ..................................341
EXECDROP ..................................342
Operands ..................................342
Return Codes ................................342
Example ..................................342
Note ....................................343
EXECIO ...................................344
Operands ..................................344
Return Codes ................................344
Examples ..................................344
Notes ...................................344
EXECLOAD ..................................346
Operands ..................................346
Return Codes ................................346
Example ..................................347
Notes ...................................347
EXECMAP ..................................348
Return Codes ................................348
Example ..................................348
EXPORT ...................................349
Operands ..................................349
Return Codes ................................349
Example ..................................349
Notes ...................................349
FILEPOOL ..................................350
Operands ..................................350
Contents xiii
Return Codes ................................350
Example ..................................351
Note ....................................351
FLST ....................................352
Operands ..................................352
Return Codes ................................352
Example ..................................352
Notes ...................................352
GETVERS ..................................353
Return Codes ................................353
Example ..................................353
HELP ....................................354
Operands ..................................354
Return Codes ................................354
IMPORT ...................................355
Operands ..................................355
Return Codes ................................355
Example ..................................355
LISTCMD ...................................356
Operands ..................................356
Return Codes ................................356
Example ..................................356
LISTCLIB ...................................357
Operands ..................................357
Return Codes ................................357
Example ..................................357
LISTELIB ...................................358
Operands ..................................358
Return Codes ................................358
Example ..................................358
LISTPOOL ..................................359
Operands ..................................359
Return Codes ................................359
Example ..................................359
Note ....................................359
LISTTRNID ..................................360
Return Codes ................................360
Example ..................................360
PATH....................................361
Operands ..................................361
Return Codes ................................361
Examples ..................................361
Notes ...................................361
PSEUDO ...................................362
Operands ..................................362
Return Codes ................................362
Example ..................................362
Note ....................................362
RFS.....................................363
Operands ..................................363
Return Codes ................................364
Note ....................................365
RLS.....................................366
Operands ..................................366
Return Codes ................................367
SCRNINFO ..................................368
xiv CICS TS for VSE/ESA: REXX Guide
Return Codes ................................368
Example ..................................368
Notes ...................................368
SET.....................................369
Operands ..................................369
Return Codes ................................370
Example ..................................370
Notes ...................................370
SETSYS ...................................371
Operands ..................................371
Return Codes ................................372
Example ..................................372
S2C.....................................373
Operands ..................................373
Return Codes ................................373
Example ..................................373
Notes ...................................373
TERMID ...................................374
Return Codes ................................374
Example ..................................374
WAITREAD ..................................375
Return Codes ................................375
Example ..................................375
Note ....................................375
WAITREQ...................................376
Return Codes ................................376
Example ..................................376
Part 3. Appendixes .............................377
Appendix A. Error Numbers and Messages .....................379
Appendix B. Return Codes ............................387
Panel Facility .................................387
SQL.....................................387
RFS and FLST .................................387
EDITOR and EDIT ...............................387
DIR.....................................388
SET.....................................388
CD.....................................388
PATH....................................388
RLS.....................................388
LISTCMD ...................................389
CLD.....................................389
DEFCMD ...................................389
DEFSCMD ..................................389
DEFTRNID ..................................390
EXECDROP ..................................390
EXECLOAD ..................................390
EXECMAP ..................................390
EXPORT and IMPORT ..............................390
FILEPOOL ..................................391
LISTCLIB and LISTELIB .............................391
GETVERS ..................................391
COPYR2S ..................................391
COPYS2R ..................................391
Contents xv
LISTPOOL ..................................392
LISTTRNID ..................................392
C2S.....................................392
PSEUDO ...................................392
AUTHUSER ..................................392
SETSYS ...................................392
S2C.....................................392
TERMID ...................................392
WAITREAD ..................................393
WAITREQ...................................393
EXEC ....................................393
CEDA and CEMT ................................393
EXECIO ...................................393
CONVTMAP ..................................393
SCRNINFO ..................................393
CICS ....................................394
Appendix C. Double-Byte Character Set (DBCS) Support ................395
General Description ...............................395
Enabling DBCS Data Operations and Symbol Use ...................396
Symbols and Strings ..............................396
Validation ..................................397
Instruction Examples ..............................397
DBCS Function Handling .............................399
Built-in Function Examples ...........................400
DBCS Processing Functions ............................404
Counting Option ...............................404
Function Descriptions ..............................404
DBADJUST .................................404
DBBRACKET ................................404
DBCENTER .................................405
DBCJUSTIFY ................................405
DBLEFT ..................................405
DBRIGHT ..................................406
DBRLEFT ..................................406
DBRRIGHT .................................406
DBTODBCS .................................407
DBTOSBCS .................................407
DBUNBRACKET ...............................407
DBVALIDATE ................................408
DBWIDTH..................................408
Appendix D. Reserved Keywords and Special Variables ................409
Reserved Keywords ...............................409
Special Variables ................................409
Appendix E. Debug Aids .............................411
Interactive Debugging of Programs .........................411
Interrupting Execution and Controlling Tracing .....................412
Appendix F. REXX/CICS Business Value Discussion ..................413
Business Solutions ...............................413
Product Positioning ...............................415
Appendix G. System Definition/Customization/Administration ..............417
Authorized REXX/CICS Commands/Authorized Command Options ..............417
xvi CICS TS for VSE/ESA: REXX Guide
System Profile Exec ...............................417
Authorized REXX/CICS VSE Librarian sublibraries ....................417
Defining Authorized Users .............................417
Setting System Options ..............................418
Defining and Initializing a REXX File System (RFS) File Pool ................418
Adding Files to a REXX File System (RFS) File Pool ...................418
RFS File Sharing Authorization ...........................418
Creating a PLT Entry for CICSTART .........................418
Security exits .................................418
CICSEXC1 .................................418
CICSECX2 .................................419
Appendix H. Security ..............................421
REXX/CICS Supports Multiple Transaction Identifiers ...................421
REXX/CICS File Security .............................421
ESA/VSE Command Level Security .........................421
REXX/CICS Authorized Command Support ......................421
Security Definitions ...............................422
REXX/CICS General Users ...........................422
REXX/CICS Authorized Users ..........................422
REXX/CICS Authorized Commands ........................422
REXX/CICS Authorized Execs ..........................422
REXX/CICS System Sublibraries .........................422
Appendix I. Performance Considerations ......................425
Appendix J. Basic Mapping Support Example ....................427
Appendix K. Post-Installation Configuration .....................431
Create the RFS Filepools .............................431
Install Resource Definitions ............................431
Update LSRPOOL Definitions ...........................431
Rename supplied Procedures ...........................431
Update CICSTART.PROC .............................432
Update CICS Initialization JCL ...........................432
Format the RFS Filepools .............................433
Create the Help Files ..............................433
Verify the Installation ...............................434
Configure the REXX DB2 Interface .........................435
Bibliography .................................437
CICS Transaction Server for VSE/ESA Release 1 library .................437
Where to Find More Information ..........................438
Books from VSE/ESA 2.5 base program libraries ....................438
VSE/ESA Version 2 Release 5 ..........................438
High-Level Assembler Language (HLASM)......................439
Language Environment for VSE/ESA (LE/VSE) ....................439
VSE/ICCF..................................439
VSE/POWER ................................439
VSE/VSAM .................................440
VTAM for VSE/ESA ..............................440
Books from VSE/ESA 2.5 optional program libraries ...................440
C for VSE/ESA (C/VSE) ............................440
COBOL for VSE/ESA (COBOL/VSE) ........................440
DB2 Server for VSE ..............................441
DL/I VSE ..................................441
Contents xvii
PL/I for VSE/ESA (PL/I VSE) ...........................441
Screen Definition Facility II (SDF II) ........................441
Notices ...................................443
Trademarks ..................................445
Index ....................................447
Sending your comments to IBM ..........................455
xviii CICS TS for VSE/ESA: REXX Guide
Preface
What this book is about
This book describes REXX/CICS or REXX for CICS®Transaction Server for VSE/ESA. This IBM®program
product provides a native REXX-based application development, customization, prototyping, and
procedures language environment for REXX/CICS, along with associated runtime facilities.
Who this book is for
This book is for users who need to refer to CICS Transaction Server for VSE/ESA REXX instructions and
functions, and for those who need to learn more details about REXX language items such as parsing. It is
also intended for anyone who wants to learn how to write REXX programs. The type of users include:
application programmers, system programmers, end users, administrators, developers, testers, and
support personnel.
What you need to know to understand this book
Within this book, reference may be made to Release 1. The function described in this book has
been added since the release of CICS Transaction Server for VSE/ESA Release 1 and can be
identified within the code as 1.1.1.
If you are not an experienced programmer, and are new to REXX, you should read the guide part of this
book, see page 1.
The book contains two parts: a user's guide and a reference. The user's guide section will help you
become familiar with REXX for CICS Transaction Server for VSE/ESA. The reference section contains the
CICS Transaction Server for VSE/ESA REXX instructions, functions, and commands. The instructions,
functions, and commands are listed alphabetically in their own sections. Also included are details about
general concepts you need to know in order to program in REXX.
The programming language described by this book is called the REstructured eXtended eXecutor
language (commonly referred to as REXX). This book also describes how the CICS Transaction Server for
VSE/ESA REXX language processor (shortened, hereafter, to the language processor) processes or
interprets the REstructured eXtended eXecutor language.
Prerequisites
REXX/CICS runs under CICS Transaction Server for VSE/ESA Version 1 or above. There are no other
prerequisites (other than the prerequisites that CICS TS for VSE/ESA requires).
© Copyright IBM Corp. 1992, 2010 xix
xx CICS TS for VSE/ESA: REXX Guide
Part 1. User's Guide
© Copyright IBM Corp. 1992, 2010 1
2CICS TS for VSE/ESA: REXX Guide
Chapter 1. Introduction
This chapter describes the REXX programming language and some of its features.
What is REXX?
REXX is an extremely versatile programming language. Common programming structure, readability, and
free format make it a good language for beginners and general users. REXX is also suitable for more
experienced computer professionals because it can be intermixed with commands to host environments, it
provides powerful functions, and it has extensive mathematical capabilities.
REXX programs can do many tasks under CICS. These include issuing EXEC CICS commands, SQL
statements, as well as commands to the CEDA (Resource Definition Online Transaction) and CEMT
(Master Terminal Transaction) utilities.
Features of REXX
In addition to its versatility, REXX has many other features, some of which are:
Ease of use
The REXX language is easy to read and write because many instructions are meaningful English words.
Unlike some lower level programming languages that use abbreviations, REXX instructions are common
words, such as SAY, PULL, IF...THEN...ELSE..., DO...END, and EXIT.
Free format
There are few rules about REXX format. You need not start an instruction in a particular column. You can
skip spaces in a line or skip entire lines. You can have an instruction span of many lines, or have multiple
instructions on one line. You need not predefine variables. You can type instructions in upper, lower, or
mixed case. The few rules about REXX format are covered in section “Syntax of REXX Instructions” on
page 6.
Convenient built-in functions
REXX supplies built-in functions that perform various processing, searching, and comparison operations
for both text and numbers. Other built-in functions provide formatting capabilities and arithmetic
calculations.
Debugging capabilities
When a REXX program running in REXX/CICS encounters an error, REXX writes messages describing the
error. You can also use the REXX TRACE instruction and the interactive debug facility to locate errors in
programs.
Interpreted language
The REXX/CICS product includes the REXX/CICS interpreter. When a REXX program runs, the interpreter
directly processes each line. Languages that are not interpreted must be compiled into machine language
and possibly link-edited before they are run.
Extensive parsing capabilities
REXX includes extensive parsing capabilities for character manipulation. This parsing capability lets you
set up a pattern to separate characters, numbers, and mixed input.
© Copyright IBM Corp. 1992, 2010 3
Components of REXX
The various components of REXX make it a powerful tool for programmers. REXX is made up of:
vClauses, which can be instructions, null clauses, or labels. Instructions can be:
– Keyword instructions
– Assignments
– Commands (REXX/CICS and CICS commands and SQL).
The language processor processes keyword instructions and assignments.
vBuilt-in functions — These functions are built into the language processor and provide convenient
processing options.
vExternal functions — REXX/CICS provides these functions that interact with the system to do specific
tasks for REXX.
vData stack functions — A data stack can store data for I/O and other types of processing.
Introduction
4CICS TS for VSE/ESA: REXX Guide
Chapter 2. Writing and Running a REXX Program
This chapter introduces programs and their syntax, describes the steps involved in writing and running
programs, and explains concepts you need to understand to avoid common problems.
What you need to run a REXX Program?
Before you can run a REXX Program, you must configure the REXX support. Go through the following
steps:
1. Create the RFS Filepools
2. Install Resource Definitions
3. Update LSRPOOL Definitions
4. Rename supplied Procedures
5. Update CICSTART.PROC
6. Update CICS Initialization JCL
7. Format the RFS Filepools
8. Create the Help Files
9. Verify the Installation
10. Configure the REXX DB2 Interface
For details on configuration, see Appendix K, “Post-Installation Configuration,” on page 431.
What is a REXX Program?
A REXX program consists of REXX language instructions that the REXX interpreter interprets directly. A
program can also contain commands that the host environment executes, such as CICS commands (see
page 81).
One advantage of the REXX language is its similarity to ordinary English. This similarity makes it easy to
read and write a REXX program. For example, to write a line of output, you use the REXX instruction SAY
followed by the text you want written.
This program starts with a comment line to identify it as a REXX program. A comment begins with /* and
ends with */. More about comments and why you might need a REXX program identifier appears later on
page 10.
When you run the program, the SAY instruction sends to the terminal output device:
Hello world!
Even in a longer program, the instructions are similar to ordinary English and are easy to understand. For
example, you could use the following to call the program ADDTWO, which adds two numbers: From a
CICS terminal you would clear the screen and enter:
REXX addtwo
For this example, the first number you will enter is 42, and the second number is 21. Here is the ADDTWO
program:
/* Sample REXX Program */
SAY ’Hello world!’
Figure 1. Example of a Simple Program
© Copyright IBM Corp. 1992, 2010 5
When you run the example program, the first PULL instruction assigns the variable number1 the value 42.
The second PULL instruction assigns the variable number2 the value 21. The next line contains an
assignment. The language processor adds the values in number1 and number2 and assigns the result, 63,
to sum. Finally, the SAY instruction displays the output line:
The sum of the two numbers is 63.
Before you try any examples, please read the next two sections, “Syntax of REXX Instructions” and
“Typing in a Program” on page 11.
Syntax of REXX Instructions
Some programming languages have rigid rules about how and where you enter characters on each line.
For example, assembler statements must begin in a certain column. REXX, on the other hand, has simple
syntax rules. You can use upper or lower or mixed case. REXX has no restrictions about the columns in
which you can type.
An instruction can begin in any column on any line. The following are all valid instructions.
SAY ’You can type in any column’
SAY ’You can type in any column’
SAY ’You can type in any column’
These instructions are sent to the terminal output device:
You can type in any column
You can type in any column
You can type in any column
The Format of REXX Instructions
The REXX language has free format. This means you can insert extra spaces between words. For
example, the following all mean the same:
total=num1+num2
total =num1+num2
total = num1+num2
total = num1 + num2
You can also insert blank lines throughout a program without causing an error.
The Letter Case of REXX Instructions
You can enter a REXX instruction in lowercase, uppercase, or mixed case. For example, SAY,Say, and say
all have the same meaning. The language processor translates alphabetic characters to uppercase, unless
you enclose them in single or double quotation marks.
Using Quotation Marks in an Instruction
A series of characters within matching quotation marks is a literal string. The following examples contain
literal strings.
/**************************** REXX *********************************/
/* This program adds two numbers and produces their sum. */
/*******************************************************************/
say ’Enter first number.’
PULL number1 /* Assigns: number1=42 */
say ’Enter second number.’
PULL number2 /* Assigns: number2=21 */
sum = number1 + number2
SAY ’The sum of the two numbers is’ sum’.’
Figure 2. Example of a Longer Program
Writing and Running a REXX Program
6CICS TS for VSE/ESA: REXX Guide
SAY ’This is a REXX literal string.’ /* Using single quotation marks */
SAY "This is a REXX literal string." /* Using double quotation marks */
Do not enclose a literal string with one each of the two different types of quotation marks. For example,
the following is incorrect:
SAY ’This is a REXX literal string." /* Using mismatched quotation marks */
If you omit the quotation marks around a literal string in a SAY instruction, the language processor usually
translates the statement to uppercase. For example,
SAY This is a REXX string.
results in:
THIS IS A REXX STRING.
(This assumes none of the words is the name of a variable that you have already assigned a value. In
REXX, the default value of a variable is its own name in uppercase.)
If a string contains an apostrophe, you can enclose the literal string in double quotation marks.
SAY "This isn’t difficult!"
You can also use two single quotation marks in place of the apostrophe, because a pair of single quotation
marks is processed as one.
SAY ’This isn’’t difficult!’
Either way, the outcome is the same.
This isn’t difficult!
Ending an instruction
A line usually contains one instruction except when it contains a semicolon (;) or ends with a comma (,).
The end of the line or a semicolon indicates the end of an instruction. If you put one instruction on a line,
the end of the line delineates the end of the instruction. If you put multiple instructions on one line, you
must separate adjacent instructions with a semicolon.
SAY ’Hi!’; say ’Hi again!’; say ’Hi for the last time!’
This example would result in three lines.
Hi!
Hi again!
Hi for the last time!
Continuing an instruction
A comma is the continuation character. It indicates that the instruction continues to the next line. The
comma, when used in this manner, also adds a space when the lines are concatenated. Here is how the
comma continuation character works when a literal string is being continued on the next line.
SAY ’This is an extended’,
’REXX literal string.’
The comma at the end of the first line adds a space (between extended and REXX when the two lines are
concatenated for output. A single line results:
This is an extended REXX literal string.
The following two instructions are identical and yield the same result:
SAY ’This is’,
’a string.’
Writing and Running a REXX Program
Chapter 2. Writing and Running a REXX Program 7
SAY ’This is’ ’a string.’
The space between the two separate strings is preserved:
This is a string.
Continuing a literal string without adding a space
If you need to continue an instruction to a second or more lines, but do not want REXX to add spaces in
the line, use the concatenation operand (two single OR bars, ||).
SAY ’This is an extended literal string that is bro’||,
’ken in an awkward place.’
This example results in one line no space in the word “broken”.
This is an extended literal string that is broken in an awkward place.
Also note that the following two instructions are identical and yield the same result:
SAY ’This is’ ||,
’a string.’
SAY ’This is’ || ’a string.’
These examples result in:
This isa string.
In both examples, the concatenation operator deletes spaces between the two strings.
The following example demonstrates the free format of REXX.
Running this example results in six lines of identical output, followed by one indented line.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
Thus, you can begin an instruction anywhere on a line, you can insert blank lines, and you can insert extra
spaces between words in an instruction. The language processor ignores blank lines, and it ignores
spaces that are greater than one. This flexibility of format lets you insert blank lines and spaces to make a
program easier to read.
Blanks and spaces are only significant during parsing, see section “Parsing Data” on page 73.
/************************* REXX *****************************/
SAY ’This is a REXX literal string.’
SAY ’This is a REXX literal string.’
SAY ’This is a REXX literal string.’
SAY,
’This’,
’is’,
’a’,
’REXX’,
’literal’,
’string.’
SAY’This is a REXX literal string.’;SAY’This is a REXX literal string.’
SAY ’ This is a REXX literal string.’
Figure 3. Example of Free Format
Writing and Running a REXX Program
8CICS TS for VSE/ESA: REXX Guide
Types of REXX Clauses
REXX clauses can be: instructions, null clauses, and labels. Instructions can be keyword instructions,
assignments, or commands. The following example shows a program with these types of clauses. A
description of each type of clause follows the example.
Keyword Instructions
A keyword instruction tells the language processor to do something. It begins with a REXX keyword that
identifies what the language processor is to do. For example, DO can group instructions and execute them
repetitively, and IF tests whether a condition is met. SAY writes to the current terminal output device.
IF, THEN and ELSE are three keywords that work together in one instruction. Each keyword forms a
clause, which is a subset of an instruction. If the expression that follows the IF keyword is true, the
instruction that follows the THEN keyword is processed. Otherwise, the instruction that follows the ELSE
keyword is processed. (Note that a semicolon is needed before the ELSE if you are putting an ELSE
clause on the same line with a THEN.) If you want to put more than one instruction after a THEN or ELSE,
use a DO before the group of instructions and an END after them. More information about the IF
instruction appears in section “Using Conditional Instructions” on page 33.
The EXIT keyword tells the language processor to end the program. Using EXIT in the preceding example
is necessary because, otherwise, the language processor would execute the code in the subroutine after
the label sub:. EXIT is not necessary in some programs (such as those without subroutines), but it is good
programming practice to include it. More about EXIT appears in section “EXIT Instruction” on page 48.
Assignment
An assignment gives a value to a variable or changes the current value of a variable. A simple assignment
instruction is:
number = 4
In the preceding program, a simple assignment instruction is: store_a=0. The left side of the assignment
(before the equal sign) contains the name of the variable to receive a value from the right side (after the
equal sign). The right side can be an actual value (such as 4) or an expression. An expression is
something that needs to be evaluated, such as an arithmetic expression. The expression can contain
numbers, variables, or both.
number=4+4
number = number + 4
In the first example, the value of number is 8. If the second example directly followed the first in a program,
the value of number would become 12. More about expressions is in section “Using Expressions” on page
21.
/* QUOTA REXX program. Two car dealerships are competing to */
/* sell the most cars in 30 days. Who will win? */
store_a=0; store_b=0
DO 30
CALL sub
END
IF store_a>store_b THEN SAY "Store_a wins!"
ELSE IF store_b>store_a THEN SAY "Store_b wins!"
ELSE SAY "It’s a tie!"
EXIT
sub:
store_a=store_a+RANDOM(0,20) /* RANDOM returns a random number in */
store_b=store_b+RANDOM(0,20) /* in specified range, here 0 to 20 */
RETURN
Writing and Running a REXX Program
Chapter 2. Writing and Running a REXX Program 9
Label
A label, such as sub: is a symbolic name followed by a colon. A label can contain either single- or
double-byte characters or a combination of single- and double-byte characters. (Double-byte characters
are valid only if OPTIONS ETMODE is the first instruction in your program.) A label identifies a portion of
the program and is commonly used in subroutines and functions, and with the SIGNAL instruction. (Note
that you need to include a RETURN instruction at the end of a subroutine to transfer control back to the
main program.) More about the use of labels appears in Chapter 6, “Writing Subroutines and Functions,”
on page 57 and section “SIGNAL Instruction” on page 50.
Null Clause
A null clause consists of only blanks or comments or both. The language processor ignores null clauses,
but they make a program easier to read.
Comments
A comment begins with /* and ends with */. Comments can be on one or more lines or on part of a
line. You can put information in a comment that might not be obvious to a person reading the
REXX instructions. Comments at the beginning of a program can describe the overall purpose of
the program and perhaps list special considerations. A comment next to an individual instruction
can clarify its purpose.
Note: REXX/CICS does not require that a REXX program begin with a comment. However, for
portability reasons, you may want to start each REXX program with a comment that
includes the word REXX.
Not every language processor requires this program identifier. However, to run the same exec on
MVS TSO and CICS, you should include the /* REXX */ program identifier to satisfy TSO
requirements.
Blank lines
Blank lines separate groups of instructions and aid readability. The more readable a program is,
the easier it is to understand and maintain.
Commands
A command is a clause consisting of only an expression. Commands are sent to a previously defined
environment for processing. (You should enclose in quotation marks any part of the expression not to be
evaluated.) The example program did not include any commands. The following example includes a
command in an ADDRESS instruction:
/* REXX program including a command */
ADDRESS REXXCICS ’DIR’
ADDRESS is a keyword instruction. When you specify an environment and a command on an ADDRESS
instruction, a single command is sent to the environment you specify. In this case, the environment is
REXXCICS. The command is the expression that follows the environment:
’DIR’
The DIR command lists the files in your current file system directory. For more details about changing the
host command environment, see section “Changing the Host Command Environment” on page 83.
More information about issuing commands appears in Chapter 8, “Using Commands from a program,” on
page 81.
Programs Using Double-Byte Character Set Names
You can use double-byte character set (DBCS) names in your REXX programs for literal strings, symbols,
and comments. Such character strings can be single-byte, double-byte, or a combination of both. To use
DBCS names, OPTIONS ETMODE must be the first instruction in the program. This specifies that the
language processor should check strings containing DBCS characters for validity. You must enclose DBCS
characters within shift-out (SO) and shift-in (SI) delimiters. (The SO character is X'0E', and the SI
Writing and Running a REXX Program
10 CICS TS for VSE/ESA: REXX Guide
character is X'0F') The SO and SI characters are non-printable. In the following example, the less than (<)
and greater than (>) symbols represent shift-out (SO) and shift-in (SI), respectively. For example,
<.S.Y.M.D> and <.D.B.C.S.R.T.N> represent DBCS symbols in the following example.
Example
The following is an example of a program using a DBCS variable name and a DBCS subroutine
label.
/* REXX */
OPTIONS ’ETMODE’ /* ETMODE to enable DBCS variable names */
<.S.Y.M.D> = 10 /* Variable with DBCS characters between */
/* shift-out (<) and shift-in (>) */
y.<.S.Y.M.D> = JUNK
CALL <.D.B.C.S.R.T.N> /* Call subroutine with DBCS name */
EXIT
<.D.B.C.S.R.T.N>: /* Subroutine with DBCS name */
DOi=1TO10
IF y.i = JUNK THEN /* Does y.i match the DBCS variable’s
value? */
SAY ’Value of the DBCS variable is : ’ <.S.Y.M.D>
END
RETURN
Typing in a Program
When you type in the following program, use the REXX/CICS editor for files that reside in the REXX File
System (RFS).
The name of the program is HELLO EXEC (for now, assume that the file type is exec).
1. Sign on to a CICS Transaction Server for VSE/ESA terminal by entering CESN and supplying your user
ID and password when it is requested.
2. Clear the screen.
3. Type:
edit hello.exec
4. Type in the program, exactly as it is shown in Figure 4, beginning with /* REXX HELLO EXEC */. Then
file it using the EDIT command:
====> file
Now your program is ready to run.
Running a Program
Clear the screen before running an exec. If you want to run a program that has a file type of EXEC, you
type in REXX followed by its file name. In this case, type rexx hello on the command line and press Enter.
Try it!
Suppose your name is Sam. Type sam and press Enter. Hello SAM is displayed.
rexx hello
Hello! What is your name?
sam
Hello SAM
/* REXX HELLO EXEC */
/* A conversation */
say "Hello! What is your name?"
pull who
if who = "" then say "Hello stranger!"
else say "Hello" who
Figure 4. HELLO EXEC
Writing and Running a REXX Program
Chapter 2. Writing and Running a REXX Program 11
Here is what happens:
1. The SAY instruction displays Hello! What is your name?
2. The PULL instruction pauses the program, waiting for a reply.
3. You type sam on the command line and then press Enter.
4. The PULL instruction puts the word SAM into the variable (the place in the computer's storage) called
who.
5. The IF instruction asks, Is who equal to nothing?
who=""
This means, “is the value stored in who equal to nothing?” To find out, REXX substitutes that stored
value for the variable name. So the question now is: Is SAM equal to nothing?
"SAM" = ""
6. Not true. The instruction after then is not processed. Instead, REXX processes the instruction after
else.
7. The SAY instruction displays "Hello" who, which is evaluated as
Hello SAM
Now, here is what happens if you press Enter without typing a response first.
hello
Hello! What is your name?
Hello stranger!
Then again, maybe you did not understand that you had to type in your name. (Perhaps the program
should make your part clearer.) Anyhow, if you just press Enter instead of typing a name:
1. The PULL instruction puts "" (nothing) into the place in the computer's storage called who.
2. Again, the IF instruction tests the variable
who=""
meaning: Is the value of who equal to nothing? When the value of who is substituted, this scans as:
""=""
And this time, it is true.
3. So the instruction after then is processed, and the instruction after else is not.
Interpreting Error Messages
When you run a program that contains an error, an error message often includes the line on which the
error occurred and gives an explanation of the error. Error messages can result from syntax errors and
from computational errors. For example, the following program has a syntax error.
/************************** REXX **********************************/
/* This REXX program contains a deliberate error of not closing */
/* a comment. Without the error, it would pull input to produce */
/* a greeting. */
/******************************************************************/
PULL who /* Get the person’s name.
IF who = ’’ THEN
SAY ’Hello, stranger’
ELSE
SAY ’Hello,’ who
Figure 5. Example of a program with a Syntax Error
Writing and Running a REXX Program
12 CICS TS for VSE/ESA: REXX Guide
When the program runs, the language processor sends the following lines of output.
7 +++ PULL who /* Get the person’s name.IF who =
’’ THEN SAY ’Hello, stranger’ELSE SAY ’Hello,’ who
CICREX453E Error 6 running HELLO EXEC, line 7: Unmatched "/*" or quote
The program runs until the language processor detects the error, the missing */ at the end of the
comment. The PULL instruction does not use the data from the data stack or terminal because this line
contains the syntax error. The program ends, and the language processor sends the error messages.
The first error message begins with the line number of the statement where the language processor
detected the error. Three pluses (+++) and the contents of the statement follow this.
7 +++ PULL who /* Get the person’s name.IF who =
’’ THEN SAY ’Hello, stranger’ ELSE SAY ’Hello,’ who
The second error message begins with the message number. A message containing the program name,
the line where the language processor found the error, and an explanation of the error follow this.
CICREX453E Error 6 running HELLO EXEC, line 7: Unmatched "/*" or quote
For more information about the error, you can go to the message explanations in Appendix A, “Error
Numbers and Messages,” on page 379.
To fix the syntax error in this program, add */ to the end of the comment on line 7.
PULL who /* Get the person’s name. */
How to Prevent Translation to Uppercase
The language processor generally translates alphabetic characters to uppercase before processing them.
The alphabetic characters can be within a program, such as words in a REXX instruction, or they can be
external to a program and processed as input. You can prevent the translation to uppercase as follows:
Characters within a program
To prevent translation of alphabetic characters in a program to uppercase, simply enclose the characters in
single or double quotation marks. The language processor does not change numbers and special
characters, regardless of whether they are in quotation marks. Suppose you use a SAY instruction with a
phrase containing a mixture of alphabetic characters, numbers, and special characters; the language
processor changes only the alphabetic characters.
SAY The bill for lunch comes to £123.51!
results in:
THE BILL FOR LUNCH COMES TO £123.51!
(This example assumes none of the words are the names of variables that have been assigned other
values.)
Quotation marks ensure that information in a program is processed exactly as typed. This is important in
the following situations:
vFor output that must be lowercase or a mixture of uppercase and lowercase.
vTo ensure that commands are processed correctly. For example, if a variable name in a program is the
same as a command name, the program can end in error when the command is issued. It is a good
programming practice to avoid using variable names that are the same as commands and to enclose all
commands in quotation marks.
Writing and Running a REXX Program
Chapter 2. Writing and Running a REXX Program 13
Characters Input to a program
When reading input or passing input from another program, the language processor also changes
alphabetic characters to uppercase before processing them. To prevent translation to uppercase, use the
PARSE instruction.
For example, the following program reads input from the terminal and sends this information to the
terminal output device.
If the input is tyrannosaurus, the language processor produces the output:
TYRANNOSAURUS
To cause the language processor to read input exactly as it is presented, use the PARSE PULL instruction
instead of the PULL instruction.
PARSE PULL animal
Now if the input is TyRannOsauRus, the output is:
TyRannOsauRus
Exercises - Running and Modifying the Example Programs
You can write and run the preceding example. Now change the PULL instruction to a PARSE PULL
instruction and note the difference.
Passing Information to a program
When a program runs, you can pass information to it in several ways:
vBy using PULL to get information from the program stack or terminal input device.
vBy specifying input when calling the program.
Getting Information from the Program Stack or Terminal Input Device
The PULL instruction is one way for a program to receive input. Repeating an earlier example shows this.
Here is how to call the ADDTWO program:
REXX addtwo
Here is the ADDTWO program.
The PULL instruction can extract more than one value at a time from the terminal by separating a line of
input. The following variation of the example shows this.
/************************** REXX ***********************************/
/* This REXX program gets the name of an animal from the input */
/* stream and sends it to the terminal. */
/*******************************************************************/
PULL animal /* Get the animal name.*/
SAY animal
Figure 6. Example of Reading Input and Writing Output
/**************************** REXX ******************************/
/* This program adds two numbers and produces their sum. */
/****************************************************************/
PULL number1
PULL number2
sum = number1 + number2
SAY ’The sum of the two numbers is’ sum’.’
Figure 7. Example of a program That Uses PULL
Writing and Running a REXX Program
14 CICS TS for VSE/ESA: REXX Guide
REXX addtwo 42 21
The PULL instruction extracts the numbers 42 and 21 from the terminal.
Specifying Values When Calling a program
Another way for a program to receive input is through values you specify when you call the program. For
example to pass the two numbers 42 and 21 to a program named ADD, you could use the CICS
command:
REXX add 42 21
The program ADD uses the ARG instruction to assign the input to variables as shown in the following
example.
ARG assigns the first number 42,tonumber1, and the second number 21,tonumber2.
If the number of values is fewer or more than the number of variable names after ARG or PULL, errors
can occur, as the following sections describe.
Specifying Too Few Values
If you specify fewer values than the number of variables after PULL or ARG, the extra variables are set to
the null string. Here is an example in which you pass only one number to the program:
REXX add 42
The language processor assigns the value 42 to number1, the first variable following ARG. It assigns the
null string to number2, the second variable. In this situation, the program ends with an error when it tries to
add the two variables. In other situations, the program might not end in error.
Specifying Too Many Values
When you specify more values than the number of variables following PULL or ARG, the last variable gets
the remaining values. For example, you pass three numbers to the program ADD:
REXX add 42 21 10
The language processor assigns the value 42 to number1, the first variable following ARG. It assigns the
value 21 10 to number2, the second variable. In this situation, the program ends with an error when it tries
to add the two variables. In other situations, the program might not end in error.
To prevent the last variable from getting the remaining values, use a period (.) at the end of the PULL or
ARG instruction.
ARG number1 number2 .
/**************************** REXX ******************************/
/* This program adds two numbers and says their sum */
/****************************************************************/
PULL number1 number2
sum = number1 + number2
SAY ’The sum of the two numbers is’ sum’.’
Figure 8. Variation of an Example that Uses PULL
/**************************** REXX ******************************/
/* This program receives two numbers as input, adds them, and */
/* produces their sum. */
/****************************************************************/
ARG number1 number2
sum = number1 + number2
SAY ’The sum of the two numbers is’ sum’.’
Figure 9. Example of a program That Uses the ARG Instruction
Writing and Running a REXX Program
Chapter 2. Writing and Running a REXX Program 15
The period acts as a dummy variable to collect unwanted extra information. (In this case, number1 receives
42,number2 receives 21, and the period ensures the 10 is discarded. If there is no extra information, the
period is ignored. You can also use a period as a placeholder within the PULL or ARG instruction as
follows:
ARG . number1 number2
In this case, the first value, 42, is discarded and number1 and number2 get the next two values, 21 and 10.
Preventing Translation of Input to Uppercase
Like the PULL instruction, the ARG instruction changes alphabetic characters to uppercase. To prevent
translation to uppercase, use PARSE ARG as in the following example.
Exercises - Using the ARG Instruction
The left column shows the input values sent to a program. The right column is the ARG instruction within
the program that receives the input. What value does each variable receive?
Input Variables Receiving Input
1. 115 -23 66 5.8
ARG first second third
2. .2 0 569 2E6
ARG first second third fourth
3. 13 13 13 13
ARG first second third fourth fifth
4. Weber Joe 91
ARG lastname firstname score
5. Baker Amanda Marie 95
PARSE ARG lastname firstname score
6. Callahan Eunice 88 62
PARSE ARG lastname firstname score .
ANSWERS
1. first = 115, second = -23, third = 66 5.8
2. first = .2, second = 0, third = 569, fourth = 2E6
3. first = 13, second = 13, third = 13, fourth = 13, fifth = null
4. lastname = WEBER, firstname = JOE, score = 91
5. lastname = Baker, firstname = Amanda, score = Marie 95
6. lastname = Callahan, firstname = Eunice, score = 88
Passing Arguments
Values passed to a program are usually called arguments. An argument can consist of one word or a
string of words. Blanks separate words within an argument from each other. The number of arguments
passed depends on how the program is called.
/**************************** REXX ********************************/
/* This program receives the last name, first name, and score of */
/* a student and reports the name and score. */
/******************************************************************/
PARSE ARG lastname firstname score
SAY firstname lastname ’received a score of’ score’.’
Figure 10. Example of a program That Uses PARSE ARG
Writing and Running a REXX Program
16 CICS TS for VSE/ESA: REXX Guide
Using the CALL Instruction or a REXX Function Call
When you call a REXX program using either the CALL instruction or a REXX function call, you can pass
up to 20 arguments to the program. Separate each argument from the next with a comma.
For more information about functions and subroutines, see Chapter 6, “Writing Subroutines and Functions,”
on page 57. For more information about arguments, see section “Parsing Multiple Strings as Arguments”
on page 78.
Writing and Running a REXX Program
Chapter 2. Writing and Running a REXX Program 17
18 CICS TS for VSE/ESA: REXX Guide
Chapter 3. Using Variables and Expressions
This chapter describes variables, expressions, and operators, and explains how to use them in REXX
programs.
Program Variables
One of the most powerful aspects of computer programming is the ability to process variable data to
achieve a result. Regardless of the complexity of a process, when data is unknown or varies, you
substitute a symbol for the data. This is much like substituting xand yin an algebraic equation.
x=y+29
The symbol, when its value can vary, is called a variable. A group of symbols or numbers that must be
calculated to be resolved is called an expression.
Using Variables
A variable is a character or group of characters representing a value. A variable can contain either single-
or double-byte characters or both. (Double-byte characters are valid only if OPTIONS ETMODE is the first
instruction of your program.) The following variable big represents the value one million or 1,000,000.
big = 1000000
Variables can refer to different values at different times. If you assign a different value to big, it gets the
value of the new assignment, until it is changed again.
big = 999999999
Variables can also represent a value that is unknown when the program is written. In the following
example, the user's name is unknown, so it is represented by the variable who.
/* Gets name from current input stream */
PARSE PULL who /* and puts it in variable "who" */
Variable Names
A variable name, the part that represents the value, is always on the left of the assignment statement and
the value itself is on the right. In the following example, the variable name is variable1.
variable1 = 5
SAY variable1
As a result of the preceding assignment statement, the language processor assigns variable1 the value 5,
and the SAY produces:
5
Variable names can consist of:
A–Z uppercase alphabetic
a–z lowercase alphabetic
0–9 numbers
?!._ special characters
X'41'–X'FE'
double-byte character set (DBCS) characters. (OPTIONS ETMODE must be the first instruction in
your program for these characters to be valid in a variable name.)
Restrictions on the variable name are:
© Copyright IBM Corp. 1992, 2010 19
vThe first character cannot be 0 through 9 or a period (.)
vThe variable name cannot exceed 250 bytes. For names containing DBCS characters, count each
DBCS character as 2 bytes, and count the shift-out (SO) and shift-in (SI) as 1 byte each.
vSO (X'0E') and SI (X'0F') must delimit DBCS characters within a DBCS name. Also note that:
– SO and SI cannot be contiguous.
– Nesting of SO / SI is not permitted.
– A DBCS name cannot contain a DBCS blank (X'4040').
vThe variable name should not be RC, SIGL, or RESULT, which are REXX special variables. More about
special variables appears later in this book.
Examples of acceptable variable names are:
ANSWER ?98B A Word3 number the_ultimate_value
Also, if OPTIONS ETMODE is the first instruction in your program, the following are valid DBCS variable
names, where < represents shift-out, > represents shift-in, X,Y, and Zrepresent DBCS characters, and
lowercase letters and numbers represent themselves.
<.X.Y.Z> number_<.X.Y.Z> <.X.Y>1234<.Z>
Variable Values
The value of the variable, which is the value the variable name represents, might be categorized as
follows:
vAconstant, which is a number that is expressed as:
An integer (12)
A decimal (12.5)
A floating point number (1.25E2)
A signed number (-12)
A string constant (' 12')
vAstring, which is one or more words that may or may not be within quotation marks, such as:
This value can be a string.
’This value is a literal string.’
vThe value from another variable, such as:
variable1 = variable2
In the preceding example, variable1 changes to the value of variable2, but variable2 remains the same.
vAn expression, which is something that needs to be calculated, such as:
variable2 = 12 + 12 - .6 /* variable2 becomes 23.4 */
Before a variable is assigned a value, its value is the value of its own name translated to uppercase. For
example, if the variable new has not been assigned a value, then
SAY new
produces
NEW
Exercises - Identifying Valid Variable Names
Which of the following are valid REXX variable names?
1. 8eight
2. £25.00
3. MixedCase
4. nine_to_five
5. result
Using Variables and Expressions
20 CICS TS for VSE/ESA: REXX Guide
ANSWERS
1. Incorrect, because the first character is a number.
2. Incorrect, because the first character is a “£”.
3. Valid
4. Valid
5. Valid, but it is a special variable name that you should use only to receive results from a subroutine.
Using Expressions
An expression is something that needs to be evaluated and consists of numbers, variables, or strings, and
zero or more operators. The operators determine the kind of evaluation to do on the numbers, variables,
and strings. There are four types of operators: arithmetic, comparison, logical, and concatenation.
Arithmetic Operators
Arithmetic operators work on valid numeric constants or on variables that represent valid numeric
constants.
Types of Numeric Constants
12 Awhole number has no decimal point or commas. Results of arithmetic operations with whole
numbers can contain a maximum of nine digits unless you override this default by using the
NUMERIC DIGITS instruction. For information about the NUMERIC DIGITS instruction, see
section section “NUMERIC” on page 150. Examples of whole numbers are:
123456789 0 91221 999
12.5 Adecimal number includes a decimal point. Results of arithmetic operations with decimal
numbers are limited to a total maximum of nine digits (NUMERIC DIGITS default) before and after
the decimal. Examples of decimal numbers are:
123456.789 0.888888888
1.25E2
Afloating point number in exponential notation, is said to be in scientific notation. The number
after the "E" represents the number of places the decimal point moves. Thus 1.25E2 (also written
as 1.25E+2) moves the decimal point to the right two places and results in 125. When an "E" is
followed by a minus (-), the decimal point moves to the left. For example, 1.25E-2 is .0125.
You can use floating point numbers to represent very large or very small numbers. For more
information about scientific notation (floating point numbers), see section “Exponential Notation” on
page 222.
-12 Asigned number with a minus (-) next to the number represents a negative value. A signed
number with a plus (+) next to the number represents a positive value. When a number has no
sign, it is processed as if it has a positive value.
The arithmetic operators you can use are:
Operator
Meaning
+Add
−Subtract
*Multiply
/Divide
%Divide and return a whole number without a remainder
// Divide and return the remainder only
Using Variables and Expressions
Chapter 3. Using Variables and Expressions 21
** Raise a number to a whole number power
−number
(Prefix −) Same as the subtraction 0 - number
+number
(Prefix +) Same as the addition 0 + number
Using numeric constants and arithmetic operators, you can write arithmetic expressions such as:
7 + 2 /* result is 9 */
7 - 2 /* result is 5 */
7 * 2 /* result is 14 */
7 ** 2 /* result is 49 */
7 ** 2.5 /* result is an error */
Division
Notice that three operators represent division. Each operator computes the result of a division expression
in a different way.
/Divide and express the answer possibly as a decimal number. For example:
7 / 2 /* result is 3.5 */
6 / 2 /* result is 3 */
%Divide and express the answer as a whole number. The remainder is ignored. For example:
7 % 2 /* result is 3 */
// Divide and express the answer as the remainder only. For example:
7 // 2 /* result is 1 */
Order of Evaluation
When you have more than one operator in an arithmetic expression, the order of numbers and operators
can be critical. For example, in the following expression, which operation does the language processor
perform first?
7+2*(9/3)-1
Proceeding from left to right, the language processor evaluates the expression as follows:
vFirst it evaluates expressions within parentheses.
vThen it evaluates expressions with operators of higher priority before expressions with operators of
lower priority.
Arithmetic operator priority is as follows, with the highest first:
Table 1. Arithmetic Operator Priority
Operator symbol Operator description
- + Prefix operators
** Power (exponential)
*/%// Multiplication and division
+ - Addition and subtraction
Thus, the preceding example would be evaluated in the following order:
1. Expression in parentheses
7+2*(9/3)-1
\___/
3
2. Multiplication
Using Variables and Expressions
22 CICS TS for VSE/ESA: REXX Guide
7+2*3-1
\___/
6
3. Addition and subtraction from left to right
7+6-1=12
Using Arithmetic Expressions
You can use arithmetic expressions in a program many different ways. The following example uses several
arithmetic operators to round and remove extra decimal places from a dollar and cents value.
Exercises—Calculating Arithmetic Expressions
1. What line of output does the following program produce?
/****************************** REXX ******************************/
pa=1
ma=1
kids = 3
SAY "There are" pa + ma + kids "people in this family."
2. What is the value of:
a. 6-4+1
b. 6-(4+1)
c. 6*4+2
d. 6*(4+2)
e. 24%5/2
ANSWERS
1. There are 5 people in this family.
2. The values are as follows:
a. 3
b. 1
c. 26
d. 36
e. 2
Comparison Operators
Expressions that use comparison operators do not return a number value as do arithmetic expressions.
Comparison expressions return either 1, which represents true, or 0, which represents false.
Comparison operators can compare numbers or strings and perform evaluations, such as:
Are the terms equal? (A=Z)
Is the first term greater than the second? (A>Z)
Is the first term less than the second? (A<Z)
/****************************** REXX *********************************/
/* This program computes the total price of an item including sales */
/* tax, rounded to two decimal places. The cost and percent of the */
/* tax (expressed as a decimal number) are passed to the program */
/* when you run it. */
/*********************************************************************/
PARSE ARG cost percent_tax
total = cost + (cost * percent_tax) /* Add tax to cost. */
price = ((total * 100 + .5) % 1) / 100 /* Round and remove extra */
/* decimal places. */
SAY ’Your total cost is £’price’.’
Figure 11. Example Using Arithmetic Expressions
Using Variables and Expressions
Chapter 3. Using Variables and Expressions 23
For example, if A=4and Z=3, then the results of the previous comparison questions are:
(A=Z) Does4=3? 0(False)
(A>Z) Is4>3? 1(True)
(A<Z) Is4<3? 0(False)
The more commonly used comparison operators are as follows:
Operator
Meaning
=Equal
== Strictly Equal
\= Not equal
\== Not strictly equal
>Greater than
<Less than
>< 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
Note: The NOT character (¬) is synonymous with the backslash (\). You can use the two characters
interchangeably according to availability and personal preference. This book uses the backslash (\)
character.
The Strictly Equal and Equal Operators
When two expressions are strictly equal, everything including the blanks and case (when the expressions
are characters) is exactly the same.
When two expressions are equal, they are resolved to be the same. The following expressions are all
true.
’WORD’ = word /* returns 1 */
’word ’ \== word /* returns 1 */
’word’ == ’word’ /* returns 1 */
4e2 \== 400 /* returns 1 */
4e2 \= 100 /* returns 1 */
Using Comparison Expressions
You often use a comparison expression in an IF...THEN...ELSE instruction. The following example uses an
IF...THEN...ELSE instruction to compare two values. For more information about this instruction, see
section “IF...THEN...ELSE Instructions” on page 33.
Using Variables and Expressions
24 CICS TS for VSE/ESA: REXX Guide
Exercises - Using Comparison Expressions
1. Based on the preceding example of using a comparison expression, what result does the language
processor produce from the following lunch costs?
Yesterday's Lunch
Today's Lunch
4.42 3.75
3.50 3.50
3.75 4.42
2. What is the result (0or 1) of the following expressions?
a. "Apples" = "Oranges"
b. " Apples" = "Apples"
c. " Apples" == "Apples"
d. 100 = 1E2
e. 100 \= 1E2
f. 100 \== 1E2
ANSWERS
1. The language processor produces the following sentences:
a. Today's lunch cost the same or less than yesterday's.
b. Today's lunch cost the same or less than yesterday's.
c. Today's lunch cost more than yesterday's.
2. The expressions result in the following. Remember 0is false and 1is true.
a. 0
b. 1
c. 0(The first " Apples" has a space.)
d. 1
e. 0
f. 1
Logical (Boolean) Operators
Logical expressions, like comparison expressions, return 1(true) or 0(false) when processed. Logical
operators combine two comparisons and return 1or 0depending on the results of the comparisons.
The logical operators are:
/****************************** REXX *********************************/
/* This program compares what you paid for lunch for two */
/* days in a row and then comments on the comparison. */
/*********************************************************************/
PARSE PULL yesterday /* Gets yesterday’s price from input stream */
PARSE PULL today /* Gets today’s price */
IF today > yesterday THEN /* lunch cost increased */
SAY "Today’s lunch cost more than yesterday’s."
ELSE /* lunch cost remained the same or decreased */
SAY "Today’s lunch cost the same or less than yesterday’s."
Figure 12. Example Using a Comparison Expression
Using Variables and Expressions
Chapter 3. Using Variables and Expressions 25
Operator
Meaning
&AND
Returns 1if both comparisons are true. For example:
(4 > 2) & (a = a) /* true, so result is 1 */
(2 > 4) & (a = a) /* false, so result is 0 */
|Inclusive OR
Returns 1if at least one comparison is true. For example:
(4 > 2) | (5 = 3) /* at least one is true, so result is 1 */
(2 > 4) | (5 = 3) /* neither one is true, so result is 0 */
&& Exclusive OR
Returns 1if only one comparison (but not both) is true. For example:
(4 > 2) && (5 = 3) /* only one is true, so result is 1 */
(4 > 2) && (5 = 5) /* both are true, so result is 0 */
(2 > 4) && (5 = 3) /* neither one is true, so result is 0 */
Prefix \,¬
Logical NOT
Negates—returning the opposite response. For example:
\ 0 /* opposite of 0, so result is 1 */
\ (4 > 2) /* opposite of true, so result is 0 */
Using Logical Expressions
You can use logical expressions in complex conditional instructions and as checkpoints to screen
unwanted conditions. When you have a series of logical expressions, for clarification, use one or more
sets of parentheses to enclose each expression.
IF ((A < B) | (J < D)) & ((M = Q) | (M = D)) THEN ....
The following example uses logical operators to make a decision.
When arguments passed to this example are SPRING YES NO, the IF clause translates as follows:
IF ((season = ’WINTER’) | (snowing =’YES’)) & (broken_leg =’NO’) THEN
\______________/ \____________/ \_____________/
false true true
/****************************** REXX ********************************/
/* This program receives arguments for a complex logical expression */
/* that determines whether a person should go skiing. The first */
/* argument is a season and the other two can be ’yes’ or ’no’. */
/********************************************************************/
PARSE ARG season snowing broken_leg
IF ((season = ’WINTER’) | (snowing =’YES’)) & (broken_leg =’NO’)
THEN SAY ’Go skiing.’
ELSE
SAY ’Stay home.’
Figure 13. Example Using Logical Expressions
Using Variables and Expressions
26 CICS TS for VSE/ESA: REXX Guide
\___________________/ /
true /
\_____________________________/
true
As a result, when you run the program, it produces the result:
Go skiing.
Exercises - Using Logical Expressions
A student applying to colleges has decided to evaluate them according to the following specifications:
IF (inexpensive | scholarship) & (reputable | nearby) THEN
SAY "I’ll consider it."
ELSE
SAY "Forget it!"
A college is inexpensive, did not offer a scholarship, is reputable, but is more than 1000 miles away.
Should the student apply?
ANSWER
Yes. The conditional instruction works out as follows:
IF (inexpensive | scholarship) & (reputable | nearby) THEN ...
\__________/ \___________/ \_________/ \______/
true false true false
\___________/ \_________/
true true
\_________________________/
true
Concatenation Operators
Concatenation operators combine two terms into one. The terms can be strings, variables, expressions, or
constants. Concatenation can be significant in formatting output.
The operators that indicate how to join two terms are as follows:
Operator
Meaning
blank Concatenates terms and places one blank between them. If more than one blank separates terms,
this becomes a single blank. For example:
SAY true blue /* result is TRUE BLUE */
|| Concatenates terms with no blanks between them. For example:
(8 / 2)||(3 * 3) /* result is 49 */
abuttal
Concatenates terms with no blanks between them. For example:
per_cent’%’ /* if per_cent = 50, result
is 50% */
You can use abuttal only with terms that are of different types, such as a literal string and a
symbol, or when only a comment separates two terms.
Using Concatenation Operators
One way to format output is to use variables and concatenation operators as in the following example.
Using Variables and Expressions
Chapter 3. Using Variables and Expressions 27
The result of this example is:
baseball £ 5
A more sophisticated way to format information is with parsing and templates. Information about parsing
appears in section “Parsing Data” on page 73.
Priority of Operators
When more than one type of operator appears in an expression, what operation does the language
processor do first?
IF (A > 7**B) & (B < 3)
Like the priority of operators for the arithmetic operators, there is an overall priority that includes all
operators. The priority of operators is as follows with the highest first.
Table 2. Overall Operator Priority
Operator symbol Operator description
\or¬- + Prefix operators
** Power (exponential)
*/%// Multiply and divide
+ - Add and subtract
blank || abuttal Concatenation operators
== = >< and so on Comparison operators
& Logical AND
| && Inclusive OR and exclusive OR
Thus, given the following values
A=8
B=2
C=10
the language processor would evaluate the previous example
IF (A > 7**B) & (B < 3)
as follows:
1. Evaluate what is inside the first set of parentheses.
a. Evaluate A to 8.
b. Evaluate B to 2.
c. Evaluate 7**2.
d. Evaluate8>49isfalse (0).
2. Evaluate what is inside the next set of parentheses.
a. Evaluate B to 2.
/****************************** REXX *********************************/
/* This program formats data into columns for output. */
/*********************************************************************/
sport = ’base’
equipment = ’ball’
column = ’ ’
cost = 5
SAY sport||equipment column ’£’ cost
Figure 14. Example Using Concatenation Operators
Using Variables and Expressions
28 CICS TS for VSE/ESA: REXX Guide
b. Evaluate2<3istrue (1).
3. Evaluate 0&1is 0
Exercises - Priority of Operators
1. What are the answers to the following examples?
a. 22 + (12 * 1)
b. -6/-2>(45%7/2)-1
c. 10*2-(5+1)//5*2+15-1
2. In the example of the student and the college from the previous exercise on page “Exercises - Using
Logical Expressions” on page 27, if the parentheses were removed from the student's formula, what
would be the outcome for the college?
IF inexpensive | scholarship & reputable | nearby THEN
SAY "I’ll consider it."
ELSE
SAY "Forget it!"
Remember the college is inexpensive, did not offer a scholarship, is reputable, but is 1000 miles away.
ANSWERS
1. The results are as follows:
a. 34 (22 + 12 = 34)
b. 1 (true) (3>3-1)
c. 32(20-2+15-1)
2. I'll consider it.
The &operator has priority, as follows, but the outcome is the same as the previous version with the
parentheses.
IF inexpensive | scholarship & reputable | nearby THEN
\_________/ \_________/ \_______/ \____/
true false true false
\ \___________/ /
\ false /
\_________________/ /
true /
\____________________/
true
Tracing Expressions with the TRACE Instruction
You can use the TRACE instruction to show how the language processor evaluates each operation of an
expression as it reads it, or to show the final result of an expression. These two types of tracing are useful
for debugging programs.
Tracing Operations
To trace operations within an expression, use the TRACE I (TRACE Intermediates) form of the TRACE
instruction. The language processor breaks down all expressions that follow the instruction and analyzes
them as:
>V> - Variable value - The data traced is the contents
of a variable.
>L> - Literal value - The data traced is a literal
(string, uninitialized variable, or constant).
>O> - Operation result - The data traced is the result
of an operation on two terms.
The following example uses the TRACE I instruction. (The line numbers are not part of the program. They
facilitate the discussion of the example that follows it.)
Using Variables and Expressions
Chapter 3. Using Variables and Expressions 29
When you run the example, the SAY instruction produces:
9*-*IFa+1>5*y
>V> "9"
>L> "1"
>O> "10"
>L> "5"
>V> "2"
>O> "10"
>O> "0"
The 9is the line number. The *-* indicates that what follows is the data from the program,
IFa+1<5*y. The remaining lines break down all the expressions.
Tracing Results
To trace only the final result of an expression, use the TRACE R (TRACE Results) form of the TRACE
instruction. The language processor analyzes all expressions that follow the instruction as follows:
>>> Final result of an expression
If you changed the TRACE instruction operand in the previous example from an I to an R, you would see
the following results.
9*-*IFa+1>5*y
>>> "0"
In addition to tracing operations and results, the TRACE instruction offers other types of tracing, see
section “TRACE” on page 166.
Exercises - Using the TRACE Instruction
Write a program with a complex expression, such as:
IF(a>z)|(c<2*d)THEN ....
Define a,z,c, and din the program and use the TRACE I instruction.
ANSWER
1 /************************* REXX ***************************/
2 /* This program uses the TRACE instruction to show how */
3 /* an expression is evaluated, operation by operation. */
4 /**********************************************************/
5 a=9
6 y=2
7 TRACE I
8
9 IFa+1>5*yTHEN
10 SAY ’a is big enough.’
11 ELSE NOP /* No operation on the ELSE path */
Figure 15. TRACE Shows How REXX Evaluates an Expression
Using Variables and Expressions
30 CICS TS for VSE/ESA: REXX Guide
When you run this program, it produces:
12*-*IF(a>z)|(c<2*d)
>V> "1"
>V> "2"
>O> "0"
>V> "3"
>L> "2"
>V> "4"
>O> "8"
>O> "1"
>O> "1"
*-* THEN
13 *-* SAY ’At least one expression was true.’
>L> "At least one expression was true."
At least one expression was true.
/****************************** REXX ********************************/
/* This program uses the TRACE instruction to show how the language */
/* processor evaluates an expression, operation by operation. */
/********************************************************************/
a=1
z=2
c=3
d=4
TRACE I
IF(a>z)|(c<2*d)THEN
SAY ’At least one expression was true.’
ELSE
SAY ’Neither expression was true.’
Figure 16. Possible Solution
Using Variables and Expressions
Chapter 3. Using Variables and Expressions 31
Using Variables and Expressions
32 CICS TS for VSE/ESA: REXX Guide
Chapter 4. Controlling the Flow within a program
This chapter introduces instructions that alter the sequential execution of a program and demonstrates
how to use those instructions.
Conditional, Looping, and Interrupt Instructions
Generally, when a program runs, one instruction after another executes, starting with the first and ending
with the last. The language processor, unless told otherwise, executes instructions sequentially.
You can change the order of execution within a program by using REXX instructions that cause the
language processor to skip some instructions, repeat others, or transfer control to another part of the
program. These REXX instructions can be classified as follows:
vConditional instructions set up at least one condition in the form of an expression. If the condition is
true, the language processor selects the path following that condition. Otherwise the language
processor selects another path. The REXX conditional instructions are:
IF expression THEN...ELSE
SELECT WHEN expression...OTHERWISE...END
vLooping instructions tell the language processor to repeat a set of instructions. A loop can repeat a
specified number of times or it can use a condition to control repeating. REXX looping instructions are:
DO repetitor...END
DO WHILE expression...END
DO UNTIL expression...END
vInterrupt instructions tell the language processor to leave the program entirely or leave one part of the
program and go to another part, either permanently or temporarily. The REXX interrupt instructions are:
EXIT
SIGNAL label
CALL label...RETURN
Using Conditional Instructions
There are two types of conditional instructions:
vIF...THEN...ELSE can direct the execution of a program to one of two choices.
vSELECT WHEN...OTHERWISE...END can direct the execution to one of many choices.
IF...THEN...ELSE Instructions
The examples of IF...THEN...ELSE instructions in previous chapters demonstrate the two-choice selection.
In a flow chart, this appears as follows:
expression
instruction instruction
Tr u eFalse
ELSE THEN
© Copyright IBM Corp. 1992, 2010 33
As a REXX instruction, the flowchart example looks like:
IF expression THEN instruction
ELSE instruction
You can also arrange the clauses in one of the following ways to enhance readability:
IF expression THEN
instruction
ELSE
instruction
or
IF expression
THEN
instruction
ELSE
instruction
When you put the entire instruction on one line, you must use a semicolon before the ELSE to separate
the THEN clause from the ELSE clause.
IF expression THEN instruction; ELSE instruction
Generally, at least one instruction should follow the THEN and ELSE clauses. When either clause has no
instructions, it is good programming practice to include NOP (no operation) next to the clause.
IF expression THEN
instruction
ELSE NOP
If you have more than one instruction for a condition, begin the set of instructions with a DO and end them
with an END.
IF weather = rainy THEN
SAY ’Find a good book.’
ELSE
DOPULL playgolf /* Gets data from input stream */
If playgolf=’YES’ THEN SAY ’Fore!’
END
Without the enclosing DO and END, the language processor assumes only one instruction for the ELSE
clause.
Nested IF...THEN...ELSE Instructions
Sometimes it is necessary to have one or more IF...THEN...ELSE instructions within other
IF...THEN...ELSE instructions. Having one type of instruction within another is called nesting. With nested
IF instructions, it is important to match each IF with an ELSE and each DO with an END.
IF weather = fine THEN
DO SAY ’What a lovely day!’
IF tenniscourt = free THEN
SAY ’Let’’s play tennis!’
ELSE NOP
END
ELSE
SAY ’We should take our raincoats!’
Not matching nested IFs to ELSEs and DOs to ENDs can have some surprising results. If you eliminate
the DOs and ENDs and the ELSE NOP, as in the following example, what is the outcome?
Control Flow within a Program
34 CICS TS for VSE/ESA: REXX Guide
Looking at the program you might assume the ELSE belongs to the first IF. However, the language
processor associates an ELSE with the nearest unpaired IF. The outcome is as follows:
What a lovely day!
We should take our raincoats!
/******************************** REXX *******************************/
/* This program demonstrates what can happen when you do not include */
/* DOs, ENDs, and ELSEs in nested IF...THEN...ELSE instructions. */
/*********************************************************************/
weather = ’fine’
tenniscourt = ’occupied’
IF weather = ’fine’ THEN
SAY ’What a lovely day!’
IF tenniscourt = ’free’ THEN
SAY ’Let’’s play tennis!’
ELSE
SAY ’We should take our raincoats!’
Figure 17. Example of Missing Instructions
Control Flow within a Program
Chapter 4. Controlling the Flow within a program 35
Exercise - Using the IF...THEN...ELSE Instruction
Write the REXX instructions for the following flowchart:
ANSWER
IFa=0THEN
IFc=2THEN
z=1
ELSE NOP
ELSE
IFz=2THEN
IFc=3THEN
a=1
ELSE
a=3
ELSE NOP
A=0
A=3 A=1
Z=1
Z=2
C=3
C=2
Tr u eFalse
Tr u eFalse
Tr u eFalse
Tr u eFalse
Control Flow within a Program
36 CICS TS for VSE/ESA: REXX Guide
SELECT WHEN...OTHERWISE...END Instruction
To select one of any number of choices, use the SELECT WHEN...OTHERWISE...END instruction. In a
flowchart it appears as follows:
False
False
THEN
WHEN
WHEN
WHEN
OTHERWISE
END
Tr u e
instruction
THEN
Tr u e
instruction
THEN
Tr u e
instruction
instruction(s)
SELECT
expression
expression
expression
As a REXX instruction, the flowchart example looks like:
SELECT
WHEN expression THEN instruction
WHEN expression THEN instruction
WHEN expression THEN instruction
:
:
OTHERWISE
instruction(s)
END
The language processor scans the WHEN clauses starting at the beginning until it finds a true expression.
After it finds a true expression, it ignores all other possibilities, even though they might also be true. If no
WHEN expressions are true, it processes the instructions following the OTHERWISE clause.
As with IF...THEN...ELSE, when you have more than one instruction for a possible path, begin the set of
instructions with a DO and end them with an END. However, if more than one instruction follows the
OTHERWISE keyword, DO and END are not necessary.
Control Flow within a Program
Chapter 4. Controlling the Flow within a program 37
Each SELECT must end with an END. Indenting each WHEN makes a program easier to read.
Exercises - Using SELECT WHEN...OTHERWISE...END
"Thirty days hath September, April, June, and November; all the rest have thirty-one, save February alone
..."
Write a program that uses the input of a number from 1 to 12, representing the month, and produces the
number of days in that month. Assume the user specifies the month number as an argument when calling
the program. (Include in the program an ARG instruction to assign the month number into the variable
month). Then have the program produce the number of days. For month 2, this can be 28 or 29.
ANSWER
/******************************** REXX *******************************/
/* This program receives input with a person’s age and sex. In */
/* reply, it produces a person’s status as follows: */
/* BABIES - under 5 */
/* GIRLS - female 5 to 12 */
/* BOYS - male 5 to 12 */
/* TEENAGERS - 13 through 19 */
/* WOMEN - female 20 and up */
/* MEN - male 20 and up */
/*********************************************************************/
PARSE ARG age sex .
SELECT
WHEN age < 5 THEN /* person younger than 5 */
status = ’BABY’
WHEN age < 13 THEN /* person between 5 and 12 */
DOIF sex = ’M’ THEN /* boy between 5 and 12 */
status = ’BOY’
ELSE /* girl between 5 and 12 */
status = ’GIRL’
END
WHEN age < 20 THEN /* person between 13 and 19 */
status = ’TEENAGER’
OTHERWISE
IF sex = ’M’ THEN /* man 20 or older */
status = ’MAN’
ELSE /* woman 20 or older */
status = ’WOMAN’
END
SAY ’This person should be counted as a’ status’.’
Figure 18. Example Using SELECT WHEN...OTHERWISE...END
Control Flow within a Program
38 CICS TS for VSE/ESA: REXX Guide
Using Looping Instructions
There are two types of looping instructions, repetitive loops and conditional loops. Repetitive loops let
you repeat instructions a certain number of times. Conditional loops use a condition to control repeating.
All loops, regardless of the type, begin with the DO keyword and end with the END keyword.
Repetitive Loops
The simplest loop tells the language processor to repeat a group of instructions a specific number of
times. It uses a constant after the keyword DO.
DO 5
SAY ’Hello!’
END
When you run this example, it produces five lines of Hello!:
Hello!
Hello!
Hello!
Hello!
Hello!
You can also use a variable in place of a constant, as in the following example, which gives you the same
results.
number = 5
DO number
SAY ’Hello!’
END
A variable that controls the number of times a loop repeats is called a control variable. Unless you
specify otherwise, the control variable increases by 1 each time the loop repeats.
/******************************** REXX *******************************/
/* This program uses the input of a whole number from 1 to 12 that */
/* represents a month. It produces the number of days in that */
/* month. */
/*********************************************************************/
ARG month
SELECT
WHEN month = 9 THEN
days = 30
WHEN month = 4 THEN
days = 30
WHEN month = 6 THEN
days = 30
WHEN month = 11 THEN
days = 30
WHEN month = 2 THEN
days = ’28 or 29’
OTHERWISE
days = 31
END
SAY ’There are’ days ’days in Month’ month’.’
Figure 19. Possible Solution
Control Flow within a Program
Chapter 4. Controlling the Flow within a program 39
DO number=1TO5
SAY ’Loop’ number
SAY ’Hello!’
END
SAY ’Dropped out of the loop when number reached’ number
This example results in five lines of Hello! preceded by the number of the loop. The number increases at
the bottom of the loop and is tested at the top.
Loop 1
Hello!
Loop 2
Hello!
Loop 3
Hello!
Loop 4
Hello!
Loop 5
Hello!
Dropped out of the loop when number reached 6
You can change the increment of the control variable with the keyword BY as follows:
DO number=1TO10BY2
SAY ’Loop’ number
SAY ’Hello!’
END
SAY ’Dropped out of the loop when number reached’ number
This example has results similar to the previous example except the loops are numbered in increments of
two.
Loop 1
Hello!
Loop 3
Hello!
Loop 5
Hello!
Loop 7
Hello!
Loop 9
Hello!
Dropped out of the loop when number reached 11
Infinite Loops
What happens when the control variable of a loop cannot attain the last number? For example, in the
following program segment, count does not increase beyond 1.
DO count=1to10
SAY ’Number’ count
count = count - 1
END
The result is called an infinite loop because count alternates between 1 and 0, producing an endless
number of lines saying Number 1.
If your program is in an infinite loop, contact the operator to cancel it. An authorized user can issue the
CEMT SET TASK PURGE command to halt an exec.
DO FOREVER Loops
Sometimes you might want to write an infinite loop purposely; for instance, in a program that reads records
from a file until it reaches the end of the file. You can use the EXIT instruction to end an infinite loop when
a condition is met, as in the following example. More about the EXIT instruction appears in section “EXIT
Instruction” on page 48.
Control Flow within a Program
40 CICS TS for VSE/ESA: REXX Guide
This example sends strings to a user-written function for processing and then issues a message that the
processing completed successfully or failed. When the input string is a blank, the loop ends and so does
the program. You can also end the loop without ending the program by using the LEAVE instruction. The
following topic describes this.
LEAVE Instruction
The LEAVE instruction causes an immediate exit from a repetitive loop. Control goes to the instruction
following the END keyword of the loop. An example of using the LEAVE instruction follows:
ITERATE Instruction
The ITERATE instruction stops execution from within the loop and passes control to the DO instruction at
the top of the loop. Depending on the type of DO instruction, the language processor increases and tests
a control variable or tests a condition to determine whether to repeat the loop. Like LEAVE, ITERATE is
used within the loop.
DO count=1TO10
IF count = 8
THEN
ITERATE
ELSE
SAY ’Number’ count
END
This example results in a list of numbers from 1 to 10 with the exception of number 8.
/******************************* REXX ********************************/
/* This program processes strings until the value of a string is */
/* a null string. */
/*********************************************************************/
DO FOREVER
PULL string /* Gets string from input stream */
IF string = ’’ THEN
PULL file_name
IF file_name = ’’ THEN
EXIT
ELSE
DO
result = process(string) /* Calls a user-written function */
/* to do processing on string. */
IF result = 0 THEN SAY "Processing complete for string:" string
ELSE SAY "Processing failed for string:" string
END
END
Figure 20. Example Using a DO FOREVER Loop
/******************************** REXX *******************************/
/* This program uses the LEAVE instruction to exit from a DO */
/* FOREVER loop. */
/*********************************************************************/
DO FOREVER
PULL string /* Gets string from input stream */
IF string = ’QUIT’ then
LEAVE
ELSE
DO
result = process(string) /* Calls a user-written function */
/* to do processing on string. */
IF result = 0 THEN SAY "Processing complete for string:" string
ELSE SAY "Processing failed for string:" string
END
END
SAY ’Program run complete.’
Figure 21. Example Using the LEAVE Instruction
Control Flow within a Program
Chapter 4. Controlling the Flow within a program 41
Number 1
Number 2
Number 3
Number 4
Number 5
Number 6
Number 7
Number 9
Number 10
Exercises - Using Loops
1. What are the results of the following loops?
a. DO digit=1TO3
SAY digit
END
SAY ’Digit is now’ digit
b. DO count = 10 BY -2 TO 6
SAY count
END
SAY ’Count is now’ count
c. DO index = 10 TO 8
SAY ’Hup! Hup! Hup!’
END
SAY ’Index is now’ index
2. Sometimes an infinite loop can occur when input to end the loop does not match what is expected. For
instance, in the example of using the LEAVE Instruction on page 41, what happens when the input is
Quit and a PARSE PULL instruction replaces the PULL instruction?
PARSE PULL file_name
ANSWERS
1. The results of the repetitive loops are as follows:
a. 1
2
3
Digit is now 4
b. 10
8
6
Count is now 4
c. Index is now 10
2. The program would be unable to leave the loop because Quit is not equal to QUIT. In this case,
omitting the PARSE keyword is preferred because regardless of whether the input is quit,QUIT,or
Quit, the language processor translates the input to uppercase before comparing it to QUIT.
Conditional Loops
There are two types of conditional loops, DO WHILE and DO UNTIL. One or more expressions control
both types of loops. However, DO WHILE loops test the expression before the loop executes the first time
and repeat only when the expression is true. DO UNTIL loops test the expression after the loop executes
at least once and repeat only when the expression is false.
Control Flow within a Program
42 CICS TS for VSE/ESA: REXX Guide
DO WHILE Loops
DO WHILE loops in a flowchart appear as follows:
DO WHILE
Tr u e
instruction(s)
expression
False
END
As REXX instructions, the flowchart example looks like:
DO WHILE expression /* expression must be true */
instruction(s)
END
Use a DO WHILE loop when you want to execute the loop while a condition is true. DO WHILE tests the
condition at the top of the loop. If the condition is initially false, the language processor never executes the
loop.
You can use a DO WHILE loop instead of the DO FOREVER loop in the example of using the LEAVE
instruction on page 41. However, you need to initialize the loop with a first case so the condition can be
tested before you get into the loop. Notice the first case initialization in the first PULL of the following
example.
Exercise - Using a DO WHILE Loop
Write a program with a DO WHILE loop that uses as input a list of responses about whether passengers
on a commuter airline want a window seat. The flight has 8 passengers and 4 window seats. Discontinue
the loop when all the window seats are taken. After the loop ends, produce the number of window seats
taken and the number of responses processed.
ANSWER
/******************************** REXX *******************************/
/* This program uses a DO WHILE loop to send a string to a */
/* user-written function for processing. */
/*********************************************************************/
PULL string /* Gets string from input stream */
DO WHILE string \= ’QUIT’
result = process(string) /* Calls a user-written function */
/* to do processing on string. */
IF result = 0 THEN SAY "Processing complete for string:" string
ELSE SAY "Processing failed for string:" string
PULL string
END
SAY ’Program run complete.’
Figure 22. Example Using DO WHILE
Control Flow within a Program
Chapter 4. Controlling the Flow within a program 43
DO UNTIL Loops
DO UNTIL loops in a flowchart appear as follows:
False
DO UNTIL
Tr u e
instruction(s)
expression
END
As REXX instructions, the flowchart example looks like:
DO UNTIL expression /* expression must be false */
instruction(s)
END
Use DO UNTIL loops when a condition is not true and you want to execute the loop until the condition is
true. The DO UNTIL loop tests the condition at the end of the loop and repeats only when the condition is
false. Otherwise, the loop executes once and ends. For example:
/******************************** REXX *******************************/
/* This program uses a DO WHILE loop to keep track of window seats */
/* in an 8-seat commuter airline. */
/*********************************************************************/
window_seats = 0 /* Initialize window seats to 0 */
passenger = 0 /* Initialize passengers to 0 */
DO WHILE (passenger < 8) & (window_seats \= 4)
/******************************************************************/
/* Continue while the program has not yet read the responses of */
/* all 8 passengers and while all the window seats are not taken. */
/******************************************************************/
PULL window /* Gets "Y" or "N" from input stream */
passenger = passenger + 1 /* Increase number of passengers by 1 */
IF window = ’Y’ THEN
window_seats = window_seats+1/*Increase window seats by 1 */
ELSE NOP
END
SAY window_seats ’window seats were assigned.’
SAY passenger ’passengers were questioned.’
Figure 23. Possible Solution
Control Flow within a Program
44 CICS TS for VSE/ESA: REXX Guide
Exercise - Using a DO UNTIL Loop
Change the program in the previous exercise on page “Exercise - Using a DO WHILE Loop” on page 43
from a DO WHILE to a DO UNTIL loop and achieve the same results. Remember that DO WHILE loops
check for true expressions and DO UNTIL loops check for false expressions, which means their logical
operators are often reversed.
/******************************** REXX ******************************/
/* This program uses a DO UNTIL loop to ask for a password. If the */
/* password is incorrect three times, the loop ends. */
/********************************************************************/
password = ’abracadabra’
time = 0
DO UNTIL (answer = password) | (time = 3)
PULL answer /* Gets ANSWER from input stream */
time = time + 1
END
Figure 24. Example Using DO UNTIL
Control Flow within a Program
Chapter 4. Controlling the Flow within a program 45
ANSWER
Combining Types of Loops
You can combine repetitive and conditional loops to create a compound loop. The following loop is set to
repeat 10 times while the quantity is less than 50, at which point it stops.
quantity = 20
DO number=1TO10WHILE quantity < 50
quantity = quantity + number
SAY ’Quantity = ’quantity ’ (Loop ’number’)’
END
The result of this example is as follows:
Quantity = 21 (Loop 1)
Quantity = 23 (Loop 2)
Quantity = 26 (Loop 3)
Quantity = 30 (Loop 4)
Quantity = 35 (Loop 5)
Quantity = 41 (Loop 6)
Quantity = 48 (Loop 7)
Quantity = 56 (Loop 8)
You can substitute a DO UNTIL loop, change the comparison operator from <to >, and get the same
results.
quantity = 20
DO number=1TO10UNTIL quantity > 50
quantity = quantity + number
SAY ’Quantity = ’quantity ’ (Loop ’number’)’
END
Nested DO Loops
Like nested IF...THEN...ELSE instructions, DO loops can contain other DO loops. A simple example
follows:
/******************************** REXX *******************************/
/* This program uses a DO UNTIL loop to keep track of window seats */
/* in an 8-seat commuter airline. */
/*********************************************************************/
window_seats = 0 /* Initialize window seats to 0 */
passenger = 0 /* Initialize passengers to 0 */
DO UNTIL (passenger >= 8) | (window_seats = 4)
/******************************************************************/
/* Continue while the program has not yet read the responses of */
/* all 8 passengers and while all the window seats are not taken. */
/******************************************************************/
PULL window /* Gets "Y" or "N" from input stream */
passenger = passenger + 1 /* Increase number of passengers by 1 */
IF window = ’Y’ THEN
window_seats = window_seats+1/*Increase window seats by 1 */
ELSE NOP
END
SAY window_seats ’window seats were assigned.’
SAY passenger ’passengers were questioned.’
Figure 25. Possible Solution
Control Flow within a Program
46 CICS TS for VSE/ESA: REXX Guide
DO outer=1TO2
DO inner=1TO2
SAY ’HIP’
END
SAY ’HURRAH’
END
The output from this example is:
HIP
HIP
HURRAH
HIP
HIP
HURRAH
If you need to leave a loop when a certain condition arises, use the LEAVE instruction followed by the
name of the control variable of the loop. If the LEAVE instruction is for the inner loop, processing leaves
the inner loop and goes to the outer loop. If the LEAVE instruction is for the outer loop, processing leaves
both loops.
To leave the inner loop in the preceding example, add an IF...THEN...ELSE instruction that includes a
LEAVE instruction after the IF instruction.
DO outer=1TO2
DO inner=1TO2
IF inner > 1 THEN
LEAVE inner
ELSE
SAY ’HIP’
END
SAY ’HURRAH’
END
The result is as follows:
HIP
HURRAH
HIP
HURRAH
Exercises - Combining Loops
1. What happens when the following program runs?
DO outer=1TO3
SAY /* Produces a blank line */
DO inner=1TO3
SAY ’Outer’ outer ’Inner’ inner
END
END
2. Now what happens when the LEAVE instruction is added?
DO outer=1TO3
SAY /* Produces a blank line */
DO inner=1TO3
IF inner = 2 THEN
LEAVE inner
ELSE
SAY ’Outer’ outer ’Inner’ inner
END
END
ANSWERS
1. When this example runs, it produces the following:
Control Flow within a Program
Chapter 4. Controlling the Flow within a program 47
Outer 1 Inner 1
Outer 1 Inner 2
Outer 1 Inner 3
Outer 2 Inner 1
Outer 2 Inner 2
Outer 2 Inner 3
Outer 3 Inner 1
Outer 3 Inner 2
Outer 3 Inner 3
2. The result is one line of output for each of the inner loops.
Outer 1 Inner 1
Outer 2 Inner 1
Outer 3 Inner 1
Using Interrupt Instructions
Instructions that interrupt the flow of a program can cause the program to:
vEnd (EXIT)
vSkip to another part of the program marked by a label (SIGNAL)
vGo temporarily to a subroutine either within the program or outside the program (CALL or RETURN).
EXIT Instruction
The EXIT instruction causes a REXX program to unconditionally end and return to where the program was
called. If another program called the REXX program, EXIT returns to that calling program. More about
calling external routines appears later in this chapter and in Chapter 6, “Writing Subroutines and
Functions,” on page 57. For more detailed information on the EXIT instruction, see section “EXIT” on page
143.
Besides ending a program, EXIT can also return a value to the caller of the program. If the program was
called as a subroutine from another REXX program, the value is received in the REXX special variable
RESULT. If the program was called as a function, the value is received in the original expression at the
point where the function was called. Otherwise, the value is received in the REXX special variable RC.
The value can represent a return code and can be in the form of a constant or an expression that is
computed.
/******************************** REXX ****************************/
/* This program uses the EXIT instruction to end the program and */
/* return a value indicating whether a job applicant gets the */
/* job. A value of 0 means the applicant does not qualify for */
/* the job, but a value of 1 means the applicant gets the job. */
/* The value is placed in the REXX special variable RESULT. */
/******************************************************************/
PULL months_experience /* Gets number from input stream */
PULL references /* Gets "Y" or "N" from input stream */
PULL start_tomorrow /* Gets "Y" or "N" from input stream */
IF (months_experience > 24) & (references = ’Y’) & (start_tomorrow= ’Y’)
THEN job = 1 /* person gets the job */
ELSE job = 0 /* person does not get the job */
EXIT job
Figure 26. Example Using the EXIT Instruction
Control Flow within a Program
48 CICS TS for VSE/ESA: REXX Guide
CALL and RETURN Instructions
The CALL instruction interrupts the flow of a program by passing control to an internal or external
subroutine. An internal subroutine is part of the calling program. An external subroutine is another
program. The RETURN instruction returns control from a subroutine back to the calling program and
optionally returns a value. For more detailed information on the CALL and RETURN instructions, see
sections “CALL” on page 135 and “RETURN” on page 161.
When calling an internal subroutine, CALL passes control to a label specified after the CALL keyword.
When the subroutine ends with the RETURN instruction, the instructions following CALL are processed.
instruction(s)
EXIT
sub1:
instruction(s)
RETURN
instruction(s)
CALL sub1
When calling an external subroutine, CALL passes control to the program name that is specified after the
CALL keyword. When the external subroutine completes, you can use the RETURN instruction to return to
where you left off in the calling program.
instruction(s)
…
…
...
sub2:
instruction(s)
RETURN
instruction(s)
CALL sub2
MAIN
For more information about calling subroutines, see Chapter 6, “Writing Subroutines and Functions,” on
page 57.
Control Flow within a Program
Chapter 4. Controlling the Flow within a program 49
SIGNAL Instruction
The SIGNAL instruction, like CALL, interrupts the usual flow of a program and causes control to pass to a
specified label. The label to which control passes can be before or after the SIGNAL instruction. Unlike
CALL, SIGNAL does not return to a specific instruction to resume execution. When you use SIGNAL from
within a loop, the loop automatically ends. When you use SIGNAL from an internal routine, the internal
routine does not return to its caller. For more detailed information on the SIGNAL instruction, see section
“SIGNAL” on page 164.
In the following example, if the expression is true, then the language processor goes to the label
Emergency: and skips all instructions in between.
Emergency:
instruction(s)
IF expression THEN
SIGNAL Emergency
ELSE
instruction(s)
SIGNAL is useful for testing programs or providing an emergency course of action. It should not be used
as a convenient way to move from one place in a program to another. SIGNAL does not provide a way to
return as does the CALL instruction described in the previous topic.
For more information about the SIGNAL instruction, see page 86 and section “SIGNAL” on page 164.
Control Flow within a Program
50 CICS TS for VSE/ESA: REXX Guide
Chapter 5. Using Functions
This chapter defines what a function is and describes how to use the built-in functions.
What is a Function?
Afunction is a sequence of instructions that can receive data, process it, and return a value. In REXX,
there are several kinds of functions:
vBuilt-in functions are built into the language processor. More about built-in functions appears later in this
chapter.
vUser-written functions are those an individual user writes or an installation supplies. These can be
internal or external. An internal function is part of the current program that starts at a label. An
external function is a self-contained program or program outside the calling program. More information
about user-written functions appears in section “Writing Subroutines and Functions” on page 58.
Regardless of the kind of function, all functions return a value to the program that issued the function call.
To call a function, type the function name immediately followed by parentheses enclosing arguments to the
function (if any). There can be no space between the function name and the left parenthesis.
function(arguments)
A function call can contain up to 20 arguments separated by commas. Arguments can be:
vConstant
function(55)
vSymbol
function(symbol_name)
vOption that the function recognizes
function(option)
vLiteral string
function(’With a literal string’)
vUnspecified or omitted
function()
vAnother function
function(function(arguments))
vCombination of argument types
function(’With literal string’, 55, option)
function(’With literal string’,, option) /* Second argument omitted */
All functions must return values. When the function returns a value, the value replaces the function call. In
the following example, the language processor adds the value the function returns to 7 and produces the
sum.
SAY 7 + function(arguments)
A function call generally appears in an expression. Therefore a function call, like an expression, does not
usually appear in an instruction by itself.
Example of a Function
Calculations that functions represent often require many instructions. For instance, the simple calculation
for finding the highest number in a group of three numbers, might be written as follows:
© Copyright IBM Corp. 1992, 2010 51
Rather than writing multiple instructions every time you want to find the maximum of a group of three
numbers, you can use a built-in function that does the calculation for you and returns the maximum
number. The function is called MAX, and you can use it as follows:
MAX(number1,number2,number3,....)
To find the maximum of 45, -2, number, and 199 and put the maximum into the symbol biggest, write the
following instruction:
biggest = MAX(45,-2,number,199)
Built-In Functions
More than 50 functions are built into the language processor. The built-in functions fall into the following
categories:
vArithmetic functions
Evaluate numbers from the argument and return a particular value.
vComparison functions
Compare numbers, or strings, or both and return a value.
vConversion functions
Convert one type of data representation to another type of data representation.
vFormatting functions
Manipulate the characters and spacing in strings supplied in the argument.
vString manipulating functions
Analyze a string supplied in the argument (or a variable representing a string) and return a particular
value.
vMiscellaneous functions
Do not clearly fit into any of the other categories.
The following tables briefly describe the functions in each category. For a complete description of these
functions, see Chapter 14, “Functions,” on page 171.
/***************************** REXX **********************************/
/* This program receives three numbers as arguments and analyzes */
/* which number is the greatest. */
/*********************************************************************/
PARSE ARG number1, number2, number3 .
IF number1 > number2 THEN
IF number1 > number3 THEN
greatest = number1
ELSE
greatest = number3
ELSE
IF number2 > number3 THEN
greatest = number2
ELSE
greatest = number3
RETURN greatest
Figure 27. Finding a Maximum Number
Using Functions
52 CICS TS for VSE/ESA: REXX Guide
Arithmetic Functions
Function Description
ABS Returns the absolute value of the input number.
DIGITS Returns the current setting of NUMERIC DIGITS.
FORM Returns the current setting of NUMERIC FORM.
FUZZ Returns the current setting of NUMERIC FUZZ.
MAX Returns the largest number from the list specified, formatted according to the current NUMERIC
settings.
MIN Returns the smallest number from the list specified, formatted according to the current
NUMERIC settings.
RANDOM Returns a quasi-random, non-negative whole number in the range specified.
SIGN Returns a number that indicates the sign of the input number.
TRUNC Returns the integer part of the input number and optionally a specified number of decimal
places.
Comparison Functions
Function Description
COMPARE Returns 0if the two input strings are identical. Otherwise, returns the position of the first
character that does not match.
DATATYPE Returns a string indicating the input string is a particular data type, such as a number or
character.
SYMBOL Returns VAR,LIT,orBAD to indicate the state of the symbol (variable, literal, or bad).
Conversion Functions
Function Description
B2X Returns the hexadecimal representation of the input binary string. (Binary to Hexadecimal).
C2D Returns the decimal representation of the input character string. (Character to Decimal).
C2X Returns the hexadecimal representation of the input character string. (Character to
Hexadecimal).
D2C Returns the character representation of the input decimal string. (Decimal to Character).
D2X Returns the hexadecimal representation of the input decimal string. (Decimal to Hexadecimal).
X2B Returns the binary representation of the input hexadecimal string. (Hexadecimal to Binary).
X2C Returns the character representation of the input hexadecimal string. (Hexadecimal to
Character).
X2D Returns the decimal representation of the input hexadecimal string. (Hexadecimal to Decimal).
Formatting Functions
Is a non-SAA built-in function REXX/CICS provides.
Function Description
CENTER or
CENTRE
Returns a string of a specified length with the input string centered in it, with pad characters
added as necessary to make up the length.
COPIES Returns the specified number of concatenated copies of the input string.
Using Functions
Chapter 5. Using Functions 53
Function Description
FORMAT Returns the input number, rounded and formatted.
JUSTIFY Returns a specified string formatted by adding pad characters between words to justify to both
margins.
LEFT Returns a string of the specified length, truncated or padded on the right as needed.
RIGHT Returns a string of the specified length, truncated or padded on the left as needed.
SPACE Returns the words in the input string with a specified number of pad characters between each
word.
String Manipulating Functions
Function Description
ABBREV Returns a string indicating if one string is equal to the specified number of leading characters of
another string.
DELSTR Returns a string after deleting a specified number of characters, starting at a specified point in
the input string.
DELWORD Returns a string after deleting a specified number of words, starting at a specified word in the
input string.
FIND Returns the word number of the first word of a specified phrase found within the input string.
INDEX Returns the character position of the first character of a specified string found in the input string.
INSERT Returns a character string after inserting another input string into it from a specified character
position.
LASTPOS Returns the starting character position of the last occurrence of one string in another.
LENGTH Returns the length of the input string.
OVERLAY Returns a string that is the target string overlaid by a second input string.
POS Returns the character position of one string in another.
REVERSE Returns a character string that is the reverse of the original.
STRIP Returns a character string after removing leading or trailing characters or both from the input
string.
SUBSTR Returns a portion of the input string beginning at a specified character position.
SUBWORD Returns a portion of the input string starting at a specified word number.
TRANSLATE Returns a character string with each character of the input string translated to another character
or unchanged.
VERIFY Returns a number indicating whether an input string is composed only of characters from
another input string or returns the character position of the first unmatched character.
WORD Returns a word from an input string as a specified number indicates.
WORDINDEX Returns the character position in an input string of the first character in the specified word.
WORDLENGTH Returns the length of a specified word in the input string.
WORDPOS Returns the word number of the first word of a specified phrase in the input string.
WORDS Returns the number of words in the input string.
Miscellaneous Functions
Function Description
ADDRESS Returns the name of the environment to which commands are currently being sent.
Using Functions
54 CICS TS for VSE/ESA: REXX Guide
Function Description
ARG Returns an argument string or information about the argument strings to a program or internal
routine.
BITAND Returns a string composed of the two input strings logically ANDed together, bit by bit.
BITOR Returns a string composed of the two input strings logically ORed together, bit by bit.
BITXOR Returns a string composed of the two input strings eXclusive ORed together, bit by bit.
CONDITION Returns the condition information, such as name and status, associated with the current trapped
condition.
DATE Returns the date in the default format (dd mon yyyy) or in one of various optional formats.
ERRORTEXT Returns the error message associated with the specified error number.
EXTERNALS This function always returns a 0.
LINESIZE Returns the width of the current output device.
QUEUED Returns the number of lines remaining in the external data queue at the time when the function
is called.
SOURCELINE Returns either the line number of the last line in the source file or the source line a number
specifies.
TIME Returns the local time in the default 24-hour clock format (hh:mm:ss) or in one of various
optional formats.
TRACE Returns the trace actions currently in effect.
USERID Returns the current user ID. This is the last user ID specified on the SETUID command, the
user ID of the calling REXX program if one program calls another, the user ID under which the
job is running, or the job name.
VALUE Returns the value of a specified symbol and optionally assigns it a new value.
XRANGE Returns a string of all 1-byte codes (in ascending order) between and including specified starting
and ending values.
Testing Input with Built-In Functions
Some of the built-in functions provide a convenient way to test input. When a program uses input, the user
might provide input that is not valid. For instance, in the example of using comparison expressions on
page 24, the program uses a dollar amount in the following instruction.
PARSE PULL yesterday /* Gets yesterday’s price from input stream */
If the program pulls only a number, the program processes that information correctly. However, if the
program pulls a number preceded by a dollar sign or pulls a word, such as nothing, the program returns
an error. To avoid getting an error, you can check the input with the DATATYPE function as follows.
IF DATATYPE(yesterday) \= ’NUM’
THEN DOSAY ’The input amount was in the wrong format.’
EXIT
END
Other useful built-in functions to test input are WORDS, VERIFY, LENGTH, and SIGN.
Exercise - Writing a program with Built-In Functions
Write a program that checks a file name for a length of 8 characters. If the name is longer than 8
characters, the program truncates it to 8 and sends a message indicating the shortened name. Use the
built-in functions LENGTH, see page 188, and SUBSTR, see page 192.
ANSWER
Using Functions
Chapter 5. Using Functions 55
/***************************** REXX *********************************/
/* This program tests the length of a file name. */
/* If the name is longer than 8 characters, the program truncates */
/* extra characters and sends a message indicating the shortened */
/* name. */
/********************************************************************/
PULL name /* Gets name from input stream */
IF LENGTH(name) > 8 THEN /* Name is longer than 8 characters */
DOname = SUBSTR(name,1,8) /* Shorten name to first 8 characters */
SAY ’The name you specified was too long.’
SAY name ’will be used.’
END
ELSE NOP
Figure 28. Possible Solution
56 CICS TS for VSE/ESA: REXX Guide
Chapter 6. Writing Subroutines and Functions
This chapter shows how to write subroutines and functions and discusses their differences and similarities.
What are Subroutines and Functions?
Subroutines and functions are routines made up of a sequence of instructions that can receive data,
process it, and return a value. The routines can be:
Internal
The routine is within the current program, marked by a label, and only that program uses the
routine.
External
A REXX subroutine that exists as a separate file.
In many aspects, subroutines and functions are the same. However, they are different in a few major
aspects, such as how to call them and the way they return values.
vCalling a subroutine
To call a subroutine, use the CALL instruction followed by the subroutine name (label or program
member name). You can optionally follow this with up to 20 arguments separated by commas. The
subroutine call is an entire instruction.
CALL subroutine_name argument1, argument2,...
vCalling a function
To call a function, use the function name (label or program member name) immediately followed by
parentheses that can contain arguments. There can be no space between the function name and the
left parentheses. The function call is part of an instruction, for example, an assignment instruction.
z = function(argument1, argument2,...)
vReturning a value from a subroutine
A subroutine does not have to return a value, but when it does, it sends back the value with the
RETURN instruction.
RETURN value
The calling program receives the value in the REXX special variable named RESULT.
SAY ’The answer is’ RESULT
vReturning a value from a function
A function must return a value. When the function is a REXX program, the value is returned with either
the RETURN or EXIT instruction.
RETURN value
The calling program receives the value at the function call. The value replaces the function call, so that
in the following example, z = value.
z = function(argument1, argument2,...)
When to Write Subroutines Rather Than Functions
The actual instructions that make up a subroutine or a function can be identical. It is the way you want to
use them in a program that turns them into either a subroutine or a function. For example, you can call the
built-in function SUBSTR as either a function or a subroutine. This is how to call SUBSTR as a function to
shorten a word to its first eight characters:
a = SUBSTR(’verylongword’,1,8) /* a is set to ’verylong’ */
You get the same results if you call SUBSTR as a subroutine.
© Copyright IBM Corp. 1992, 2010 57
CALL SUBSTR ’verylongword’, 1, 8
a = RESULT /* a is set to ’verylong’ */
When deciding whether to write a subroutine or a function, ask yourself the following questions:
vIs a returned value optional? If so, write a subroutine.
vDo I need a value returned as an expression within an instruction? If so, write a function.
The rest of this chapter describes how to write subroutines and functions and finally summarizes the
differences and similarities between the two.
Writing Subroutines and Functions
A subroutine is a series of instructions that a program calls to perform a specific task. The instruction that
calls the subroutine is the CALL instruction. You can use the CALL instruction several times in a program
to call the same subroutine.
When the subroutine ends, it can return control to the instruction that directly follows the subroutine call.
The instruction that returns control is the RETURN instruction.
instruction(s)
EXIT
sub1:
instruction(s)
RETURN
instruction(s)
CALL sub1
A function is a series of instructions that a program calls to perform a specific task and return a value. As
Chapter 5, “Using Functions,” on page 51 describes, a function can be built-in or user-written. Call a
user-written function the same way as a built-in function: specify the function name immediately followed
by parentheses that can contain arguments. There can be no blanks between the function name and the
left parenthesis. The parentheses can contain up to 20 arguments or no arguments at all.
function(argument1, argument2,...)
or function()
A function requires a return value because the function call generally appears in an expression.
z = function(arguments1, argument2,...)
When the function ends, it can use the RETURN instruction to send back a value to replace the function
call.
Writing Subroutines and Functions
58 CICS TS for VSE/ESA: REXX Guide
instruction(s)
EXIT
instruction(s)
instruction(s)
RETURN
z=func1(arg1, arg2)
Both subroutines and functions can be internal (designated by a label) or external (designated by the
subroutine or function in the REXX File System/VSE Librarian sublibrary member name). The two
preceding examples illustrate an internal subroutine named sub1 and an internal function named func1.
IMPORTANT NOTE
Because internal subroutines and functions generally appear after the main part of the program,
when you have an internal subroutine or function, it is important to end the main part of the program
with the EXIT instruction.
The following illustrates an external subroutine named sub2.
instruction(s)
…
…
...
sub2:
instruction(s)
RETURN
instruction(s)
CALL sub2
MAIN
The following illustrates an external function named func2.
Writing Subroutines and Functions
Chapter 6. Writing Subroutines and Functions 59
FUNC2
ARG var1
instruction(s)
RETURN value
MAIN
instruction(s)
z=func2(arg1)
instruction(s)
…
…
…
exit
When to Use Internal Versus External Subroutines or Functions
To determine whether to make a subroutine or function internal or external, you might consider factors,
such as:
vSize of the subroutine or function. Very large subroutines and functions often are external, whereas
small ones fit easily within the calling program.
vHow you want to pass information. It is quicker to pass information through variables in an internal
subroutine or function. The next topic describes passing information this way.
vWhether the subroutine or function might be of value to more than one program or user. If so, an
external subroutine or function is preferable.
vPerformance. For functions, the language processor searches for an internal function before it searches
for an external function.
Passing Information
A program and its internal subroutine or function can share the same variables. Therefore, you can use
commonly shared variables to pass information between caller and internal subroutine or function. You can
also use arguments to pass information to and from an internal subroutine or an internal function. External
subroutines, however, cannot share variables with the caller. To pass information to them, you need to use
arguments or some other external way, such as the data stack. (Remember: An internal function does not
need to pass arguments within the parentheses that follow the function call. However, all functions, both
internal and external, must return a value.)
Passing Information by Using Variables
When a program and its internal subroutine or function share the same variables, the value of a variable is
what was last assigned. This is regardless of whether the assignment was in the main part of the program
or in the subroutine or function.
The following example shows passing information to a subroutine. The variables number1,number2, and
answer are shared. The value of answer is assigned in the subroutine and used in the main part of the
program.
Writing Subroutines and Functions
60 CICS TS for VSE/ESA: REXX Guide
The next example is the same, except it passes information to a function rather than a subroutine. The
subroutine includes the variable answer on the RETURN instruction. The language processor replaces the
function call with the value in answer.
Using the same variables in a program and its internal subroutine or function can sometimes create
problems. In the next example, the main part of the program and the subroutine use the same control
variable, i, for their DO loops. As a result, the DO loop runs only once in the main program because the
subroutine returns to the main program with i=6.
/******************************* REXX ********************************/
/* This program receives a calculated value from an internal */
/* subroutine and uses that value in a SAY instruction. */
/*********************************************************************/
number1 = 5
number2 = 10
CALL subroutine
SAY answer /* Produces 15 */
EXIT
subroutine:
answer = number1 + number2
RETURN
Figure 29. Example of Passing Information in a Variable Using a Subroutine
/******************************* REXX ********************************/
/* This program receives a calculated value from an internal */
/* function and uses SAY to produce that value. */
/*********************************************************************/
number1 = 5
number2 = 10
SAY add() /* Produces 15 */
SAY answer /* Also produces 15 */
EXIT
add:
answer = number1 + number2
RETURN answer
Figure 30. Example of Passing Information in a Variable Using a Function
Writing Subroutines and Functions
Chapter 6. Writing Subroutines and Functions 61
The next example is the same, except it passes information using a function instead of a subroutine.
To avoid this kind of problem in an internal subroutine or function, you can use:
vThe PROCEDURE instruction, as the next topic describes.
vDifferent variable names in a subroutine or function than in the main part of the program. For a
subroutine, you can pass arguments on the CALL instruction; section “Passing Information by Using
Arguments” on page 64 describes this.
Protecting Variables with the PROCEDURE Instruction: When you use the PROCEDURE instruction
immediately after the subroutine or function label, all variables in the subroutine or function become local
to the subroutine or function; they are shielded from the main part of the program. You can also use the
PROCEDURE EXPOSE instruction to protect all but a few specified variables.
/******************************* REXX ********************************/
/* NOTE: This program contains an error. */
/* It uses a DO loop to call an internal subroutine, and the */
/* subroutine uses a DO loop with the same control variable as the */
/* main program. The DO loop in the main program runs only once. */
/*********************************************************************/
number1 = 5
number2 = 10
DOi=1TO5
CALL subroutine
SAY answer /* Produces 105 */
END
EXIT
subroutine:
DOi=1TO5
answer = number1 + number2
number1 = number2
number2 = answer
END
RETURN
Figure 31. Example of a Problem Caused by Passing Information in a Variable Using a Subroutine
/******************************* REXX ********************************/
/* NOTE: This program contains an error. */
/* It uses a DO loop to call an internal function, and the */
/* function uses a DO loop with the same control variable as the */
/* main program. The DO loop in the main program runs only once. */
/*********************************************************************/
number1 = 5
number2 = 10
DOi=1TO5
SAY add() /* Produces 105 */
END
EXIT
add:
DOi=1TO5
answer = number1 + number2
number1 = number2
number2 = answer
END
RETURN answer
Figure 32. Example of a Problem Caused by Passing Information in a Variable Using a Function
Writing Subroutines and Functions
62 CICS TS for VSE/ESA: REXX Guide
The following examples show how results differ when a subroutine or function uses or does not use
PROCEDURE.
The next two examples are the same, except they use functions rather than subroutines.
/******************************* REXX ********************************/
/* This program uses a PROCEDURE instruction to protect the */
/* variables within its subroutine. */
/*********************************************************************/
number1 = 10
CALL subroutine
SAY number1 number2 /* Produces 10 NUMBER2 */
EXIT
subroutine: PROCEDURE
number1 = 7
number2 = 5
RETURN
Figure 33. Example of Subroutine Using the PROCEDURE Instruction
/******************************* REXX ********************************/
/* This program does not use a PROCEDURE instruction to protect the */
/* variables within its subroutine. */
/*********************************************************************/
number1 = 10
CALL subroutine
SAY number1 number2 /* Produces 7 5 */
EXIT
subroutine:
number1 = 7
number2 = 5
RETURN
Figure 34. Example of Subroutine without the PROCEDURE Instruction
/******************************* REXX ********************************/
/* This program uses a PROCEDURE instruction to protect the */
/* variables within its function. */
/*********************************************************************/
number1 = 10
SAY pass() number2 /* Produces 7 NUMBER2 */
EXIT
pass: PROCEDURE
number1 = 7
number2 = 5
RETURN number1
Figure 35. Example of Function Using the PROCEDURE Instruction
Writing Subroutines and Functions
Chapter 6. Writing Subroutines and Functions 63
Exposing Variables with PROCEDURE EXPOSE: To protect all but specific variables, use the EXPOSE
option with the PROCEDURE instruction, followed by the variables that are to remain exposed to the
subroutine or function.
The next example uses PROCEDURE EXPOSE in a subroutine.
The next example is the same except PROCEDURE EXPOSE is in a function instead of a subroutine.
For more information about the PROCEDURE instruction, see section “PROCEDURE” on page 155.
Passing Information by Using Arguments
A way to pass information to either internal or external subroutines or functions is through arguments.
When calling a subroutine, you can pass up to 20 arguments separated by commas on the CALL
instruction as follows:
CALL subroutine_name argument1, argument2, argument3,...
/******************************* REXX ********************************/
/* This program does not use a PROCEDURE instruction to protect the */
/* variables within its function. */
/*********************************************************************/
number1 = 10
SAY pass() number2 /* Produces 7 5 */
EXIT
pass:
number1 = 7
number2 = 5
RETURN number1
Figure 36. Example of Function without the PROCEDURE Instruction
/******************************* REXX ********************************/
/* This program uses a PROCEDURE instruction with the EXPOSE option */
/* to expose one variable, number1, in its subroutine. The other */
/* variable, number2, is set to null and the SAY instruction */
/* produces this name in uppercase. */
/*********************************************************************/
number1 = 10
CALL subroutine
SAY number1 number2 /* produces 7 NUMBER2 */
EXIT
subroutine: PROCEDURE EXPOSE number1
number1 = 7
number2 = 5
RETURN
Figure 37. Example Using PROCEDURE EXPOSE in Subroutine
/******************************* REXX ********************************/
/* This program uses a PROCEDURE instruction with the EXPOSE option */
/* to expose one variable, number1, in its function. */
/*********************************************************************/
number1 = 10
SAY pass() number1 /* Produces 5 7 */
EXIT
pass: PROCEDURE EXPOSE number1
number1 = 7
number2 = 5
RETURN number2
Figure 38. Example Using PROCEDURE EXPOSE in a Function
Writing Subroutines and Functions
64 CICS TS for VSE/ESA: REXX Guide
In a function call, you can pass up to 20 arguments separated by commas.
function(argument1,argument2,argument3,...)
Using the ARG Instruction: A subroutine or function can receive the arguments with the ARG
instruction. In the ARG instruction, commas also separate arguments.
ARG arg1, arg2, arg3, ...
The names of the arguments that are passed do not have to be the same as those on the ARG instruction
because information is passed by position rather than by argument name. The first argument sent is the
first argument received and so forth. You can also set up a template in the CALL instruction or function
call. The language processor then uses this template in the corresponding ARG instruction. For information
about parsing with templates, see section “Parsing Data” on page 73.
In the following example, the main routine sends information to a subroutine that computes the perimeter
of a rectangle. The subroutine returns a value in the variable perim by specifying the value in the RETURN
instruction. The main program receives the value in the special variable RESULT.
The next example is the same except it uses ARG in a function instead of a subroutine.
This program receives as arguments the length and width of a
rectangle and passes that information to an internal subroutine.
The subroutine then calculates the perimeter of the rectangle.
PARSE ARG long wide
CALL perimeter long, wide
SAY ‘The perimeter is’ RESULT ‘inches.’
EXIT
perimeter:
ARG length, width
perim = 2 * length + 2 * width
RETURN perim
/***********************************REXX***********************************/
/* */
/* */
/* */
/*****************************************************************************/
Figure 39. Example of Passing Arguments on the CALL Instruction
Writing Subroutines and Functions
Chapter 6. Writing Subroutines and Functions 65
In the two preceding examples, notice the positional relationships between long and length, and wide and
width. Also notice how information is received from variable perim. Both programs include perim on a
RETURN instruction. For the program with a subroutine, the language processor assigns the value in
perim to the special variable RESULT. For the program using a function, the language processor replaces
the function call perimeter(long,wide) with the value in perim.
Using the ARG Built-in Function: Another way for a subroutine or function to receive arguments is with
the ARG built-in function. This function returns the value of a particular argument. A number represents the
argument position.
For instance, in the previous example, instead of the ARG instruction:
ARG length, width
you can use the ARG function as follows:
length = ARG(1) /* puts the first argument into length */
width = ARG(2) /* puts the second argument into width */
For more information about the ARG function see section “ARG” on page 134.
Receiving Information from a Subroutine or Function
Although a subroutine or function can receive up to 20 arguments, it can specify only one expression on
the RETURN instruction. That expression can be:
vA number
RETURN 55
vOne or more variables whose values are substituted (or their names if no values have been assigned).
RETURN value1 value2 value3
vA literal string
RETURN ’Work complete.’
vAn arithmetic, comparison, or logical expression whose value is substituted.
RETURN 5 * number
This program receives as arguments the length and width of a
rectangle and passes that information to an internal function,
named perimeter. The function then calculates the perimeter of
the rectangle.
/***********************************REXX***********************************/
/* */
/* */
/* */
/* */
/*****************************************************************************/
PARSE ARG long wide
SAY ‘The perimeter is’ perimeter (long,wide) ‘inches.’
EXIT
perimeter:
ARG length, width
perim = 2 * length + 2 * width
RETURN perim
Figure 40. Example of Passing Arguments on the Call to an Internal Routine
Writing Subroutines and Functions
66 CICS TS for VSE/ESA: REXX Guide
Exercise - Writing an Internal and an External Subroutine
Write a program that plays a simulated coin toss game and produces the accumulated scores.
There should be four possible inputs:
v'HEADS'
v'TAILS'
v'' (Null—to quit the game)
vNone of these three (incorrect response).
Write an internal subroutine without arguments to check for valid input. Send valid input to an external
subroutine that uses the RANDOM built-in function to generate random outcomes. Assume HEADS = 0
and TAILS = 1, and use RANDOM as follows:
RANDOM(0,1)
Compare the valid input with the value from RANDOM. If they are the same, the user wins one point; if
they are different, the computer wins one point. Return the result to the main program where results are
tallied.
ANSWER
/***************************** REXX ********************************/
/* This program plays a simulated coin toss game. */
/* The input can be heads, tails, or null ("") to quit the game. */
/* First an internal subroutine checks input for validity. */
/* An external subroutine uses the RANDOM built-in function to */
/* obtain a simulation of a throw of dice and compares the user */
/* input to the random outcome. The main program receives */
/* notification of who won the round. It maintains and produces */
/* scores after each round. */
/*******************************************************************/
PULL flip /* Gets "HEADS", "TAILS", or "" */
/* from input stream. */
computer = 0; user = 0 /* Initializes scores to zero */
CALL check /* Calls internal subroutine, check */
DO FOREVER
CALL throw /* Calls external subroutine, throw */
IF RESULT = ’machine’ THEN /* The computer won */
computer = computer + 1 /* Increase the computer score */
ELSE /* The user won */
user = user + 1 /* Increase the user score */
SAY ’Computer score = ’ computer ’ Your score = ’ user
PULL flip
CALL check /* Call internal subroutine, check */
END
EXIT
Figure 41. Possible Solution (Main Program)
Writing Subroutines and Functions
Chapter 6. Writing Subroutines and Functions 67
Exercise - Writing a Function
Write a function named AVG that receives a list of numbers separated by blanks and computes their
average. The final answer can be a decimal number. To call this function, you would use:
AVG(number1 number2 number3...)
Use the WORDS (see section “WORDS” on page 199) and WORD (see section “WORD” on page 198)
built-in functions.
ANSWER
/*************************** REXX ************************************/
/* This internal subroutine checks for valid input of "HEADS", */
/* "TAILS", or "" (to quit). If the input is anything else, the */
/* subroutine says the input is not valid and gets the next input. */
/* The subroutine keeps repeating until the input is valid. */
/* Commonly used variables return information to the main program */
/*********************************************************************/
check:
DO UNTIL outcome = ’correct’
SELECT
WHEN flip = ’HEADS’ THEN
outcome = ’correct’
WHEN flip = ’TAILS’ THEN
outcome = ’correct’
WHEN flip = ’’ THEN
EXIT
OTHERWISE
outcome = ’incorrect’
PULL flip
END
END
RETURN
Figure 42. Possible Solution (Internal Subroutine Named CHECK)
/******************************* REXX ********************************/
/* This external subroutine receives the valid input, analyzes it, */
/* gets a random "flip" from the computer, and compares the two. */
/* If they are the same, the user wins. If they are different, */
/* the computer wins. The routine returns the outcome to the */
/* calling program. */
/*********************************************************************/
throw:
ARG input
IF input = ’HEADS’ THEN
userthrow = 0 /* heads = 0 */
ELSE
userthrow = 1 /* tails = 1 */
compthrow = RANDOM(0,1) /* choose a random number */
/* between 0 and 1 */
IF compthrow = userthrow THEN
outcome = ’human’ /* user chose correctly */
ELSE
outcome = ’machine’ /* user chose incorrectly */
RETURN outcome
Figure 43. Possible Solution (External Subroutine named THROW)
Writing Subroutines and Functions
68 CICS TS for VSE/ESA: REXX Guide
/******************************* REXX ********************************/
/* This function receives a list of numbers, adds them, computes */
/* their average, and returns the average to the calling program. */
/*********************************************************************/
ARG numlist /* receive the numbers in a single variable */
sum = 0 /* initialize sum to zero */
DOn=1TOWORDS(numlist) /* Repeat for as many times as there */
/* are numbers */
number = WORD(numlist,n) /* Word #n goes to number */
sum = sum + number /* Sum increases by number */
END
average = sum / WORDS(numlist) /* Compute the average */
RETURN average
Figure 44. Possible Solution
Writing Subroutines and Functions
Chapter 6. Writing Subroutines and Functions 69
Subroutines and Functions—Similarities and Differences
The following tables highlight similarities and differences between subroutines and functions:
Similarities between Subroutines and Functions
Can be internal or external.
Internal
– Can pass information by using common variables
– Can protect variables with the PROCEDURE instruction
– Can pass information by using arguments.
External
– Must pass information by using arguments
– Can use the ARG instruction or the ARG built-in function to receive arguments.
Uses the RETURN instruction to return to the caller.
Table 3. Differences between Subroutines and Functions
Subroutines Functions
Calling Call by using the CALL instruction, followed
by the subroutine name and, optionally, up to
20 arguments.
Call by specifying the function's name,
immediately followed by parentheses that
optionally contain up to 20 arguments.
Returning a Value Might return a value to the caller. If you
include a value on the RETURN instruction,
the language processor assigns this value to
the REXX special variable RESULT.
Must return a value. Specify a value on the
RETURN instruction; the language processor
replaces the function call with this value.
Writing Subroutines and Functions
70 CICS TS for VSE/ESA: REXX Guide
Chapter 7. Manipulating Data
This chapter describes how to use compound variables and stems and explains parsing.
Using Compound Variables and Stems
Sometimes it is useful to store groups of related data in a way that makes data retrieval easy. For
example, you could store a list of employee names in an array and retrieve them by number. An array is
an arrangement of elements in one or more dimensions, identified by a single name. An array called
employee could contain names as follows:
EMPLOYEE
(1) Adams, Joe
(2) Crandall, Amy
(3) Devon, David
(4) Garrison, Donna
(5) Leone, Mary
(6) Sebastian, Isaac
In some computer languages, you use the number of the element to access an element in an array. For
example, employee(1) would retrieve Adams, Joe. In REXX, you use compound variables.
What Is a Compound Variable?
You can use compound variables to create an array or a list of variables in REXX. A compound variable,
for example: employee.1, consists of a stem and a tail. A stem is a symbol with a period at the end. Here
are some examples of stems:
FRED.
Array.
employee.
Atail is similar to a subscript. It follows the stem and consists of additional parts of the name that can be
constant symbols (as in employee.1), simple symbols (as in employee.n), or null. Thus, in REXX,
subscripts need not necessarily be numeric. A compound variable contains at least one period with
characters on both sides of it. Here are some more examples of compound variables:
FRED.5
Array.Row.Col
employee.name.phone
You cannot do any substitution for the name of the stem but you can use substitution for the tail. For
example:
employee.7=’Amy Martin’
new=7
employee.new=’May Davis’
say employee.7 /* Produces: May Davis */
As with other REXX variables, if you have not previously assigned a value to a variable in a tail, it takes
on the value of its own name in uppercase.
first = ’Fred’
last = ’Higgins’
name = first.last /* NAME is assigned FIRST.Higgins */
/* The value FIRST appears because the */
/* variable FIRST is a stem, which */
/* cannot change. */
SAY name.first.middle.last /* Produces NAME.Fred.MIDDLE.Higgins */
You can use a DO loop to initialize a group of compound variables and set up an array.
© Copyright IBM Corp. 1992, 2010 71
DOi=1TO6
PARSE PULL employee.i
END
If you use the same names used in the example of the employee array, you have a group of compound
variables as follows:
employee.1 = ’Adams, Joe’
employee.2 = ’Crandall, Amy’
employee.3 = ’Devon, David’
employee.4 = ’Garrison, Donna’
employee.5 = ’Leone, Mary’
employee.6 = ’Sebastian, Isaac’
After the names are in the group of compound variables, you can easily access a name by its number or
by a variable that represents its number.
name = 3
SAY employee.name /* Produces ’Devon, David’ */
For more information about compound variables, see section “Compound Symbols” on page 122.
Using Stems
When working with compound variables, it is often useful to initialize an entire collection of variables to the
same value. You can do this easily by using an assignment that includes a stem. For example, number.=0
initializes all array elements in the array named number. to 0.
You can change the values of all compound variables in an array the same way. For example, to change
all employee names to Nobody, use the following assignment instruction:
employee. = ’Nobody’
As a result, all compound variables beginning with the stem employee., previously assigned or not, have
the value Nobody. After a stem assignment, you can assign individual compound variables new values.
employee.=’Nobody’
SAY employee.5 /* Produces ’Nobody’ */
SAY employee.10 /* Produces ’Nobody’ */
SAY employee.oldest /* Produces ’Nobody’ */
employee.new = ’Clark, Evans’
SAY employee.new /* Produces ’Clark, Evans’ */
You can use stems with the EXECIO and RFS commands when reading to and writing from a file. See
section “EXECIO” on page 344 for information about EXECIO. See section “RFS” on page 363 for
information about RFS. RFS is the preferred I/O method under CICS.
Exercises - Using Compound Variables and Stems
1. After these assignment instructions, what do the following SAY instructions produce?
a = 3 /* assigns ’3’ to variable ’A’ */
d = 4 /* ’4’ to ’D’ */
c = ’last’ /* ’last’ to ’C’ */
a.d = 2 /* ’2’ to ’A.4’ */
a.c = 5 /* ’5’ to ’A.last’ */
z.a.d = ’cv3d’ /* ’cv3d’ to ’Z.3.4’ */
a. SAY a
b. SAY D
c. SAY c
d. SAY a.a
e. SAY A.D
f. SAY d.c
g. SAY c.a
Manipulating Data
72 CICS TS for VSE/ESA: REXX Guide
h. SAY a.first
i. SAY z.a.4
2. After these assignment instructions, what output do the SAY instructions produce?
hole.1 = ’full’
hole. = ’empty’
hole.s = ’full’
a. SAY hole.1
b. SAY hole.s
c. SAY hole.mouse
ANSWERS
1.
a. 3
b. 4
c. last
d. A.3
e. 2
f. D.last
g. C.3
h. A.FIRST
i. cv3d
2.
a. empty
b. full
c. empty
Parsing Data
Parsing is separating data and assigning parts of it into one or more variables. Parsing can assign each
word in the data into a variable or can divide the data into smaller parts. Parsing is also useful to format
data into columns.
The variables to receive data are named in a template. A template is a model telling how to split the data.
It can be as simple as a list of variables to receive data. More complex templates can contain patterns;
section “Parsing with Patterns” on page 75 explains patterns.
Parsing Instructions
The REXX parsing instructions are PULL, ARG, and PARSE. (PARSE has several variants.)
PULL Instruction
Other chapters show PULL as an instruction that reads input and assigns it to one or more variables. If the
program stack contains information, the PULL instruction takes information from the program stack. When
the program stack is empty, PULL takes information from the current terminal input device. See section
“Getting Information from the Program Stack or Terminal Input Device” on page 14 for information about
the data stack.
/* This REXX program parses the string "Knowledge is power." */
PULL word1 word2 word3
/* word1 contains ’KNOWLEDGE’ */
/* word2 contains ’IS’ */
/* word3 contains ’POWER.’ */
PULL uppercases character information before assigning it into variables. If you do not want uppercase
translation, use the PARSE PULL instruction.
Manipulating Data
Chapter 7. Manipulating Data 73
/* This REXX program parses the string: "Knowledge is power." */
PARSE PULL word1 word2 word3
/* word1 contains ’Knowledge’ */
/* word2 contains ’is’ */
/* word3 contains ’power.’ */
You can include the optional keyword UPPER on any variant of the PARSE instruction.This causes the
language processor to uppercase character information before assigning it into variables. For example,
using PARSE UPPER PULL... gives the same result as using PULL.
ARG Instruction
The ARG instruction takes information passed as arguments to a program, function, or subroutine, and
puts it into one or more variables. To pass the three arguments Knowledge is power. to a REXX program
named sample:
1. Call the program and pass the arguments as a string following the exec name:
REXX sample Knowledge is power.
2. Use the ARG instruction to receive the three arguments into variables.
/* SAMPLE -- A REXX program using ARG */
ARG word1 word2 word3
/* word1 contains ’KNOWLEDGE’ */
/* word2 contains ’IS’ */
/* word3 contains ’POWER.’ */
ARG uppercases the character information before assigning the arguments into variables.
If you do not want uppercase translation, use the PARSE ARG instruction instead of ARG.
/* REXX program using PARSE ARG */
PARSE ARG word1 word2 word3
/* word1 contains ’Knowledge’ */
/* word2 contains ’is’ */
/* word3 contains ’power.’ */
PARSE UPPER ARG has the same result as ARG. It uppercases character information before assigning it
into variables.
PARSE VALUE ... WITH Instruction
The PARSE VALUE...WITH instruction parses a specified expression, such as a literal string, into one or
more variables whose names follow the WITH subkeyword.
PARSE VALUE ’Knowledge is power.’ WITH word1 word2 word3
/* word1 contains ’Knowledge’ */
/* word2 contains ’is’ */
/* word3 contains ’power.’ */
PARSE VALUE does not uppercase character information before assigning it into variables. If you want
uppercase translation, use PARSE UPPER VALUE. You could use a variable instead of a string in PARSE
VALUE (you would first assign the variable the value):
string=’Knowledge is power.’
PARSE VALUE string WITH word1 word2 word3
/* word1 contains ’Knowledge’ */
/* word2 contains ’is’ */
/* word3 contains ’power.’ */
Or you can use PARSE VAR to parse a variable.
PARSE VAR Instruction
The PARSE VAR instruction parses a specified variable into one or more variables.
Manipulating Data
74 CICS TS for VSE/ESA: REXX Guide
quote = ’Knowledge is power.’
PARSE VAR quote word1 word2 word3
/* word1 contains ’Knowledge’ */
/* word2 contains ’is’ */
/* word3 contains ’power.’ */
PARSE VAR does not uppercase character information before assigning it into variables. If you want
uppercase translation, use PARSE UPPER VAR.
More about Parsing into Words
In the preceding examples, the number of words in the data to parse is always the same as the number of
variables in the template. Parsing always assigns new values to all variables named in the template. If
there are more variable names than words in the data to parse, the leftover variables receive null (empty)
values. If there are more words in the data to parse than variable names in the template, each variable
gets one word of data in sequence except the last variable, which gets the remainder of the data.
In the next example, there are more variable names in the template than words of data; the leftover
variable receives a null value.
PARSE VALUE ’Extra variables’ WITH word1 word2 word3
/* word1 contains ’Extra’ */
/* word2 contains ’variables’ */
/* word3 contains ’’ */
In the next example there are more words in the data than variable names in the template; the last
variable gets the remainder of the data. The last variable name can contain several words and possibly
leading and trailing blanks.
PARSE VALUE ’More words in data’ WITH var1 var2 var3
/* var1 contains ’More’ */
/* var2 contains ’words’ */
/* var3 contains ’ in data’ */
Parsing into words generally removes leading and trailing blanks from each word before putting it into a
variable. However, when putting data into the last variable, parsing removes one word-separator blank but
retains any extra leading or trailing blanks. There are two leading blanks before words. Parsing removes
both the word-separator blank and the extra leading blank before putting ’words’ into var2. There are four
leading blanks before in. Because var3 is the last variable, parsing removes the word-separator blank but
keeps the extra leading blanks. Thus, var3 receives ’ in data’ (with three leading blanks).
A period in a template acts as a placeholder. It receives no data. You can use a period as a "dummy
variable" within a group of variables or at the end of a template to collect unwanted information.
string=’Example of using placeholders to discard junk’
PARSE VAR string var1 . var2 var3 .
/* var1 contains ’Example’ */
/* var2 contains ’using’ */
/* var3 contains ’placeholders’ */
/* The periods collect the words ’of’ and ’to discard junk’ */
For more information about parsing instructions, see section “PARSE” on page 152.
Parsing with Patterns
The simplest template is a group of blank-separated variable names. This parses data into blank-delimited
words. The preceding examples all use this kind of template. Templates can also contain patterns. A
pattern can be a string, a number, or a variable representing either of these.
Manipulating Data
Chapter 7. Manipulating Data 75
String
If you use a string in a template, parsing checks the input data for a matching string. When assigning data
into variables, parsing generally skips over the part of the input string that matches the string in the
template.
phrase = ’To be, or not to be?’ /* phrase containing comma */
PARSE VAR phrase part1 ’,’ part2 /* template containing comma */
/* as string separator */
/* part1 contains ’To be’ */
/* part2 contains ’ or not to be?’ */
In this example, notice that the comma is not included with 'To be' because the comma is the string
separator. (Notice also that part2 contains a value that begins with a blank. Parsing splits the input string
at the matching text. It puts data up to the start of the match in one variable and data starting after the
match in the next variable.
Variable
When you do not know in advance what string to specify as separator in a template, you can use a
variable enclosed in parentheses.
separator = ’,’
phrase = ’To be, or not to be?’
PARSE VAR phrase part1 (separator) part2
/* part1 contains ’To be’ */
/* part2 contains ’ or not to be?’ */
Again, in this example, notice that the comma is not included with 'To be' because the comma is the string
separator.
Number
You can use numbers in a template to indicate the column at which to separate data. An unsigned integer
indicates an absolute column position. A signed integer indicates a relative column position.
An unsigned integer or an integer with the prefix of an equal sign (=) separates the data according to
absolute column position. The first segment starts at column 1 and goes up to, but does not include, the
information in the column number specified. Subsequent segments start at the column numbers specified.
quote = ’Ignorance is bliss.’
....+....1....+....2
PARSE VAR quote part1 5 part2
/* part1 contains ’Igno’ */
/* part2 contains ’rance is bliss.’ */
The following code has the same result:
quote = ’Ignorance is bliss.’
....+....1....+....2
PARSE VAR quote 1 part1 =5 part2
/* part1 contains ’Igno’ */
/* part2 contains ’rance is bliss.’ */
Specifying the numeric pattern 1is optional. If you do not use a numeric pattern to indicate a starting point
for parsing, this defaults to 1. The example also shows that the numeric pattern 5is the same as =5.
If a template has several numeric patterns and a later one is lower than a preceding one, parsing loops
back to the column the lower number specifies.
quote = ’Ignorance is bliss.’
....+....1....+....2
PARSE VAR quote part1 5part2 10 part3 1part4
Manipulating Data
76 CICS TS for VSE/ESA: REXX Guide
/* part1 contains ’Igno’ */
/* part2 contains ’rance’ */
/* part3 contains ’ is bliss.’ */
/* part4 contains ’Ignorance is bliss.’ */
When each variable in a template has column numbers both before and after it, the two numbers indicate
the beginning and the end of the data for the variable.
quote = ’Ignorance is bliss.’
....+....1....+....2
PARSE VAR quote 1part1 10 11 part2 13 14 part3 191part4 20
/* part1 contains ’Ignorance’ */
/* part2 contains ’is’ */
/* part3 contains ’bliss’ */
/* part4 contains ’Ignorance is bliss.’ */
Thus, you could use numeric patterns to skip over part of the data:
quote = ’Ignorance is bliss.’
....+....1....+....2
PARSE VAR quote 2var1 35var2 78var3 var 4 var5
SAY var1||var2||var3 var4 var5 /* || means concatenate */
/* Says: grace is bliss. */
A signed integer in a template separates the data according to relative column position. The plus or minus
sign indicates movement right or left, respectively, from the starting position. In the next example,
remember that part1 starts at column 1 (by default because there is no number to indicate a starting
point).
quote = ’Ignorance is bliss.’
....+....1....+....2
PARSE VAR quote part1 +5 part2 +5 part3 +5 part4
/* part1 contains ’Ignor’ */
/* part2 contains ’ance ’ */
/* part3 contains ’is bl’ */
/* part4 contains ’iss.’ */
+5 part2 means parsing puts into part2 data starting in column 6 (1+5=6). +5 part3 means data put into
part3 starts with column 11 (6+5=11), and so on. The use of the minus sign is similar to the use of the
plus sign. It identifies a relative position in the data string. The minus sign “backs up” (moves to the left) in
the data string.
quote = ’Ignorance is bliss.’
....+....1....+....2
PARSE VAR quote part1 +10 part2 +3 part3 -3 part4
/* part1 contains ’Ignorance ’ */
/* part2 contains ’is ’ */
/* part3 contains ’bliss.’ */
/* part4 contains ’is bliss.’ */
In this example, part1 receives characters starting at column 1 (by default). +10 part2 receives characters
starting in column 11 (1+10=11). +3 part3 receives characters starting in column 14 (11+3=14). -3 part4
receives characters starting in column 11 (14-3=11).
To provide more flexibility, you can define and use variable numeric patterns in a parsing instruction. To do
this, first define the variable as an unsigned integer before the parsing instruction. Then, in the parsing
instruction, enclose the variable in parentheses and specify one of the following before the left parenthesis:
vA plus sign (+) to indicate column movement to the right
vA minus sign (-) to indicate column movement to the left
vAn equal sign (=) to indicate an absolute column position.
Manipulating Data
Chapter 7. Manipulating Data 77
(Without +,−,or=before the left parenthesis, the language processor would consider the variable to be a
string pattern.) The following example uses the variable numeric pattern movex.
quote = ’Ignorance is bliss.’
....+....1....+....2
movex = 3 /* variable position */
PARSE VAR quote part5 +10 part6 +3 part7 -(movex) part8
/* part5 contains ’Ignorance ’ */
/* part6 contains ’is ’ */
/* part7 contains ’bliss.’ */
/* part8 contains ’is bliss.’ */
For more information about parsing, see Chapter 15, “Parsing,” on page 203.
Parsing Multiple Strings as Arguments
When passing arguments to a function or a subroutine, you can specify multiple strings to be parsed. The
ARG, PARSE ARG, and PARSE UPPER ARG instructions parse arguments. These are the only parsing
instructions that work on multiple strings.
To pass multiple strings, use commas to separate adjacent strings.
The next example passes three arguments to an internal subroutine.
CALL sub2 ’String One’, ’String Two’, ’String Three’
:
:
EXIT
sub2:
PARSE ARG word1 word2 word3, string2, string3
/* word1 contains ’String’ */
/* word2 contains ’One’ */
/* word3 contains ’’ */
/* string2 contains ’String Two’ */
/* string3 contains ’String Three’ */
The first argument is two words "String One" to parse into three variable names, word1,word2, and word3.
The third variable, word3, is set to null because there is no third word. The second and third arguments are
parsed entirely into variable names string2 and string3.
For more information about parsing multiple arguments that have been passed to a program or subroutine,
see section “Parsing Multiple Strings” on page 211.
Exercise - Practice with Parsing
What are the results of the following parsing examples?
1. quote = ’Experience is the best teacher.’
PARSE VAR quote word1 word2 word3
a) word1 =
b) word2 =
c) word3 =
2. quote = ’Experience is the best teacher.’
PARSE VAR quote word1 word2 word3 word4 word5 word6
a) word1 =
b) word2 =
c) word3 =
d) word4 =
e) word5 =
f) word6 =
3. PARSE VALUE ’Experience is the best teacher.’ WITH word1 word2 . . word3
a) word1 =
b) word2 =
Manipulating Data
78 CICS TS for VSE/ESA: REXX Guide
c) word3 =
4. PARSE VALUE ’Experience is the best teacher.’ WITH v1 5 v2
....+....1....+....2....+....3.
a) v1 =
b) v2 =
5. quote = ’Experience is the best teacher.’
....+....1....+....2....+....3.
PARSE VAR quote v1 v2 15 v3 3 v4
a) v1 =
b) v2 =
c) v3 =
d) v4 =
6. quote = ’Experience is the best teacher.’
....+....1....+....2....+....3.
PARSE UPPER VAR quote 15 v1 +16 =12 v2 +2 1 v3 +10
a) v1 =
b) v2 =
c) v3 =
7. quote = ’Experience is the best teacher.’
....+....1....+....2....+....3.
PARSE VAR quote 1 v1 +11 v2 +6 v3 -4 v4
a) v1 =
b) v2 =
c) v3 =
d) v4 =
8. first = 7
quote = ’Experience is the best teacher.’
....+....1....+....2....+....3.
PARSE VAR quote 1 v1 =(first) v2 +6 v3
a) v1 =
b) v2 =
c) v3 =
9. quote1 = ’Knowledge is power.’
quote2 = ’Ignorance is bliss.’
quote3 = ’Experience is the best teacher.’
CALL sub1 quote1, quote2, quote3
EXIT
sub1:
PARSE ARG word1..,word2..,word3 .
a) word1 =
b) word2 =
c) word3 =
ANSWERS
1.
a) word1 = Experience
b) word2 = is
c) word3 = the best teacher.
2.
a) word1 = Experience
b) word2 = is
c) word3 = the
d) word4 = best
e) word5 = teacher.
Manipulating Data
Chapter 7. Manipulating Data 79
f) word6 = ''
3.
a) word1 = Experience
b) word2 = is
c) word3 = teacher.
4.
a) v1 = Expe
b) v2 = rience is the best teacher.
5.
a) v1 = Experience
b) v2 = is (Note that v2 contains ’is ’.)
c) v3 = the best teacher.
d) v4 = perience is the best teacher.
6.
a) v1 = THE BEST TEACHER
b) v2 = IS
c) v3 = EXPERIENCE
7.
a) v1 = 'Experience '
b) v2 = 'is the'
c) v3 = ' best teacher.'
d) v4 = ' the best teacher.'
8.
a) v1 = 'Experi'
b) v2 = 'ence i'
c) v3 = 's the best teacher.'
9.
a) word1 = Knowledge
b) word2 = Ignorance
c) word3 = Experience
Manipulating Data
80 CICS TS for VSE/ESA: REXX Guide
Chapter 8. Using Commands from a program
This chapter describes how to use commands in a REXX program.
Types of Commands
A REXX program can issue several types of commands. The main categories of commands are:
REXX/CICS commands
These commands provide access to miscellaneous REXX/CICS facilities. See Chapter 25,
“REXX/CICS Commands,” on page 319.
CICS commands
These commands implement the EXEC CICS commands that application programs use to access
CICS services. These commands are documented in the CICS Transaction Server for VSE/ESA
Application Programming Reference.
SQL statements
These statements are prepared and executed dynamically. See Chapter 22, “REXX/CICS DB2
Interface,” on page 285
EDIT commands
These commands invoke the editor facilities from the REXX/CICS macros. See Chapter 18,
“REXX/CICS Text Editor,” on page 231.
RFS commands
These commands are for the REXX File System (RFS). See Chapter 19, “REXX/CICS File
System,” on page 257.
RLS commands
These commands are for the REXX List System (RLS). See Chapter 20, “REXX/CICS List
System,” on page 273.
When a program issues a command, the REXX special variable RC is set to the return code. A program
can use the return code to determine a course of action within the program. Every time a command is
issued, RC is set. Therefore, RC contains the return code from the most recently issued command.
Using Quotations Marks in Commands
Generally, to differentiate commands from other types of instructions, you enclose the command within
single or double quotation marks. If the command is not enclosed within quotation marks, it is processed
as an expression and might end in error. For example, the language processor treats an asterisk (*)asa
multiplication operator.
Many CICS commands use single quotation marks within the command. For this reason, it is
recommended that, as a matter of course, you enclose CICS commands within double quotation marks.
The following example places the word test in the temporary storage queue ABC.
"CICS WRITEQ TS QUEUE(’ABC’) FROM(’test’)"
Using Variables in Commands
When a command contains a variable, the value of the variable is not substituted if the variable is within
quotation marks. The language processor uses the value of a variable only for variables outside quotation
marks.
© Copyright IBM Corp. 1992, 2010 81
Calling Another REXX Program as a Command
Previously, this book discussed how to call another program as an external routine (Chapter 6, “Writing
Subroutines and Functions,” on page 57). You can also call a program from another program explicitly with
the EXEC command. Like an external routine, a program called explicitly or implicitly can return a value to
the caller with the RETURN or EXIT instruction. Unlike an external routine, which passes a value to the
special variable RESULT, the program that is called passes a value to the REXX special variable RC.
Calling Another Program with the EXEC Command
To explicitly call another program from within a program, use the EXEC command as you would any other
REXX/CICS command. The called program should end with a RETURN or EXIT instruction, ensuring that
control returns to the caller. The REXX special variable RC is set to the return code from the EXEC
command. You can optionally return a value to the caller on the RETURN or EXIT instruction. When
control passes back to the caller, the REXX special variable RC is set to the value of the expression
returned on the RETURN or EXIT instruction.
For example, to call a program named CALC and pass it an argument of four numbers, you could include
the following instructions:
"EXEC calc 24 55 12 38"
SAY ’The result is’ RC
CALC might contain the following instructions:
ARG number1 number2 number3 number4
answer = number1 * (number2 + number3) - number4
RETURN answer
Issuing Commands from a program
The following sections explain what a host command environment is, how commands are passed to host
command environments, and how to change the host command environment.
What is a Host Command Environment?
An environment for executing commands is called a host command environment. Before a program
runs, an active host command environment is defined to handle the commands. . When the language
processor encounters a command, it passes the command to the host command environment for
processing.
When a REXX program runs on a host system, there is at least one default environment available for
executing commands.
The host command environments are as follows:
REXXCICS
This is the default REXX/CICS command environment. All REXX/CICS, SQL, EDIT, RFS, or RLS
commands can be issued from this environment. However, CICS commands must be prefixed with
CICS, SQL statements with EXECSQL, EDIT commands with EDITSVR, RFS commands with
RFS, and RLS commands with RLS.
CICS This is an optional environment that only issues CICS commands. The first word of the host
command string is the command name (for example: SEND, RECEIVE).
EXECSQL
This is an optional environment that issues SQL statements (SELECT) to the CICS/DB2 interface.
EDITSVR
This is an optional environment that creates the edit session.
FLSTSVR
This is an optional environment that executes commands for the File List Utility.
Using Commands from a Program
82 CICS TS for VSE/ESA: REXX Guide
RFS This is an optional environment that executes commands for the REXX File System.
RLS This is an optional environment that executes commands for the REXX List System.
Note: It is recommended that the default environment of REXXCICS be used for all commands (that is,
the ADDRESS instruction should not be specified).
How Is a Command Passed to the Host Environment?
The language processor evaluates each expression in a REXX program. This evaluation results in a
character string (which may be the null string). The character string is prepared appropriately and
submitted to the host command environment. The environment processes the string as a command, and,
after processing is complete, returns control to the language processor. If the string is not a valid
command for the current host command environment, a failure occurs and the special variable RC
contains the return code from the host command environment.
Changing the Host Command Environment
You can change the host command environment either from the default environment (REXXCICS) or from
whatever environment was previously established. To change the host command environment, use the
ADDRESS instruction followed by the name of an environment.
The ADDRESS instruction has two forms; one affects only a single command, and one affects all
commands issued after the instruction.
vSingle command
When an ADDRESS instruction includes both the name of the host command environment and a
command, only that command is sent to the specified environment. After the command is complete the
former host command environment becomes active again.
vAll commands
When an ADDRESS instruction includes only the name of the host command environment, all
commands issued afterward within that program are processed as that environment's commands.
This ADDRESS instruction affects only the host command environment of the program that uses the
instruction. If a program calls an external routine, the host command environment is the default
environment regardless of the host command environment of the calling program. Upon return to the
original program, the host command environment that the ADDRESS instruction previously established
is resumed.
Determining the Active Host Command Environment
To find out which host command environment is currently active, use the ADDRESS built-in function.
Example
curenv = ADDRESS()
In this example, curenv is set to the active host command environment, for example, REXXCICS.
Using Commands from a Program
Chapter 8. Using Commands from a program 83
84 CICS TS for VSE/ESA: REXX Guide
Chapter 9. Diagnosing Problems within a program
This chapter describes how to trace command output and other debugging techniques.
Debugging Programs
When you encounter an error in a program, there are several ways to locate the error.
vThe TRACE instruction shows how the language processor evaluates each operation. For information
about using the TRACE instruction to evaluate expressions, see section “Tracing Expressions with the
TRACE Instruction” on page 29. For information about using the TRACE instruction to evaluate host
commands, see the next section, “Tracing Commands with the TRACE Instruction.”
vREXX/CICS sets the special variables RC and SIGL as follows:
RC Indicates the return code from a command.
SIGL Indicates the line number from which there was a transfer of control because of a function call,
a SIGNAL instruction, or a CALL instruction.
Tracing Commands with the TRACE Instruction
The TRACE instruction has many options for various types of tracing, including Cfor commands and Efor
errors.
TRACE C
After TRACE C, the language processor traces each command before execution, then executes it and sends
the return code from the command to the current terminal output device. For more information on
specifying the current terminal output device, refer to the SET TERMOUT command.
TRACE E
When you specify TRACE E in a program, the language processor traces any host command that results in
a nonzero return code after execution and sends the return code from the command to the terminal.
If a program includes TRACE E and issues an incorrect command, the program sends error messages ,the
line number, the command, and the return code from the command to the output stream.
For more information about the TRACE instruction, see section “TRACE” on page 166.
Using REXX Special Variables RC and SIGL
The REXX language has three special variables: RC, SIGL, and RESULT. REXX/CICS sets these
variables during particular situations and you can use them in an expression at any time. If REXX/CICS
did not set a value, a special variable has the value of its own name in uppercase, as do other variables in
REXX. You can use two special variables, RC and SIGL, to help diagnose problems within programs.
RC
RC stands for return code. The language processor sets RC every time a program issues a command.
When a command ends without error, RC is usually 0. When a command ends in error, RC is whatever
return code is assigned to that error.
The RC variable can be especially useful in an IF instruction to determine which path a program should
take.
Note: Every command sets a value for RC, so it does not remain the same for the duration of a program.
When using RC, make sure it contains the return code of the command you want to test.
© Copyright IBM Corp. 1992, 2010 85
SIGL
The language processor sets the SIGL special variable in connection with a transfer of control within a
program because of a function, a SIGNAL or a CALL instruction. When the language processor transfers
control to another routine or another part of the program, it sets the SIGL special variable to the line
number from which the transfer occurred. (The line numbers in the following example are to aid in
discussion after the example. They are not part of the program.)
1 /* REXX */
2:
3 CALL routine
4:
5
6 routine:
7 SAY ’We came here from line’ SIGL /* SIGL is set to 3 */
8 RETURN
If the called routine itself calls another routine, SIGL is reset to the line number from which the most recent
transfer occurred.
SIGL and the SIGNAL ON ERROR instruction can help determine which command caused an error and
what the error was. When SIGNAL ON ERROR is in a program, any host command that returns a nonzero
return code causes a transfer of control to a routine named error. The error routine runs regardless of
other actions that would usually take place, such as the transmission of error messages.
For more information about the SIGNAL instruction, see section “SIGNAL” on page 164.
Tracing with the Interactive Debug Facility
The interactive debug facility lets a user control the execution of a program. The language processor reads
from the terminal, and writes output to the terminal.
Starting Interactive Debug
To start interactive debug, specify ?before the option of a TRACE instruction, for example: TRACE ?A.
There can be no blank(s) between the question mark and the option. Interactive debug is not carried over
into external routines that are called but is resumed when the routines return to the traced program.
Options within Interactive Debug
After interactive debug starts, you can provide one of the following during each pause or each time the
language processor reads from the input stream.
vA null line, which continues tracing. The language processor continues execution until the next pause or
read from the input stream. Repeated input of a null line, therefore, steps from pause point to pause
point until the program ends.
vAn equal sign (=), which re-executes the last instruction traced. The language processor re-executes
the previously traced instruction with values possibly modified by instructions read from the input
stream. (The input can also be an assignment, which changes the value of a variable.)
vAdditional instructions. This input can be any REXX instruction, including a command or call to another
program. This input is processed before the next instruction in the program is traced. For example, the
input could be a TRACE instruction that alters the type of tracing:
TRACE L /* Makes the language processor pause at labels only */
The input could be an assignment instruction. This could change the flow of a program, by changing the
value of a variable to force the execution of a particular branch in an IF THEN ELSE instruction. In the
following example, RC is set by a previous command.
IF RC = 0 THEN
DO
instruction1
Diagnosing Problems within a Program
86 CICS TS for VSE/ESA: REXX Guide
instruction2
END
ELSE
instructionA
If the command ends with a nonzero return code, the ELSE path is taken. To force taking the first path,
the input during interactive debug could be:
RC=0
Ending Interactive Debug
You can end interactive debug in one of the following ways:
vUse the TRACE OFF instruction as input. The TRACE OFF instruction ends tracing, as stated in the
message at the beginning of interactive debug:
+++ Interactive trace. TRACE OFF to end debug, ENTER to continue. +++
vUse the TRACE ? instruction as input
The question mark prefix before a TRACE option can end interactive debug as well as beginning it. The
question mark reverses the previous setting (on or off) for interactive debug. Thus you can use TRACE
?R within a program to start interactive debug, and provide input of another TRACE instruction with ?
before the option to end interactive debug but continue tracing with the specified option.
vUse TRACE with no options as input. If you specify TRACE with no options in the input stream, this turns
off interactive debug but continues tracing with TRACE Normal in effect. (TRACE Normal traces only
failing commands after execution.)
vLet the program run until it ends. Interactive debug automatically ends when the program that started
tracing ends. You can end the program prematurely using as input an EXIT instruction. The EXIT
instruction ends both the program and interactive debug.
Saving Interactive TRACE Output
REXX/CICS provides the ability to route trace output to a file. The REXX command SET TERMOUT routes
linemode output (such as SAY and TRACE output) to a file instead of, or in addition to, the current
terminal device.
Diagnosing Problems within a Program
Chapter 9. Diagnosing Problems within a program 87
88 CICS TS for VSE/ESA: REXX Guide
Chapter 10. Programming Style and Techniques
The method you use for constructing your programs is just as important as the language you use to write
them.
Consider the Data
When you are faced with the task of writing a program, the first thing to consider is the data you are
required to process. Make a list of the input data—what are the items and what are the possible values of
each? If the items have a kind of structure or pattern, draw a diagram to illustrate it. Then do the same for
the output data. Study your two diagrams and try to see if they fit together. If they do, you are well on the
way to designing your program.
Next, write the specification that the user will use. This might be a written specification, a HELP file or
both.
Last of all, write your program.
Here is a little example:
You are required to write an interactive program that invites the user to play “Heads or tails”. The game
can be played as long as the user likes. To end the game the user should reply Quit in answer to the
question “Heads or tails?” The program is arranged so that the computer always wins.
Think about how you would write this program.
The computer starts off with:
Let’s play a game! Type "Heads", "Tails",
or "Quit"
and press ENTER.
This means that there are four possible inputs:
vHEADS
vTAILS
vQUIT
vNone of these three.
And so the corresponding outputs should be:
vSorry. It was TAILS. Hard luck!
vSorry. It was HEADS. Hard luck!
vThat's not a valid answer. Try again!
And this sequence must be repeated indefinitely, ending with the return to CICS.
Now that you understand the specification, the input data and the output data, you are ready to write the
program.
If you had started off by writing down some instructions without considering the data, it would have taken
you longer.
Test Yourself...
Write the program. If you are careful, it should run the first time!
© Copyright IBM Corp. 1992, 2010 89
Answer:
Happy Hour
Here is a chance to have some fun.
This is a very simple arcade game. Type it in and play it with your friends. Later in this chapter, you may
want to improve it.
/* CON EXEC */
/* Tossing a coin. The machine is lucky, not the user */
do forever
say "Let’s play a game! Type ’Heads’, ’Tails’",
"or ’Quit’ and press ENTER."
pull answer
select
when answer = "HEADS"
then say "Sorry! It was TAILS. Hard luck!"
when answer = "TAILS"
then say "Sorry! It was HEADS. Hard luck!"
when answer = "QUIT"
then exit
otherwise
say "That’s not a valid answer. Try again!"
end
say
end
Programming Style and Techniques
90 CICS TS for VSE/ESA: REXX Guide
/* CATMOUSE EXEC */
/* The user says where the mouse is to go. But where */
/* will the cat jump? */
say "This is the mouse ----------> @"
say "These are the cat’s paws ---> ( )"
say "This is the mousehole ------> O"
say "This is a wall -------------> |"
say
say "You are the mouse. You win if you reach",
"the mousehole. You cannot go past"
say "the cat. Wait for him to jump over you.",
"If you bump into him you’re caught!"
say
say "The cat always jumps towards you, but he’s not",
"very good at judging distances."
say "If either player hits the wall he misses a turn."
say
say "Enter a number between 0 and 2 to say how far to",
"the right you want to run."
say "Be careful, if you enter a number greater than 2 then",
"the mouse will freeze and the cat will move!"
say
/*------------------------------------------------------*/
/* Parameters that can be changed to make a different */
/* game */
/*------------------------------------------------------*/
len = 14 /* length of corridor */
hole = 14 /* position of hole */
spring = 5 /* maximum distance cat can jump */
mouse = 1 /* mouse starts on left */
cat = len /* cat starts on right */
/*------------------------------------------------------*/
/* Main program */
/*------------------------------------------------------*/
do forever
call display
/*---------------------------------------------------*/
/* Mouse’s turn */
/*---------------------------------------------------*/
pull move
if datatype(move,whole) & move >= 0 & move <= 2
then select
when mouse + move > len then nop /* hits wall */
when cat > mouse,
& mouse + move >= cat /* hits cat */
/* continued ... */
Figure 45. CATMOUSE EXEC 1/2
Programming Style and Techniques
Chapter 10. Programming Style and Techniques 91
Good job! Now, take a while to put your new skills into action, or continue reading.
Designing a Program
Still thinking about method, which is just as important as language, let us take another look at
CATMOUSE EXEC.
The program is about a cat and a mouse and their positions in a corridor. At some stage their positions will
have to be pictured on the screen. The whole thing is too complicated to think about all at once; the first
step is to break it down into:
vMain program: calculate their positions
vDisplay subroutine: display their positions.
Now let us look at main program. The user (who plays the mouse) will want to see where everybody is
before making a move. The cat will not. The next step is to break the main program down further, into:
then mouse = cat
otherwise /* moves */
mouse = mouse + move
end
if mouse = hole then leave /* reaches hole */
if mouse = cat then leave /* hits cat */
/*---------------------------------------------------*/
/* Cat turn */
/*---------------------------------------------------*/
jump = random(1,spring)
if cat > mouse then do /* cat tries to jump left */
Temp = cat - jump
if Temp < 1 then nop /* hits wall */
else cat = Temp
end
else do /* cat tries to jump right */
if cat + jump > len then nop /* hits wall */
else cat = cat + jump
end
if cat = mouse then leave
end
/*------------------------------------------------------*/
/* Conclusion */
/*------------------------------------------------------*/
call display
if cat = mouse then say "Cat wins"
else say "Mouse wins"
exit
/*------------------------------------------------------*/
/* Subroutine to display the state of play */
/* */
/* Input: CAT and MOUSE */
/* */
/* Design note: each position in the corridor occupies */
/* three character positions on the screen. */
/*------------------------------------------------------*/
corridor = copies(" ",3*len) /* corridor */
corridor = overlay("O",corridor,3*hole-1) /* hole */
if mouse ¬= len /* mouse in hole? */
then corridor = overlay("@",corridor,3*mouse-1)/* mouse */
corridor = overlay("(",corridor,3*cat-2) /* cat */
corridor = overlay(")",corridor,3*cat)
say " |"corridor"|"
return
Figure 46. CATMOUSE EXEC 2/2
Programming Style and Techniques
92 CICS TS for VSE/ESA: REXX Guide
Do forever
call Display
Mouse’s move
Cat’s move
end
Conclusion
Methods for Designing Loops
The method for designing loops is to ask two questions:
vWill it always end?
vWhenever it terminates, will the data meet the conditions required?
Well, the loop terminates (and the game ends) when:
1. The mouse runs to the hole.
2. The mouse runs into the cat.
3. The cat catches the mouse.
The Conclusion
At the end of the program, the user must be told what happened.
call display
say who won
Programming Style and Techniques
Chapter 10. Programming Style and Techniques 93
What Do We Have So Far?
Putting all this together, we have:
The method that we have just discussed is sometimes called stepwise refinement. You start with a
specification (which may be incomplete). Then you divide the proposed program into routines, such that
each routine will be easier to code than the program as a whole. Then you repeat the process for each of
these routines until you reach routines that you are sure you can code correctly at the first attempt.
While you are doing this, keep asking yourself two questions:
vWhat data does this routine handle?
vIs the specification complete?
Stepwise Refinement: An Example
Granny is going to knit you a warm woolen garment to wear when you go sailing. This is what she might
do.
1. Knit front
2. Knit back
3. Knit left arm
4. Knit right arm
5. Sew pieces together.
Each of these jobs is simpler to describe than the job of knitting a pullover. In computer jargon, breaking a
job down into simpler jobs is called stepwise refinement.
/*------------------------------------------------------*/
/* Main program */
/*------------------------------------------------------*/
do forever
call display
/*---------------------------------------------------*/
/* Mouse’s turn */
/*---------------------------------------------------*/
...
if mouse = hole then leave /* reaches hole */
if mouse = cat then leave /* hits cat */
/*---------------------------------------------------*/
/* Cat’s turn */
/*---------------------------------------------------*/
...
if cat = mouse then leave
end
/*------------------------------------------------------*/
/* Conclusion */
/*------------------------------------------------------*/
call display
if cat = mouse then say "Cat wins"
else say "Mouse wins"
exit
/*------------------------------------------------------*/
/* Subroutine to display the state of play */
/* */
/* Input: CAT and MOUSE */
/* */
/*------------------------------------------------------*/
display:
...
Programming Style and Techniques
94 CICS TS for VSE/ESA: REXX Guide
At this stage, look at the specification again. A sailor might need to put on the pullover in the dark, quickly,
without worrying about the front or back. Therefore, the front should be the same as the back; and the two
sleeves should also be the same. This could be programmed:
do 2
CALL Knit_body_panel
end
do 2
CALL Knit_sleeve
end
CALL sew_pieces_together
In programming, the best method is to go on refining your program, working from the top, until you get
down to something that is easy to code.
Top down is the best approach.
Reconsider the Data
When you are refining your program, your objective is to make each piece simpler. This almost certainly
means:
vSimpler input data for each segment or routine
vSimpler output data for each segment or routine
vSimpler processing
vAnd, therefore, simpler code.
If your pieces really are simpler, they will probably have simpler names, too. For instance:
vKnit cuff
rather than
vMake ribbing for cuffs and waistband.
Correcting Your Program
If you cannot understand why your program is giving wrong results, you can:
vModify your program so that it tells you what it is doing
vUse some of the REXX interactive trace facilities (See “Interactive Debugging of Programs” on page
411).
You will gradually learn which of these techniques suits you better.
Modifying Your Program
You can put extra instructions into your program, such as:
...
say "Checkpoint A. x =" x
...
say "End of first routine"
...
Tracing Your Program
Or you can use the TRACE instruction, described on page 166.
vTo find out where your program is going, use TRACE Labels. The example shows a program and the
trace it gives on the screen.
Programming Style and Techniques
Chapter 10. Programming Style and Techniques 95
This gives the trace:
rotate
6 *-* wheel:
8 *-* cog:
10 *-* true:
8 *-* cog:
10 *-* true:
8 *-* cog:
10 *-* true:
6 *-* wheel:
8 *-* cog:
13 *-* false:
8 *-* cog:
13 *-* false:
8 *-* cog:
13 *-* false:
17 *-* done:
vTo see how the language processor is computing expressions, use TRACE Intermediates.
vTo find out whether you are passing the right data to a command or subroutine, use TRACE Results.
vTo make sure that you get to see nonzero return codes from commands, use TRACE Errors.
Coding Style
The only sure way of finding out whether a program is correct is to read it. Therefore, programs must be
easy to read. Naturally, easy to read means different things to different programmers. All we can do here is
to give examples of different styles, and leave you to choose the style you prefer.
A very good way to get your program checked is to ask a fellow worker to read it. Be sure to choose a
coding style that your fellow workers find easy to read.
Most people would find the following program fragment difficult to read.
/* ROTATE EXEC */
/* Example: two iterations of wheel, six iterations */
/* of cog. On the first three iterations, "x < 2" */
/* is true. On the next three, it is false. */
trace L
dox=1to2
wheel:
do 3
cog: ifx<2then do
true: end
else do
false:end
end
end
done:
Figure 47. ROTATE EXEC
Programming Style and Techniques
96 CICS TS for VSE/ESA: REXX Guide
This next example is easier to read. It is divided into segments, each with its own heading. The comments
on the right are sometimes called remarks. They can help the reader get a general idea of what is going
on.
/********************************************************/
/* SAMPLE #1: A portion of CATMOUSE EXEC */
/* not divided into segments and written with no */
/* indentation, and no comments. This style is not */
/* recommended. */
/********************************************************/
do forever
call display
pull move
if datatype(move,whole) & move >= 0 & move <=2
then select
when mouse+move > len then nop
when cat > mouse,
& mouse+move >= cat,
then mouse = cat
otherwise
mouse = mouse + move
end
if mouse = hole then leave
if mouse = cat then leave
jump = random(1,spring)
if cat > mouse then do
if cat-jump < 1 then nop
else cat = cat-jump
end
else do
if cat+jump > len then nop
else cat = cat+jump
end
if cat = mouse then leave
end
call display
if cat = mouse then say "Cat wins"
else say "Mouse wins"
exit
Programming Style and Techniques
Chapter 10. Programming Style and Techniques 97
This next example has additional features that are popular with some programmers. Keywords written in
uppercase and a different indentation style highlight the structure of the code; the abundant comments
recall the detail of the specification.
/********************************************************/
/* SAMPLE #2: A portion of CATMOUSE EXEC */
/* divided into segments and written with ’some’ */
/* indentation and ’some’ comments. */
/********************************************************/
/********************************************************/
/* Main program */
/********************************************************/
do forever
call display
/*****************************************************/
/* Mouse’s turn */
/*****************************************************/
pull move
if datatype(move,whole) & move >= 0 & move <=2
then select
when mouse+move > len then nop /* hits wall */
when cat > mouse,
& mouse + move >= cat, /* hits cat */
then mouse = cat
otherwise /* moves */
mouse = mouse + move
end
if mouse = hole then leave /* reaches hole */
if mouse = cat then leave /* hits cat */
/******************************************************/
/* Cat’s turn */
/******************************************************/
jump = random(1,spring)
if cat > mouse then do /* cat tries to jump left */
if cat - jump < 1 then nop /* hits wall */
else cat = cat - jump
end
else do /* cat tries to jump right */
if cat + jump > len then nop /* hits wall */
else cat = cat + jump
end
if cat = mouse then leave
end
/********************************************************/
/* Conclusion */
/********************************************************/
call display
if cat = mouse then say "Cat wins"
else say "Mouse wins"
exit
Programming Style and Techniques
98 CICS TS for VSE/ESA: REXX Guide
Congratulations! Now you know the best ways to program your REXX execs. Have fun writing programs
that will make your life easier!
/********************************************************/
/* SAMPLE #3: A portion of CATMOUSE EXEC */
/* divided into segments and written with ’more’ */
/* indentation and ’more’ comments. */
/* Note commands in uppercase (to highlight logic) */
/********************************************************/
/********************************************************/
/* Main program */
/********************************************************/
DO FOREVER
CALL display
/**********************************/
/* Mouse’s turn */
/**********************************/
PULL move
IF datatype(move,whole) & move >= 0 & move <=2
THEN SELECT
WHEN mouse+move > len /* mouse hits wall */
THEN nop /* and loses turn */
WHEN cat > mouse,
& mouse+move >= cat, /* mouse hits cat */
THEN mouse = cat /* and loses game */
OTHERWISE mouse = mouse + move /* mouse ... */
END /* moves to new location */
IF mouse = hole THEN LEAVE /* mouse is home safely */
IF mouse = cat THEN LEAVE /* mouse hits cat (ouch) */
/**********************************/
/* Cat’s turn */
/**********************************/
jump = RANDOM(1,spring) /* determine cat’s move */
IF cat > mouse /* cat must jump left */
THEN DOIF cat-jump < 1 /* cat hits wall */
THEN nop /* misses turn */
ELSE cat = cat-jump /* cat jumps left */
END
ELSE DO /* cat must jump right */
IF cat+jump > len /* cat hits wall */
THEN nop /* misses turn */
ELSE cat = cat+jump /* cat jumps right */
END
IF cat = mouse THEN LEAVE /* cat catches mouse */
END
/********************************************************/
/* Conclusion */
/********************************************************/
CALL display /* on final display */
IF cat = mouse /* who won? */
THEN say "Cat wins" /* ... the cat */
ELSE say "Mouse wins" /* ... the mouse */
EXIT
Programming Style and Techniques
Chapter 10. Programming Style and Techniques 99
100 CICS TS for VSE/ESA: REXX Guide
Part 2. Reference
© Copyright IBM Corp. 1992, 2010 101
102 CICS TS for VSE/ESA: REXX Guide
Chapter 11. Introduction
This introductory section:
vIdentifies the reference's purpose and audience
vExplains how to use the reference
vGives an overview of product features
vExplains how to read a syntax diagram.
Who Should Read This Reference
This reference describes the CICS Transaction Server for VSE/ESA REXX Guide and Reference
Interpreter (hereafter referred to as the interpreter or language processor) and the REstructured eXtended
eXecutor (called REXX) language. This reference is intended for experienced programmers, particularly
those who have used a block-structured, high-level language (for example, PL/I, Algol, or Pascal).
Descriptions include the use and syntax of the language and how the language processor “interprets” the
language while a program is running under the REXX/CICS interpreter. The reference also describes:
vProgramming services that let you interface with REXX and the language processor.
vCustomizing 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 Reference
This part of the book is a reference rather than a tutorial. It assumes you are already familiar with REXX
programming concepts. The material in this reference is arranged in chapters:
vChapter 11, “Introduction”
vChapter 12, “REXX General Concepts”
vChapter 13, “Keyword Instructions” (in alphabetic order)
vChapter 14, “Functions” (in alphabetic order)
vChapter 15, “Parsing” (a method of dividing character strings, such as commands)
vChapter 16, “Numbers and Arithmetic”
vChapter 17, “Conditions and Condition Traps”
vChapter 18, “REXX/CICS Text Editor”
vChapter 19, “REXX/CICS File System”
vChapter 20, “REXX/CICS List System”
vChapter 21, “REXX/CICS Command Definition”
vChapter 22, “REXX/CICS DB2 Interface”
vChapter 23, “REXX/CICS High-level Client/Server Support”
vChapter 24, “REXX/CICS Panel Facility”
vChapter 25, “REXX/CICS Commands”
There are several appendixes covering:
vAppendix A, “Error Numbers and Messages”
vAppendix B, “Return Codes”
vAppendix C, “Double-Byte Character Set (DBCS) Support”
vAppendix D, “Reserved Keywords and Special Variables”
vAppendix E, “Debug Aids”
vAppendix F, “REXX/CICS Business Value Discussion”
vAppendix G, “System Definition/Customization/Administration”
vAppendix H, “Security”
vAppendix I, “Performance Considerations”
vAppendix J, “Basic Mapping Support Example”
© Copyright IBM Corp. 1992, 2010 103
Overview of Product Features
The following list is the product features of REXX/CICS described in this section.
vSAA Level 2 REXX Language Support Under REXX/CICS
vSupport for the Interpretive Execution of REXX Execs
vCICS-Based Text Editor for REXX Execs and Data
vVSAM-Based File System for REXX Execs and Data
vDynamic Support for EXEC CICS Commands
vREXX Interface to CEDA and CEMT Transaction Programs
vHigh-level Client/Server Support
vSupport for Commands Written in REXX
vCommand Definition of REXX Commands
vSupport for System and User Profile Execs
vShared Execs in Virtual Storage
vSQL Interface.
SAA Level 2 REXX Language Support Under REXX/CICS
REXX/CICS is currently at REXX language level 3.48 and provides all Systems Application Architecture*
(SAA) REXX Level 2 capability (as described in the SAA Common Programming Interface REXX Level 2
Reference, SC24-5549) except for stream I/O and REXX language processor exits.
Note: The POWER HOST environment is not implemented in REXX/CICS.
Support for the Interpretive Execution of REXX Execs
Interpretive execution of REXX execs provides the ability to create and run REXX execs without first
compiling them. The use of the interpreter provides a very productive development, customization,
prototyping, and command list (CLIST) processing environment. This is because it provides a fast
development cycle, source level interactive debug, and a native CICS-based development environment, in
one integrated package.
Note: REXX execs can freely invoke CICS programs and transactions written in any CICS supported
language.
CICS-Based Text Editor for REXX Execs and Data
A native CICS text editor, similar to the VM/CMS XEDIT editor, is being provided as part of REXX/CICS,
so execs (and other data) can be created and modified directly under CICS. Edit support is provided for
files residing in the provided VSAM-based REXX file system (RFS), and for files existing in members in
the VSE Librarian sublibraries.
VSAM-Based File System for REXX Execs and Data
REXX/CICS includes the REXX File System (RFS), a high-level file system that is hierarchically structured
and is similar to the Operating System/2* (OS/2*), Advanced Interactive Executive* (AIX*), and the VM
Shared File systems. The RFS automatically provides each REXX user with a file system in which to store
execs and data. There is a file list utility to facilitate working with this file system, the text editor supports
editing members of this file system, and execs to be run are loaded from this file system. This file system
is VSAM based for performance, security, and portability reasons.
VSE Librarian Sublibraries
These can be used as an alternative to the RFS for REXX execs. A REXX exec in a VSE librarian
sublibrary must have have a member type of .PROC.
Introduction
104 CICS TS for VSE/ESA: REXX Guide
Dynamic Support for EXEC CICS Commands
Support for most EXEC CICS API commands is included in REXX/CICS. This is a dynamic interface (no
EXEC CICS command translation pre-processing step is needed). This support is provided through the
addition of an ADDRESS CICS command environment.
REXX Interface to CEDA and CEMT Transaction Programs
This allows CEDA and CEMT commands to be easily issued from REXX execs, with any subsequent
output placed into a REXX variable, instead of being displayed at the terminal. This facilitates the
automation of many CICS administration and operation activities, and is an excellent programmer aid.
High-level Client/Server Support
REXX/CICS provides integrated client/server support to REXX execs by providing facilities to allow REXX
execs to act as clients (which make requests to REXX/CICS servers) and by providing facilities to allow
REXX execs to act as servers (with the ability to wait for and process requests from REXX/CICS clients).
REXX/CICS facilities are provided which allow REXX/CICS servers to wait on requests from clients
(WAITREQ), and to retrieve (C2S) and set (S2C) the contents of client REXX variables.
Note: Servers do not execute as nested execs of clients, but rather execute as parallel entities.
Servers use Automatic Server Initiation (ASI) to start automatically when they receive their first request.
Support for Commands Written in REXX
REXX/CICS supports the ability for users to write new REXX/CICS commands in REXX. These commands
do not function as nested REXX execs, and unlike nested REXX execs have the ability to get and set the
values of REXX variables in the user exec that issued the command. Therefore, commands written in
REXX can have similar capabilities as commands written in Assembler or other languages. Also,
commands can be quickly written in REXX to speed systems development (in a building block structure),
and then can selectively be rewritten in Assembler (or any other CICS supported language) at a later date,
if performance requirements dictate.
Command Definition of REXX Commands
REXX/CICS includes as one of its basic facilities, the ability for systems administrators and users to easily
and dynamically define new REXX commands, either on a system-wide or user-by-user basis. One of the
greatest strengths of REXX is its ability to interface cleanly with other products, applications, and system
services. The goal for providing a command definition facility for new or existing commands is to facilitate
the rapid and consistent high-level integration of various products and services together through the use of
REXX. REXX command definition is accomplished with the REXX/CICS DEFCMD and DEFSCMD
commands.
Support for System and User Profile Execs
To facilitate REXX/CICS system and user environment tailoring, REXX/CICS attempts to execute
CICSTART, CICSPROF, and user PROFILE execs, if they exist. CICSTART is the system profile exec
(STARTUP profile) and it is issued before the first user exec is run after CICS system restart. CICSPROF
is the system user profile exec and it is issued when a user enters REXX/CICS for the first time since the
CICS system restart. CICSPROF also invokes the user PROFILE.
Shared Execs in Virtual Storage
REXX/CICS supports shared copies of REXX execs residing in virtual storage. Shared execs improve the
interactive response time of REXX applications, and sharing reduces the total virtual storage requirement.
Execs can be pre-loaded by using the EXECLOAD command. Common system-wide execs are good
candidates for pre-loading through the placement of EXECLOAD commands in the CICSTART exec.
Introduction
Chapter 11. Introduction 105
SQL Interface
REXX programs may contain SQL statements. These statements are interpreted and executed
dynamically. The results of the SQL statements are placed into REXX variables for use within the REXX
program.
Programming Considerations
To embed SQL statements withn a REXX exec, the host command environment must be changed, The
ADDRESS instruction, followed by the name of the environment, is used to change the host command
environment.
The REXX/CICS command envlironment that supports SQL statements is EXECSQL.
Embedding SQL statments
You can pass the following SQL statements directly to the EXECSQL command environment:
ALTER
CREATE
COMMENT ON
DELETE
EXPLAIN
INSERT
GRANT
INSERT
LABEL ON
LOCK
REVOKE
SELECT
UPDATE
You cannot use the following SQL statements:
BEGIN DECLARE SECTION
CLOSE
COMMIT
CONNECT
DECLARE CURSOR
DESCRIBE
END DECLARE SECTION
EXECUTE
EXECUTE IMMEDIATE
FETCH
INCLUDE
OPEN
PREPARE
ROLLBACK
WHENEVER
How to Read the Syntax Diagrams
Throughout this book, syntax is described using the structure defined below.
vRead the syntax diagrams from left to right, from top to bottom, following the path of the line.
The ─── symbol indicates the beginning of a statement.
The ─── symbol indicates that the statement syntax is continued on the next line.
The ─── symbol indicates that a statement is continued from the previous line.
The ─── symbol indicates the end of a statement.
Diagrams of syntactical units other than complete statements start with the ─── symbol and end with
the ─── symbol.
Introduction
106 CICS TS for VSE/ESA: REXX Guide
vRequired items appear on the horizontal line (the main path).
 STATEMENT required_item 
vOptional items appear below the main path.
 STATEMENT
optional_item

vIf you can choose from two or more items, they appear vertically, in a stack.
If you must choose one of the items, one item of the stack appears on the main path.
 STATEMENT required_choice1
required_choice2

If choosing is optional, the entire stack appears below the main path.
 STATEMENT
optional_choice1
optional_choice2

vIf one of the items is the default, it appears above the main path and the remaining choices are shown
below.
 STATEMENT
default_choice
optional_choice
optional_choice

vAn arrow returning to the left above the main line indicates an item that can be repeated.
 STATEMENT repeatable_item 
A repeat arrow above a stack indicates that you can repeat the items in the stack.
vA set of vertical bars around an item indicates that the item is a fragment, a part of the syntax diagram
that appears in greater detail below the main diagram.
 STATEMENT fragment 
fragment:
expansion_provides_greater_detail
vKeywords appear in uppercase (for example, PARM1). They must be spelled exactly as shown but can be
specified in any case. Variables appear in all lowercase letters (for example, parmx). They represent
user-supplied names or values.
vIf punctuation marks, parentheses, arithmetic operators, or such symbols are shown, you must enter
them as part of the syntax.
Introduction
Chapter 11. Introduction 107
Introduction
108 CICS TS for VSE/ESA: REXX Guide
Chapter 12. REXX General Concepts
The REstructured eXtended eXecutor (REXX) language is particularly suitable for:
vCommand procedures
vApplication front ends
vUser-defined macros (such as editor subcommands)
vUser-defined XEDIT subcommands
vPrototyping
vPersonal computing.
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 16MB. 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 Yand Zcan be the names of variables or can be constant symbols), for constructing arrays and for
other purposes.
REXX programs can reside in REXX File System directories or in VSE sublibraries. REXX programs
usually have a file type of EXEC or, if they are in a VSE Librarian sublibrary, a member type of PROC.
A language processor (interpreter) runs REXX programs. That is, the program is processed line-by-line
and word-by-word, without first being translated to another form (compiled). The advantage of this to the
user is that if the program fails with a syntax error of some kind, the point of error is clearly indicated;
usually, it will not take long to understand the difficulty and make a correction.
Structure and General Syntax
REXX programs are recommended to start with a comment. REXX/CICS does not require this. However,
for portability reasons, you are recommended to start each REXX program with a comment that begins on
the first line and includes the word REXX. The example in Figure 48 illustrates this. The program starts with
a comment and the characters “REXX” are in the first line (line 1).
A REXX program is built from a series of clauses that are composed of:
/* REXX program */
...
...
...
EXIT
Figure 48. Example of Using the REXX Program Identifier
© Copyright IBM Corp. 1992, 2010 109
vZero or more blanks (which are ignored)
vA sequence of tokens (see section “Tokens” on page 111)
vZero or more blanks (again ignored)
vA semicolon (;) delimiter that may 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 114) are also removed.
Implementation maximum: The length of a clause cannot exceed 16K.
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 encodings 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 encodings for each character in a set. You should be aware that:
vSome code pages do not contain all characters that REXX defines as valid (for example, ¬, the logical
NOT character).
vSome characters that REXX defines as valid have different encodings in different code pages (for
example, !, the exclamation point).
For information about Double-Byte Character Set characters, see Appendix C, “Double-Byte Character Set
(DBCS) Support,” on page 395.
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 parse pull input
02 if substr(input,1,5) = ’/*123’
03 then call process
04 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 (*/).
REXX General Concepts
110 CICS TS for VSE/ESA: REXX Guide
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 C, “Double-Byte Character Set
(DBCS) Support,” on page 395 and the OPTIONS instruction on page 151.
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’
"Don’t Panic!"
’You shouldn’’t’ /* Same as "You shouldn’t" */
’’ /* 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 Xor x, it is considered to be a hexadecimal string. If followed
immediately by the symbol Bor 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. See the note
on page 109 for more information.
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 (0–9,a–f,A–F), 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 Xor x. (Neither xnor Xcan be part of a longer symbol.) The blanks, which may 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:
’ABCD’x
"1d ec f8"X
"1 d8"x
REXX General Concepts
Chapter 12. REXX General Concepts 111
Note: A hexadecimal string is not a representation of a number. Rather, it is an escape
mechanism that lets a user describe a character in 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.
Also note that in Assembler language hexadecimal numbers are represented with the X in front of
the number. REXX only accepts hexadecimal numbers as was described in the previous note. In
this book you will see hexadecimal numbers represented in both ways, but when you are coding a
hexadecimal string in REXX, place the X after the number.
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 (0or 1) in groups of 8 (bytes) or 4 (nibbles). The first group
may 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 bor B. (Neither bnor Bcan be part of a longer symbol.)
The blanks, which may 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:
’11110000’b /* == ’f0’x */
"101 1101"b /* == ’5d’x */
’1’b /* == ’00000001’b and ’01’x */
’10000 10101010’b /* == ’0001 0000 1010 1010’b */
’’b /* == ’’ */
Implementation maximum: The packed length of a hexadecimal string (the string with blanks
removed) cannot exceed 250 bytes.
Symbols:
Symbols are groups of characters, selected from the:
vEnglish alphabetic characters (A–Zand a–z1)
vNumeric characters (0–9)
vCharacters .!
2?and _(underscore).
vDouble-Byte Character Set (DBCS) characters (X'41'–X'FE')—ETMODE must be in effect for
these characters to be valid in symbols.
Any lowercase alphabetic character in a symbol is translated to uppercase (that is, lowercase a–z
to uppercase A–Z) before use.
These are valid symbols:
Fred
Albert.Hall
WHERE?
<.H.E.L.L.O> /* This is DBCS */
For information about Double-Byte Character Set (DBCS) characters, see Appendix C,
“Double-Byte Character Set (DBCS) Support,” on page 395.
1. Note that some code pages do not include lowercase English characters a–z.
2. The encoding of the exclamation point character depends on the code page in use.
REXX General Concepts
112 CICS TS for VSE/ESA: REXX Guide
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 a–zto uppercase A–Z). 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 (0–9) or a period, and it may end with the sequence Eor 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. See the note on page 109 for
more information.
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 217-224 for a full definition of numbers.
Numbers can have leading blanks (before and after the sign, if any) and can have trailing blanks.
Blanks may not be embedded among the digits of a number or in the exponential part. Note that a
symbol (see preceding) or a literal string may 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 ’
’0E000’
You can specify numbers with or without quotation marks around them. Note that the sequence
−17.9 (without quotation marks) in an expression is not simply a number. It is a minus operator
(which may be prefix minus if no term is to the left of it) followed by a positive number. The result
of the operation is a number.
Awhole 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).
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 115). 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:
REXX General Concepts
Chapter 12. REXX General Concepts 113
345>=123
345 >=123
345 >= 123
345 > = 123
Some of these characters may not be available in all character sets, and, if this is the case,
appropriate translations may 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 tokens—a literal string (’REPEAT’), a blank operator, a symbol (A, which may have
a value), an operator (+), a second symbol (3, which is a number and a symbol), and the clause delimiter
(;). The blanks between the Aand the +and between the +and the 3are removed. However, one of the
blanks between the ’REPEAT’ and the Aremains 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 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:
vThe line ends in the middle of a string.
vThe line ends in the middle of a comment. The clause continues on to the next line.
vThe 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.
Note: 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.
REXX General Concepts
114 CICS TS for VSE/ESA: REXX Guide
Continuations
One way to continue a clause onto the next line is to use 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.
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.
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:
vLiteral Strings (delimited by quotation marks), which are constants
vSymbols (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.
vFunction calls (see page 171), 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 section “Parentheses and Operator Precedence” on page 118). Expressions
are wholly evaluated, unless an error occurs during evaluation.
All data is in the form of “typeless” character strings (typeless because it is not—as in some other
languages—of 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) may be the null string (a string of length 0). Note that REXX imposes no restriction
on the maximum length of results. However, there is a 16MB limitation on the amount of a single storage
request available to the language processor. See the note on page 109 for more information.
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
may 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
REXX General Concepts
Chapter 12. REXX General Concepts 115
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:
vConcatenation
vArithmetic
vComparison
vLogical
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 may occur with or without an intervening blank. The
concatenation operators are:
(blank)
Concatenate terms with one blank in between
|| Concatenate without an intervening blank
(abuttal)
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 c2’x’CDE’
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 113) using the arithmetic operators:
+Add
−Subtract
*Multiply
/Divide
%Integer divide (divide and return the integer part of the result)
// Remainder (divide and return the remainder—not modulo, because the result may be negative)
** Power (raise a number to a whole-number power)
REXX General Concepts
116 CICS TS for VSE/ESA: REXX Guide
Prefix −
Same as the subtraction: 0 - number
Prefix +
Same as the addition: 0 + number.
See Chapter 16, “Numbers and Arithmetic,” on page 217 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 1if the result of the comparison is true,
or 0otherwise.
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 forth—see section “Numeric Comparisons” on page 222) 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 0–9are higher than all 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
REXX General Concepts
Chapter 12. REXX General Concepts 117
>>= Strictly greater than or equal to
\<<, ¬<<
Strictly NOT less than
<<= Strictly less than or equal to
\>>, ¬>>
Strictly NOT greater than
Note: Throughout the language, the not character, ¬, is synonymous with the backslash (\). You can use
the two characters interchangeably, according to 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 0or 1are not allowed) and return 0or 1as appropriate:
&AND
Returns 1if both terms are true.
|Inclusive OR
Returns 1if either term is true.
&& Exclusive OR
Returns 1if either (but not both) is true.
Prefix \,¬
Logical NOT
Negates; 1becomes 0, and 0becomes 1.
Parentheses and Operator Precedence
Expression evaluation is from left to right; parentheses and operator precedence modify this:
vWhen parentheses are encountered (other than those that identify function calls) the entire
subexpression between the parentheses is evaluated immediately when the term is required.
vWhen 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)
REXX General Concepts
118 CICS TS for VSE/ESA: REXX Guide
=>< (comparison operators)
== >> <<
\= ¬=
>< <>
\> ¬>
\< ¬<
\== ¬==
\>> ¬>>
\<< ¬<<
>= >>=
<= <<=
/= /==
&(and)
|&& (or, exclusive or)
Examples:
Suppose the symbol Ais a variable whose value is 3,DAY is a variable whose value is Monday, and other
variables are uninitialized. Then:
A+5 -> ’8’
A-4*2 -> ’-5’
A/2 -> ’1.5’
0.5**2 -> ’0.25’
(A+1)>7 -> ’0’ /* that is, False */
’ ’=’’ -> ’1’ /* that is, True */
’ ’==’’ -> ’0’ /* that is, False */
’ ’¬==’’ -> ’1’ /* that is, True */
(A+1)*3=12 -> ’1’ /* that is, True */
’077’>’11’ -> ’1’ /* that is, True */
’077’ >> ’11’ -> ’0’ /* that is, False */
’abc’ >> ’ab’ -> ’1’ /* that is, True */
’abc’ << ’abd’ -> ’1’ /* that is, True */
’ab ’ << ’abd’ -> ’1’ /* that is, True */
Today is Day -> ’TODAY IS Monday’
’If it is’ day -> ’If it is Monday’
Substr(Day,2,3) -> ’ond’ /* Substr is a function */
’!’xxx’!’ -> ’!XXX!’
’000000’ >> ’0E0000’ -> ’1’ /* that is, 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:
vThe prefix minus operator always has a higher priority than the power operator.
vPower 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 */
REXX General Concepts
Chapter 12. REXX General Concepts 119
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).
Note: 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 may 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.
You can use DBCS characters. See Appendix C, “Double-Byte Character Set (DBCS) Support,” on page
395 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 section “Assignments and Symbols” on page 121.
Keyword Instructions
Akeyword 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.
DO instruction
instruction
instruction
END
Asubkeyword 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
Acommand 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.
REXX General Concepts
120 CICS TS for VSE/ESA: REXX Guide
Assignments and Symbols
Avariable 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 may 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 pool interface, 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. Currently, on VM if you omit expression, the variable is set to the
null string. However, it is recommended that you explicitly set a variable to the null string: symbol=’’.
Example:
/* Next line gives FRED the value "Frederic" */
Fred=’Frederic’
The symbol naming the variable cannot begin with a digit (0–9) 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 3the 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 a–zto uppercase A–Z).
However, if it is a compound symbol (described under section “Compound Symbols” on page 122), its
value is the derived name of the symbol.
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
Aconstant symbol starts with a digit (0–9) 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 /* Same as 12E5 */
3D
17E-3
Simple Symbols
Asimple symbol does not contain any periods and does not start with a digit (0–9).
REXX General Concepts
Chapter 12. REXX General Concepts 121
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? /* Same as WHATAGOODIDEA? */
?12
<.D.A.T.E>
Compound Symbols
Acompound 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.
The name begins with a stem (that part of the symbol up to and including the first period). This is followed
byatail, 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 A–Z,a–z,0–9, 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.
<.F.R.E.D>.<.A.B>
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).
REXX General Concepts
122 CICS TS for VSE/ESA: REXX Guide
Some examples follow in the form of a small extract from a REXX program:
a=3 /* assigns ’3’ to the variable A */
z=4 /* ’4’ to Z */
c=’Fred’ /* ’Fred’ to C */
a.z=’Fred’ /* ’Fred’ to A.4 */
a.fred=5 /* ’5’ to A.FRED */
a.c=’Bill’ /* ’Bill’ to A.Fred */
c.c=a.fred /* ’5’ to C.Fred */
y.a.z=’Annie’ /* ’Annie’ to Y.3.4 */
sayazca.aa.za.cc.aa.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.
Stems
Astem 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.
<.A.B>.
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 to the individual variable.
For example:
hole. = "empty"
hole.9 = "full"
say hole.1 hole.mouse hole.9
/* says "empty empty full" */
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
REXX General Concepts
Chapter 12. REXX General Concepts 123
Note: 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:
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 “Purpose” on page 142), and
PROCEDURE EXPOSE FRED. exposes all possible variables with that stem (see page “Purpose” on page 155).
Notes:
1. When the ARG, PARSE, or PULL instruction or the VALUE built-in function or the variable pool
interface 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 may consist purely of an
expression (see section “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 (=)isanassignment, 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 193) 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 variables—see page 225).
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 environment for
processing commands. An environment is selected by default on entry to a REXX program. 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 default environment for a REXX/CICS program is
REXXCICS.
Commands
To send a command to the currently addressed environment, use a clause of the form:
expression;
The expression is evaluated, resulting in a character string (which may be the null string), which is then
prepared as appropriate and submitted to the underlying system. Any part of the expression not to be
evaluated should be enclosed in quotation marks.
The environment then processes the command, which may 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
REXX General Concepts
124 CICS TS for VSE/ESA: REXX Guide
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 section “Special Variables” on page 228.
In addition to setting a return code, the underlying system may 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 17, “Conditions and Condition Traps,” on page 225). They may 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 default—see
page “Purpose” on page 166.
Here is an example of submitting a command to the default REXX/CICS command environment. The
sequence:
TSQ1 = ’TSQUEUE1’
"EXECIO * READ" TSQ1 "MYDATA."
results in the string EXECIO * READ TSQUEUE1 MYDATA. being submitted to REXX/CICS.
On return, the return code placed in RC has the value 0if the CICS temporary storage queue TSQUEUE1
was successfully read into MYDATA array. If TSQUEUE1 is empty the appropriate return code is placed in
RC.
Note: 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.
Example:
"EXECIO * READ" /* * does not mean "multiplied by" */
Basic Structure of REXX Running Under CICS
REXX/CICS support provides a main interface program named CICREXD which is used to load and issue
REXX execs within a CICS region. Each REXX exec runs under a separate CICS task. Any nested REXX
execs run under the CICS task of the parent exec.
REXX Exec Invocation
vExecs started from a terminal
CICS uses transaction identifiers associated with programs to determine which programs to execute.
REXX/CICS uses a table created by the REXX/CICS command, DEFTRNID, to associate CICS
transaction identifiers with specific REXX execs. The CICS transaction identifier associated with the
REXX/CICS supplied exec, CICRXTRY, is known as the default REXX/CICS transaction identifier. The
supplied default is REXX. If REXX is entered from a CICS screen alone, the CICRXTRY exec is started.
If other operands are specified, for example: REXX MYEXEC ABC, the exec MYEXEC is started and
ABC is passed to it as an argument. CICS transaction identifiers other than the REXX/CICS default
transaction identifier cause the associated exec to be started and any other operands are passed as an
argument to the exec. For example: EDIT TEST.EXEC causes the REXX/CICS editor exec, CICEDIT, to
start and TEST.EXEC, the argument, names the file to edit or create. All REXX/CICS transaction
identifiers must have CICS definitions which associate them with the REXX/CICS main module,
CICREXD.
vExecs started using a CICS START command
REXX General Concepts
Chapter 12. REXX General Concepts 125
REXX/CICS execs may be started using the CICS START command. The START command names the
CICS transaction identified to start and the table created by the REXX/CICS DEFTRNID command
names the exec to start. If the exec is CICRXTRY and CICS start data is present, the first operand
names the exec to start and any other operands are passed to the exec as an argument. If no start
data is present, then CICRXTRY is started. For execs other than CICRXTRY, start data is passed to the
exec as an argument. Usually, REXX/CICS execs have a terminal associated with them. However, if a
REXX/CICS exec does not have a terminal associated to the transaction, any terminal output is either
discarded or directed to a CICS temporary storage queue as specified by the REXX/CICS SET
TERMOUT command. An error is generated if terminal input is requested for a transaction for which no
terminal is associated.
vExecs started using a CICS LINK or XCTL command
The REXX/CICS interface program CICREXD may be invoked using the CICS LINK or XCTL command.
A COMMAREA must be passed to the interface program when invoked in this way. The COMMAREA
must contain operands that name the exec to start and an argument to be passed. The exec name is
expected as the first blank delimited token in the COMMAREA.
Note: A utility called REXXTRY (CICRXTRY exec) is provided with REXX/CICS that allows the interactive
execution of REXX instructions and REXX/CICS commands. To invoke this utility, enter the
REXX/CICS transaction identifier associated with CICRXTRY without any operands.
Where Execs Execute
REXX/CICS execs are executed as part of the CICS task that issues them, within the CICS region. The
REXX interpreter is fully reentrant and runs above the 16 megabyte line (AMODE=31, RMODE=ANY).
Locating and Loading Execs
The following rules are used to locate and load an exec into storage so it can be started:
1. Execs loaded into storage using EXECLOAD are searched and if the exec is found, the EXECLOADed
copy is used.
2. The user's current RFS directory, as defined by the REXX/CICS CD command, is searched. If found,
the exec is loaded and started.
3. The user's path, as defined by the REXX/CICS PATH command, is searched. If found, the exec is
loaded and started.
4. If the user is an authorized user, VSE Librarian sublibraries specified on the SETSYS AUTHCLIB
command are searched. If the exec is found, it is loaded and started.
5. VSE Librarian sublibraries specified on the SETSYS AUTHELIB command are searched. If the exec is
found, it is loaded and started.
6. Finally, members with a member type of PROC in sublibraries defined in the LIBDEF PROC search
chain for the CICS TS partition are searched.
Editing Execs
REXX execs can be edited using the supplied REXX/CICS editor. Also, if REXX/CICS execs reside in a
VSE Librarian member, they can be edited using other editors such as the librarian member edit
component of DITTO.
REXX File System
Execs can be stored as members in the VSAM-based REXX File System (RFS), provided with
REXX/CICS, or in VSE librarian members with a member type of PROC.
Note: If the file identifier you specified for invoking an exec does not include a file type extension, then
only RFS file identifiers with a file type of EXEC are searched when you attempt to locate and issue
the REXX exec. If the file identifier includes a file type extension, then only RFS files with a
matching file type are searched (when you attempt to locate and run the exec).
REXX General Concepts
126 CICS TS for VSE/ESA: REXX Guide
Control of Exec Execution Search Order
The CD and PATH commands define the search order of user REXX libraries when you attempt to load an
exec. After the current directory (set by the CD command) is searched, all directories specified with the
PATH command are searched, then VSE sublibraries specified on the SETSYS AUTHCLIB and SETSYS
AUTHELIB commands are searched, followed by VSE Librarian members with a member type of PROC in
the LIBDEF PROC search chain for the CICS partition.
Adding User Written Commands
An exec may be defined so it can be invoked as a REXX/CICS command. The DEFCMD command is
used to define REXX/CICS user commands. DEFCMD supports commands written in REXX as well as the
standard CICS supported languages. For more information on the DEFCMD command, see section
“DEFCMD” on page 332.
Support of Standard REXX Features
This section discusses the support of standard REXX features such as SAY and TRACE statements, PULL
and PARSE EXTERNAL statements, REXX stacking, and REXX functions.
SAY and TRACE Statements
The REXX SAY and TRACE terminal I/O output statements use CICS Terminal Control support to provide
simulated line-mode output. Also, the SET TERMOUT command can be used to route line-mode output
into a temporary storage queue.
PULL and PARSE EXTERNAL Statements
The REXX PULL and PARSE EXTERNAL terminal I/O input statements use CICS Terminal Control
support to provide simulated line-mode input.
Notes:
1. PULL (or PARSE PULL) first attempts to pull a line from the program stack and, only if it is empty,
issues a read to the terminal.
2. Attempting to perform terminal line-mode input from a REXX exec that is running as part of a
non-terminal attached transaction, is an error, which causes the exec to terminate with an error
message.
REXX Stack Support
Each user has a shared program stack between multiple generations of REXX execs. This single
automatic program stack is not named. If named program stacks are desired, use the RLS LPUSH,
LQUEUE, and LPULL commands.
REXX Function Support
REXX/CICS supports the standard SAA Level 2 built-in function set, with the following exceptions:
vStream I/O functions are not supported.
vThe USERID function returnsa1to8character CICS user ID if the user is signed on. If the CICS user
has not signed on and a default user has been specified for the CICS region (by the CICS Systems
Programmer specifying DFLTUSER in the CICS startup parameters) then that value is used.
Note: The default user shares REXX File System and REXX List System directories.
vThe STORAGE function, that allows a REXX user to display or modify the virtual storage of the CICS
region. This function can only be successfully invoked from an authorized exec or by an authorized
user.
REXX General Concepts
Chapter 12. REXX General Concepts 127
REXX Command Environment Support
REXX command environments that are currently available (to use with the REXX ADDRESS command)
are REXXCICS, CICS, EXECSQL, EDITSVR, FLSTSVR, RFS and RLS.
Adding REXX Host Command Environments
Support is provided for allowing new REXX/CICS commands and command environments to be
dynamically defined. New commands may be written in REXX or in any REXX/CICS supported language
(for example: Assembler, COBOL, C, PL/I). For more information on how commands and command
environments are defined to REXX/CICS, see Chapter 21, “REXX/CICS Command Definition,” on page
281.
Support of Standard CICS Features/Facilities
This section discusses the support of standard CICS features/facilities such as: CICS mapped I/O support,
dataset I/O services, interfaces to CICS facilities and services, issuing user applications from execs, REXX
interfaces to CICS temporary and transient storage queues, pseudo-conversational transaction support,
and DBCS support.
CICS Mapped I/O Support
Support for CICS basic mapping support (BMS) I/O is provided by the CICS SEND MAP, RECEIVE MAP,
and CONVERSE MAP commands and the REXX/CICS CONVTMAP and COPYS2R commands. See
Appendix J, “Basic Mapping Support Example,” on page 427.
Note: BMS maps must be predefined, using normal CICS procedures.
Dataset I/O Services
Standard CICS File I/O commands (EXEC CICS READ, WRITE, and so on) are supported. Also,
high-level I/O may be done from an exec to the VSAM-based REXX File System (RFS) using the provided
RFS command. In addition, standard VSE Librarian members may be used with the IMPORT and
EXPORT commands and the REXX/CICS editor.
Interfaces to CICS Facilities and Services
From within the ADDRESS CICS command environment, support is provided for most CICS commands
(as defined in the CICS Transaction Server for VSE/ESA Application Programming Reference. See
Chapter 25, “REXX/CICS Commands,” on page 319 for detailed information on the commands supported.
Issuing User Applications From Execs
REXX/CICS supports the EXEC CICS START, LINK, and XCTL commands to provide the ability to START
CICS transactions or invoke CICS programs from within a REXX exec.
REXX Interfaces to CICS Storage Queues
Command support exists for reading, writing, and deleting CICS temporary storage and transient data
queues from REXX/CICS.
Pseudo-conversational Transaction Support
CICS pseudo-conversational support for REXX execs is supported though the use of the CICS RETURN
TRANSID() command, by the REXX/CICS PSEUDO command (see section “PSEUDO” on page 362), and
the SETSYS PSEUDO command (see section “SETSYS” on page 371).
REXX General Concepts
128 CICS TS for VSE/ESA: REXX Guide
Interfaces to Other Programming Languages
REXX/CICS supports (by support for CICS LINK and CICS XCTL REXX/CICS commands) the ability to
invoke CICS programs written in any REXX/CICS supported language. It likewise provides the same
support for the programs used to implement new REXX commands, which are defined by using the
DEFCMD and DEFSCMD commands. Support is also provided to allow an EXEC CICS START to be
issued from REXX execs.
DBCS Support
The full range of DBCS functions and handling techniques that are included in SAA Level 2 REXX are
available to the REXX/CICS user.
Miscellaneous Features
vA TERMID command has been provided to return the four character terminal identifier of a CICS user.
vA retrieve PF key may be specified to retrieve the last input line entered using line-mode I/O while in the
REXXTRY interactive utility (CICRXTRY exec). Refer to the SET RETRIEVE command.
vThe SET TERMOUT command allows line-mode terminal output (from SAY or TRACE) to be directed to
a CICS temporary storage queue instead of, or in addition to, the terminal.
vThe PULL instruction sets the REXX variable PULLKEY, with the name of the AID key pressed if PULL
read data from the terminal.
vLine-mode output to the terminal causes MORE to appear in the lower right hand corner of the screen,
when the screen is full. Press Clear or Enter to proceed.
vLine-mode input from the terminal causes READ to appear in the lower right hand corner of the screen.
REXX General Concepts
Chapter 12. REXX General Concepts 129
REXX General Concepts
130 CICS TS for VSE/ESA: REXX Guide
Chapter 13. Keyword Instructions
Akeyword 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.
As explained in section “Keyword Instructions” on page 120, 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 (though this is generally not
recommended).
Certain other keywords, known as subkeywords, are reserved within the clauses of individual instructions.
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 409.
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 VALUE’ENVIR’||number
© Copyright IBM Corp. 1992, 2010 131
ADDRESS
Purpose
 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.
The concept of alternative subcommand environments is described in section “Issuing Commands from a
program” on page 82.
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 environment name is limited to
eight characters. 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 124.) Errors and failures in commands processed in this way are
trapped or traced as usual.
Example:
ADDRESS CICS "READQ TSQ QUEUE(’QUEUE1’) INTO(VAR1)" /* CICS */
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 cics
"READQ TSQ QUEUE(’QUEUE1’) INTO(VAR1)"
ADDRESS RFS
’COPY PROFILE.EXEC TEMP.EXEC’
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 */
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 “Purpose” on page 135) for more details.
ADDRESS
132 CICS TS for VSE/ESA: REXX Guide
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 175).
ADDRESS
Chapter 13. Keyword Instructions 133
ARG
Purpose
 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 the section on parsing (page 203).
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 a–z
to uppercase A–Z) before processing them. Use the PARSE ARG instruction if you do not want uppercase
translation.
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(’data X’,1,5) */
Fred: Arg string, num1, num2
/* Now: STRING contains ’DATA X’ */
/* NUM1 contains ’1’ */
/* NUM2 contains ’5’ */
Notes:
1. The ARG built-in function can also retrieve or check the argument strings to a REXX program or
internal routine, see page 175.
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 153 for details.
ARG
134 CICS TS for VSE/ESA: REXX Guide
CALL
Purpose
 CALL
,
name
expression
OFF ERROR
FAILURE
HALT
ON ERROR
FAILURE NAME trapname
HALT
; 
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 on condition traps is contained in
Chapter 17, “Conditions and Condition Traps,” on page 225.
To call a routine, a literal string or symbol that is taken as a constant, specify name. 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 built-in routine
A function (which may be called as a subroutine) that is defined as part of the REXX language.
An external routine
A function or subroutine that is neither built-in nor in the same program as the CALL instruction or
function call that calls it.
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 the name in the
literal string should also be in uppercase.
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, you get an error if you call it as a function (as previously
shown).
VM 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.
CALL
Chapter 13. Keyword Instructions 135
The CALL then causes a branch to the routine called name, using exactly the same mechanism as
function calls, see Chapter 14, “Functions,” on page 171. The search order is in the section on functions
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 was determined at the time of execution; this is known as a multi-way
call (see page 164). 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 174.)
External routines:
Users can write or use routines that are external to the language processor and the calling
program. External routines must be coded in REXX. 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 /* Calculate factorial by */
arg n /* recursive invocation. */
if n=0 then return 1
call factorial n-1
return result * n
During internal subroutine (and function) execution, all important pieces of information are automatically
saved and then restored upon return from the routine. These are:
CALL
136 CICS TS for VSE/ESA: REXX Guide
vThe 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.)
vTrace 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.
vNUMERIC settings: The DIGITS, FUZZ, and FORM of arithmetic operations (in section “NUMERIC” on
page 150) are saved and then restored on return. A subroutine can, therefore, set the precision, and so
forth, that it needs to use without affecting the caller.
vADDRESS settings: The current and previous destinations for commands (see section “ADDRESS” on
page 132) are saved and then restored on return.
vCondition 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.
vCondition information: This information describes the state and origin of the current trapped condition.
The CONDITION built-in function returns this information. See section “CONDITION” on page 178.
vElapsed-time clocks: A subroutine inherits the elapsed-time clock from its caller (see section “TIME” on
page 194), 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.
vOPTIONS settings: ETMODE and EXMODE are saved and then restored on return. For more
information, see section “OPTIONS” on page 151.
Implementation maximum: The total nesting of control structures, which includes internal routine calls, is
dependent upon available storage.
CALL
Chapter 13. Keyword Instructions 137
DO
Purpose
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:
vThe 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.
vThe exprw or expru options (if present) can be any expression that evaluates to 1or 0.
vThe TO, BY, and FOR phrases can be in any order, if used, and are evaluated in the order in
which they are written.
vThe 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).
vThe 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,orexprf. FOREVER is also reserved, but only if it immediately follows the
keyword DO and an equal sign does not follow it.
vThe 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.
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 Doa=a+2
Say ’Smile!’
End
 DO
repetitor conditional
;
instruction
END
name
; 
repetitor: name=expri
TO exprt BY exprb FOR exprf
FOREVER
exprr

conditional:
WHILE exprw
UNTIL expru
DO
138 CICS TS for VSE/ESA: REXX Guide
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 section “Conditional Phrases (WHILE and UNTIL)” on page 140).
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).
Note: For a discussion on conditional phrases, see section “Conditional Phrases (WHILE and UNTIL)” on
page 140.
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,acontrol variable that is assigned
an initial value (the result of expri, formatted as though 0had 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.
Example:
Do I=3 to -2 by -1 /* Displays: */
say i /* 3 */
end /* 2 */
/*1*/
/*0*/
/* -1 */
/* -2 */
The numbers do not have to be whole numbers:
Example:
I=0.3 /* Displays: */
Do Y=I to I+4 by 0.7 /* 0.3 */
say Y /* 1.0 */
end /* 1.7 */
/* 2.4 */
/* 3.1 */
/* 3.8 */
DO
Chapter 13. Keyword Instructions 139
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 Iwithin 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 time—when 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 */
Note: 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 0or 1), and the loop is ended if exprw evaluates to 0or
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 bottom—before 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" */
Note: Using the LEAVE or ITERATE instructions can also modify the execution of repetitive loops.
DO
140 CICS TS for VSE/ESA: REXX Guide
Evaluate exprr + 0
evaluate expri + 0
exprt + 0, exprb + 0,
exprf + 0 in order written
or
and
and
Assign start value to control
variable
Use TO value (expr) 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
Discontinue execution of DO
group if UNTIL condition is
met
Use FOR value (exprf) to test
for termination
Use WHILE expression (exprw)
to test for termination
Use BY expression (exprb) to
update control variable
Use UNTIL expression (expru)
to test for termination
Use count of iterations (exprr)
to test for termination
Execute instruction(s)
in the DO group
Figure 49. Concept of a DO Loop
DROP
Chapter 13. Keyword Instructions 141
DROP
Purpose
 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 section
“PROCEDURE” on page 155), 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. */
DROP
142 CICS TS for VSE/ESA: REXX Guide
EXIT
Purpose
 EXIT
expression
; 
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 “Purpose” on page 161) 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 error—either 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 underlying operating system. If the conversion fails, it is
deemed to be unsuccessful due to the underlying operating system 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).
EXIT
Chapter 13. Keyword Instructions 143
IF
Purpose
 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 0or 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?’
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.
IF
144 CICS TS for VSE/ESA: REXX Guide
INTERPRET
Purpose
 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" */
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:
kitty3 *-* 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"
INTERPRET
Chapter 13. Keyword Instructions 145
>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 196) 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.
INTERPRET
146 CICS TS for VSE/ESA: REXX Guide
ITERATE
Purpose
 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 just as though the
END clause had been encountered. 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.
ITERATE
Chapter 13. Keyword Instructions 147
LEAVE
Purpose
 LEAVE
name
; 
LEAVE causes an immediate exit from one or more repetitive DO loops (that is, any DO construct other
than a simple DO).
Processing of the group of instructions is ended, and control is passed to the instruction following the END
clause, just as though the END clause had been encountered and the termination condition had been met.
However, on exit, 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.
LEAVE
148 CICS TS for VSE/ESA: REXX Guide
NOP
Purpose
 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 /* Do nothing */
when a>c then say ’A > C’
otherwise say ’A < C’
end
Note: 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.
NOP
Chapter 13. Keyword Instructions 149
NUMERIC
Purpose
 NUMERIC DIGITS
expression1
SCIENTIFIC
FORM
ENGINEERING
expression2
VALUE
FUZZ
expression3
; 
NUMERIC changes the way in which a program carries out arithmetic operations. The options of this
instruction are described in detail on pages 217-224, 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 9digits. 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—see the note on
page 109 for more information) but note that high precisions are likely to require a good deal of
processing time. It is recommended that you use the default value wherever possible.
You can retrieve the current NUMERIC DIGITS setting with the DIGITS built-in function, see section
“DIGITS” on page 183.
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 section
“FORM” on page 185.
NUMERIC FUZZ
controls how many digits, at full precision, are ignored during a numeric comparison operation. (See
page 222.) If you omit expression3, the default is 0digits. 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.
You can retrieve the current NUMERIC FUZZ setting with the FUZZ built-in function, see section
“FUZZ” on page 186.
Note: The three numeric settings are automatically saved across internal and external subroutine and
function calls. See the CALL instruction (page “Purpose” on page 135) for more details.
NUMERIC
150 CICS TS for VSE/ESA: REXX Guide
OPTIONS
Purpose
 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 recommended 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 CICREXX488E. 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 search process are tokenized within the current setting of
ETMODE. Therefore, if this is the first statement in the program, the default is NOETMODE.
2. 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.
3. The EXMODE setting is saved and restored across subroutine and function calls.
4. 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.
5. When you specify OPTIONS 'ETMODE', DBCS characters within a literal string are excluded from the
search for a closing quotation mark in literal strings.
6. 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.
OPTIONS
Chapter 13. Keyword Instructions 151
PARSE
Purpose
 PARSE
UPPER
ARG
EXTERNAL
LINEIN
NUMERIC
PULL
SOURCE
VALUE WITH
expression
VAR name
VERSION
template_list
; 
PARSE assigns data (from various sources) to one or more variables according to the rules of parsing.
(See Chapter 15, “Parsing,” on page 203.)
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 page 211 for
information on 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 EXTERNAL and PARSE PULL, a data string is removed from the queue, for
PARSE LINEIN (and PARSE PULL if the queue is empty), a line is taken from the default input stream,
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 (if it is enabled) is raised.
If you specify the UPPER option, the data to be parsed is first translated to uppercase (that is, lowercase
a–zto uppercase A–Z). 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 the ARG
instruction on page 134 for details and examples.)
Note: You can also retrieve or check the argument strings to a REXX program or internal routine with
the ARG built-in function (see page 175).
PARSE EXTERNAL
This is a non-SAA subkeyword provided in REXX/CICS. The next string from the terminal input buffer
is parsed. This queue may contain data that is the result of external asynchronous events—such as
user console input, or messages. If that queue is empty, a console read results. Note that this
mechanism should not be used for typical console input, for which PULL is more general, but rather
for special applications (such as debugging) where the program stack cannot be disturbed.
PARSE LINEIN
This is the same as PARSE EXTERNAL.
PARSE NUMERIC
This is a non-SAA subkeyword provided in VM. The current numeric controls (as set by the NUMERIC
instruction, see page “Purpose” on page 150) are available. These controls are in the order DIGITS
FUZZ FORM.
PARSE
152 CICS TS for VSE/ESA: REXX Guide
Example:
Parse Numeric Var1
After this instruction, Var1 would be equal to: 9 0 SCIENTIFIC. See section “NUMERIC” on page 150
and the built-in functions in section “DIGITS” on page 183, and section “FORM” on page 185, and
section “FUZZ” on page 186.
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. You can find the number of lines currently in the queue with the QUEUED built-in
function, see page 190. Other programs in the system can alter the queue and use it as a means of
communication with programs written in REXX. See also the PULL instruction on page 158.
Note: PULL and PARSE PULL read from the program stack. If that is empty, they read from the
terminal input buffer; and if that too is empty, they read from the console. (See the PULL
instruction, on page “Purpose” on page 158, for further details.)
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. It returns a source string containing the
following tokens:
1. The characters CICS.
2. The string COMMAND, FUNCTION, or SUBROUTINE depending on whether the program was
invoked as some kind of host command, from a function call in an expression, by a CALL
instruction, or as a server process.
3. The name of the exec in uppercase. The name of the file (RFS), or VSE Librarian Sublibrary from
which the exec was originally loaded. The three formats are:
vLibrary.sublibrary(member)
vRFS fully qualified file identifier
vDataset name (member)
4. Initial (default) host command environment that is always REXXCICS.
5. Identifier of the specific CICS/ESA environment, which in this case is REXX/CICS.
PARSE VALUE
parses the data that is the result of evaluating expression. If you specify no expression, 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 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
Chapter 13. Keyword Instructions 153
PARSE VERSION
parses information describing the language level and the date of the language processor. This
information consists of five words delimited by blanks:
1. The string REXX370, signifying the 370 implementation.
2. The language level description (for example, 3.48).
3. The language processor release date (for example, 05 April 2000).
PARSE
154 CICS TS for VSE/ESA: REXX Guide
PROCEDURE
Purpose
 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 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.
PROCEDURE
Chapter 13. Keyword Instructions 155
Example:
/* This is the main REXX program */
j=1; z.1=’a’
call toft
sayjkm /*Displays "1 7 M" */
exit
/* This is a subroutine */
toft: procedure exposejkz.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 Jwould 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=’jkm’
call test
exit
/* This is a subroutine */
test: procedure expose (a) /* Exposes A, J, K, and M */
sayajkm /*Displays "jkm169" */
return
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
saycdef /*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 */
say value(word(showlist,2)) /* Displays "New" */
e=8 /* E is not exposed */
f=9 /* F was explicitly exposed */
return
Specifying a stem as name exposes this stem and all possible compound variables whose names begin
with that stem. (See page 123 for information about stems.)
PROCEDURE
156 CICS TS for VSE/ESA: REXX Guide
Example:
/* This is the main REXX program */
a.=11; i=13; j=15
i=i+1
C.5 = ’FRED’
call lucky7
saya.a.1ijc.c.5
say ’You should see 11 7 14 15 C. FRED’
exit
lucky7:Procedure Exposeija.c.
/* This exposes I, J, and all variables whose */
/* names start with A. or C. */
A.1=’7’ /* This sets A.1 in the caller’s */
/* 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 the CALL instruction and function descriptions on pages “Purpose” on page 135 and 171 for details
and examples of how routines are called.
PROCEDURE
Chapter 13. Keyword Instructions 157
PULL
Purpose
 PULL
template_list
; 
PULL reads a string from the program stack. If the program stack is empty, PULL then tries reading a line
from the current terminal input device. 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 a–zto uppercase A–Z) and then parsed into
variables according to the rules described in the section on parsing (page 203). Use the PARSE PULL
instruction if you do not desire uppercase translation.
Notes:
1. The REXX/CICS implementation of the external data queue is the program stack. The language
processor reads a line from the program stack. If the program stack is empty, a terminal read occurs.
The program stack for you is in an RLS queue named \SYSTEM\rexxtnum\*PROGSTACK* where
rexxtrnum is an internal REXX task number.
2. If the PULL causes a read from the terminal, the variable PULLKEY is set upon completion of the
PULL command. It will contain the name of the aid key pressed in response to the PULL command (for
example: ENTER, PFKEY 1, PAKEY 1, MSR, PEN, or CLEAR).
For information on named queues, see the REXX List System LPULL command in section “LPULL” on
page 275.
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.
If the external data queue is empty, a console read is issued and the program pauses, if necessary, until a
line is complete.
The QUEUED built-in function (see page 190) returns the number of lines currently in the program stack.
PULL
158 CICS TS for VSE/ESA: REXX Guide
PUSH
Purpose
 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 REXX/CICS implementation of the external data queue is the program stack. The language
processor reads a line from the program stack. If the program stack is empty, a terminal read
occurs. The program stack for you is in an RLS queue named \SYSTEM\rexxtnum\*PROGSTACK*
where rexxtrnum is an internal REXX task number.
For information on named queues, see the REXX List System LPUSH command, section “LPUSH” on
page 276.
Example:
a=’Fred’
push /* Puts a null line onto the queue */
push a 2 /* Puts "Fred 2" onto the queue */
The QUEUED built-in function (described on page 190) returns the number of lines currently in the
external data queue.
PUSH
Chapter 13. Keyword Instructions 159
QUEUE
Purpose
 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 REXX/CICS implementation of the external data queue is the program stack. The language
processor reads a line from the program stack. If the program stack is empty, a terminal read
occurs. The program stack for you is in an RLS queue named \SYSTEM\rexxtnum\*PROGSTACK*
where rexxtrnum is an internal REXX task number.
Example:
a=’Toft’
queue a 2 /* Enqueues "Toft 2" */
queue /* Enqueues a null line behind the last */
The QUEUED built-in function (described on page 190) returns the number of lines currently in the
external data queue.
QUEUE
160 CICS TS for VSE/ESA: REXX Guide
RETURN
Purpose
 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 page “Purpose” on page 143.)
Ifasubroutine 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.Ifexpression
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 page “Purpose” on page
135.)
Ifafunction 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 the description of functions on page 171 for more details.
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.
RETURN
Chapter 13. Keyword Instructions 161
SAY
Purpose
 SAY
expression
; 
SAY writes a line to the default output stream (the terminal) so the user sees it displayed. The result of
expression may be of any length. If you omit expression, the null string is written.
You can use the SET TERMOUT command to redirect SAY output.
Example:
data=100
Say data ’divided by 4 =>’ data/4
/* Displays: "100 divided by 4 => 25" */
SAY
162 CICS TS for VSE/ESA: REXX Guide
SELECT
Purpose
 SELECT; WHEN expression THEN instruction
;;
OTHERWISE
instruction
;
END ; 
SELECT conditionally calls one of several alternative instructions.
Each expression after a WHEN is evaluated in turn and must result in 0or 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 ’Warning, 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.
SELECT
Chapter 13. Keyword Instructions 163
SIGNAL
Purpose
 SIGNAL labelname
expression
VALUE
OFF ERROR
FAILURE
HALT
NOVALUE
SYNTAX
ON ERROR
FAILURE NAME trapname
HALT
NOVALUE
SYNTAX
; 
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 on condition traps is contained in
Chapter 17, “Conditions and Condition Traps,” on page 225.
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, control always passes to the first
occurrence, if duplicates are present, 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.
For information about using SIGNAL with the INTERPRET instruction, see Note 1 on page 145.
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.
SIGNAL
164 CICS TS for VSE/ESA: REXX Guide
Example:
fred=’PETE’
call multiway fred, 7
....
....
exit
Multiway: procedure
arg label . /* One word, uppercase */
/* Can add checks for valid labels here */
signal value label /* Transfer control to wherever */
....
Pete: say arg(1) '!' arg(2) /* Displays: "PETE ! 7" */
return
SIGNAL
Chapter 13. Keyword Instructions 165
TRACE
Purpose
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:
vA numeric option
vOne of the valid prefix or alphabetic character (word) options described later
vNull.
The symbol is taken as a constant, and is, therefore:
vA numeric option
vOne 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).
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:
3. See page 125 for definitions of error and failure.
 TRACE
number
Normal
All
Commands
? Error
! Failure
Intermediates
Labels
Off
Results
Scan
; 
Or, alternatively:
 TRACE
string
symbol
expression
VALUE
; 
TRACE
166 CICS TS for VSE/ESA: REXX Guide
All Traces (that is, displays) all clauses before execution.
Commands
Traces all commands before execution. If the command results in an error or failure 3,tracing also
displays the return code from the command.
Error Traces any command resulting in an error or failure 3after execution, together with the return code
from the command.
Failure
Traces any command resulting in a failure 3after execution, together with the return code from the
command. This is the same as the Normal option.
Intermediates
Traces all clauses before execution. Also traces intermediate results during evaluation of
expressions and substituted names.
Labels
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.
Normal
Traces any command resulting in a negative return code after execution, together with the return
code from the command. This is the default setting.
Off Traces nothing and resets the special prefix options (described later) to OFF.
Results
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 recommended for general debugging.
Scan 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.
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:
?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 411 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:
vEntering TRACE O turns off all tracing.
vEntering TRACE with no options restores the defaults—it turns off interactive debug but continues
tracing with TRACE Normal (which traces any failing command after execution) in effect.
vEntering TRACE ? turns off interactive debug and continues tracing with the current option.
vEntering a TRACE instruction with a ?prefix before the option turns off interactive debug and
continues tracing with the new option.
TRACE
Chapter 13. Keyword Instructions 167
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.)
!Inhibits host command execution. During regular execution, a 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.
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 411, 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.
2. You can retrieve the trace actions currently in effect by using the TRACE built-in function (see section
“TRACE” on page 195).
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
(page “Purpose” on page 135) 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. */
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
TRACE
168 CICS TS for VSE/ESA: REXX Guide
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 page 204).
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.
>F> The data traced is the result of a function call.
>L> The data traced is a literal (string, uninitialized variable, or constant symbol).
>O> The data traced is the result of an operation on two terms.
>P> The data traced is the result of a prefix operation.
>V> 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.
TRACE
Chapter 13. Keyword Instructions 169
UPPER
Purpose
This is a non-SAA instruction provided in REXX/CICS.
 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 page 121.)
Using this instruction is more convenient than repeatedly invoking the TRANSLATE built-in function.
Example:
a1=’Hello’; b1=’there’
Upper a1 b1
say a1 b1 /* 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.
UPPER
170 CICS TS for VSE/ESA: REXX Guide
Chapter 14. Functions
Afunction 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
Afunction 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 VM, 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 192) 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.
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
© Copyright IBM Corp. 1992, 2010 171
instruction, various other status information (TRACE and NUMERIC settings and so forth) is saved
too. See the CALL instruction (page “Purpose” on page 135) 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 164).
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
While searching for an internal label, syntax checking is performed and the exec is tokenized. See
Appendix I, “Performance Considerations,” on page 425 for more details. FACTORIAL is unusual
in that it calls itself (this is recursive invocation). The PROCEDURE instruction ensures that a new
variable nis 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
These functions are always available and are defined in the next section of this manual.
External
You can write or use functions that are external to your program and to the language processor.
External routines must be written in REXX. 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.
Notes:
1. External REXX functions can easily perform an EXEC CICS LINK to a program written in any
CICS-supported language. Also, REXX/CICS command routines may be written in assembler.
2. 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).
3. 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.
4. 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.
Functions
172 CICS TS for VSE/ESA: REXX Guide
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.
External functions and subroutines have a system-defined search order. The search order for external
functions and subroutines follows.
Whenever an exec, command, external function, or subroutine, written in REXX is invoked by REXX/CICS
(for example: from the CICS command line, CALL instruction, EXEC command, or a command from within
an exec), the search order for locating the target exec is as follows:
vSearch order for a DEFCMD defined command exec or other called exec:
Note: If this is an attempt to execute an authorized command, a check is made to see if this is an
authorized user or the command is in an exec loaded from a VSE Librarian sublibrary specified
on a SETSYS AUTHCLIB or SETSYS AUTHELIB command. If none of these are true, the
command fails with a return code of -4.
1. Within the current exec for an internal function or subroutine.
Note: This search can be bypassed by explicitly identifying the function (or subroutine) as external by
enclosing its name in quotes.
vExecs in storage (from an earlier EXECLOAD).
vThe current RFS directory.
vThe current PATH. RFS directories and VSE Librarian sublibraries are searched in the order listed in the
most recent PATH command, if it was executed.
vVSE Librarian sublibraries in the order listed in the most recent SETSYS AUTHCLIB command.
If the user is an authorized user or if the current exec was loaded from a sublibrary specified on the last
SETSYS AUTHELIB command and the search is for an authorized command's program, then check the
sublibraries specified on the most recent SETSYS AUTHCLIB command.
vVSE Librarian sublibraries in the order listed in the most recent SETSYS AUTHELIB command.
vVSE Librarian members with a member type of PROC in the LIBDEF PROC search chain for the CICS
partition.
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.
Functions
Chapter 14. Functions 173
Built-in Functions
REXX provides a rich set of built-in functions, including character manipulation, conversion, and
information functions.
Other built-in and external functions are generally available—see section “External Functions Provided in
REXX/CICS” on page 201.
The following are general notes on the built-in functions:
vThe 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.
vThe 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. Any argument named as a
number is rounded, if necessary, according to the current setting of NUMERIC DIGITS (just as though
the number had been added to 0) and checked for validity before use. This occurs in the following
functions: ABS, FORMAT, MAX, MIN, SIGN, and TRUNC, and for certain options of DATATYPE. This is
not true for RANDOM.
vAny argument named as a string may be a null string.
vIf 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.
vWhere 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. You can include any number of trailing
commas; they are ignored. (Where there are actual parameters, the default values apply.)
vIf 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 188.)
vIf a function has an option you can select by specifying the first character of a string, that character can
be in upper- or lowercase.
vA number of the functions described in this chapter support DBCS. A complete list and descriptions of
these functions are in Appendix C, “Double-Byte Character Set (DBCS) Support,” on page 395.
Functions
174 CICS TS for VSE/ESA: REXX Guide
ABBREV (Abbreviation)
 ABBREV(information,info
,length
) 
returns 1if info is equal to the leading characters of information and the length of info is not less than
length. Returns 0if 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:
ABBREV(’Print’,’Pri’) -> 1
ABBREV(’PRINT’,’Pri’) -> 0
ABBREV(’PRINT’,’PRI’,4) -> 0
ABBREV(’PRINT’,’PRY’) -> 0
ABBREV(’PRINT’,’’) -> 1
ABBREV(’PRINT’,’’,1) -> 0
Note: 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’) -> 12.3
ABS(’ -0.307’) -> 0.307
ADDRESS
 ADDRESS() 
returns the name of the environment to which commands are currently being submitted. The environment
may be a name of a subcommand environment. See the ADDRESS instruction (page “Purpose” on page
132) for more information. Trailing blanks are removed from the result.
Here are some examples:
ADDRESS() -> ’CICS’ /* default under CICS */
ADDRESS() -> ’EDITSVR’ /* default under CICS editor */
ARG (Argument)
 ARG(
n
,option
) 
Functions
Chapter 14. Functions 175
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 nmust 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 returns 1if the nth argument exists; that is, if it was explicitly specified when the routine was
called. Returns 0otherwise.
Omitted
returns 1if the nth argument was omitted; that is, if it was not explicitly specified when the routine
was called. Returns 0otherwise.
Here are some examples:
/* following "Call name;" (no arguments) */
ARG() -> 0
ARG(1) -> ’’
ARG(2) -> ’’
ARG(1,’e’) -> 0
ARG(1,’O’) -> 1
/* following "Call name ’a’,,’b’;" */
ARG() -> 3
ARG(1) -> ’a’
ARG(2) -> ’’
ARG(3) -> ’b’
ARG(n) -> ’’ /* for n>=4 */
ARG(1,’e’) -> 1
ARG(2,’E’) -> 0
ARG(2,’O’) -> 1
ARG(3,’o’) -> 0
ARG(4,’o’) -> 1
Notes:
1. The number of argument strings is the largest number nfor which ARG(n,’e’) would return 1or 0if
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 “Purpose” on page 134, 152, and 203.)
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 encodings 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:
Functions
176 CICS TS for VSE/ESA: REXX Guide
BITAND(’12’x) -> ’12’x
BITAND(’73’x,’27’x) -> ’23’x
BITAND(’13’x,’5555’x) -> ’1155’x
BITAND(’13’x,’5555’x,’74’x) -> ’1154’x
BITAND(’pQrS’,,’BF’x) -> ’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
encodings 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(’12’x) -> ’12’x
BITOR(’15’x,’24’x) -> ’35’x
BITOR(’15’x,’2456’x) -> ’3556’x
BITOR(’15’x,’2456’x,’F0’x) -> ’35F6’x
BITOR(’1111’x,,’4D’x) -> ’5D5D’x
BITOR(’pQrS’,,’40’x) -> ’PQRS’ /* EBCDIC */
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
encodings 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(’12’x) -> ’12’x
BITXOR(’12’x,’22’x) -> ’30’x
BITXOR(’1211’x,’22’x) -> ’3011’x
BITXOR(’1111’x,’444444’x) -> ’555544’x
BITXOR(’1111’x,’444444’x,’40’x) -> ’555504’x
BITXOR(’1111’x,,’4D’x) -> ’5C5C’x
BITXOR(’C711’x,’222222’x,’ ’) -> ’E53362’x /* 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 (0or 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 A–F, and does not include blanks.
Functions
Chapter 14. Functions 177
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 0digits are added on the left before the conversion to make a total
that is a multiple of four.
Here are some examples:
B2X(’11000011’) -> ’C3’
B2X(’10111’) -> ’17’
B2X(’101’) -> ’5’
B2X(’1 1111 0000’) -> ’1F0’
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) -> ’ ABC ’
CENTER(abc,8,’-’) -> ’--ABC---’
CENTRE(’The blue sky’,8) -> ’e blue s’
CENTRE(’The blue sky’,7) -> ’e blue ’
Note: 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 0if 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’) -> 0
COMPARE(’abc’,’ak’) -> 2
COMPARE(’ab ’,’ab’) -> 0
COMPARE(’ab ’,’ab’,’ ’) -> 0
COMPARE(’ab ’,’ab’,’x’) -> 3
COMPARE(’ab-- ’,’ab’,’-’) -> 5
CONDITION
 CONDITION(
option
) 
returns the condition information associated with the current trapped condition. (See Chapter 17,
“Conditions and Condition Traps,” on page 225 for a description of condition traps.) You can request the
following pieces of information:
vThe name of the current trapped condition
vAny descriptive string associated with that condition
Functions
178 CICS TS for VSE/ESA: REXX Guide
vThe instruction processed as a result of the condition trap (CALL or SIGNAL)
vThe 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
returns the name of the current trapped condition.
Description
returns any descriptive string associated with the current trapped condition. If no description is
available, returns a null string.
Instruction
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.
Status
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.
If no condition has been trapped, then the CONDITION function returns a null string in all four cases.
Here are some examples:
CONDITION() -> ’CALL’ /* perhaps */
CONDITION(’C’) -> ’FAILURE’
CONDITION(’I’) -> ’CALL’
CONDITION(’D’) -> ’FailureTest’
CONDITION(’S’) -> ’OFF’ /* perhaps */
Note: 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.
COPIES
 COPIES(string,n) 
returns nconcatenated copies of string. The nmust be a positive whole number or zero.
Here are some examples:
COPIES(’abc’,3) -> ’abcabcabc’
COPIES(’abc’,0) -> ’’
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.
Functions
Chapter 14. Functions 179
If string is null, returns 0.
Here are some examples:
C2D(’09’X) -> 9
C2D(’81’X) -> 129
C2D(’FF81’X) -> 65409
C2D(’’) -> 0
C2D(’a’) -> 129 /* EBCDIC */
If you specify n, the string is taken as a signed number expressed in ncharacters. 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 ncharacters. This padding or
truncation is as though RIGHT(string,n,’00’x) had been processed. If nis 0, C2D always returns 0.
Here are some examples:
C2D(’81’X,1) -> -127
C2D(’81’X,2) -> 129
C2D(’FF81’X,2) -> -127
C2D(’FF81’X,1) -> -127
C2D(’FF7F’X,1) -> 127
C2D(’F081’X,2) -> -3967
C2D(’F081’X,1) -> -127
C2D(’0031’X,0) -> 0
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 A–Fand 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’) -> ’F7F2A2’ /* ’C6F7C6F2C1F2’X in EBCDIC */
C2X(’0123’X) -> ’0123’ /* ’F0F1F2F3’X 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 1if string matches the type; otherwise returns 0.Ifstring is null, the function
returns 0(except when type is X, which returns 1for 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 xrather than h.)
Alphanumeric
returns 1if string contains only characters from the ranges a–z,A–Z, and 0–9.
Functions
180 CICS TS for VSE/ESA: REXX Guide
Binary
returns 1if string contains only the characters 0or 1or both.
Creturns 1if string is a mixed SBCS/DBCS string.
Dbcs returns 1if string is a DBCS-only string enclosed by SO and SI bytes.
Lowercase
returns 1if string contains only characters from the range a–z.
Mixed case
returns 1if string contains only characters from the ranges a–zand A–Z.
Number
returns 1if string is a valid REXX number.
Symbol
returns 1if string contains only characters that are valid in REXX symbols. (See page 112.) Note
that both uppercase and lowercase alphabetics are permitted.
Uppercase
returns 1if string contains only characters from the range A–Z.
Whole number
returns 1if string is a REXX whole number under the current setting of NUMERIC DIGITS.
heXadecimal
returns 1if string contains only characters from the ranges a–f,A–F,0–9, and blank (as long as
blanks appear only between pairs of hexadecimal characters). Also returns 1if string is a null
string, which is a valid hexadecimal string.
Here are some examples:
DATATYPE(’ 12 ’) -> ’NUM’
DATATYPE(’’) -> ’CHAR’
DATATYPE(’123*’) -> ’CHAR’
DATATYPE(’12.3’,’N’) -> 1
DATATYPE(’12.3’,’W’) -> 0
DATATYPE(’Fred’,’M’) -> 1
DATATYPE(’’,’M’) -> 0
DATATYPE(’Fred’,’L’) -> 0
DATATYPE(’?20K’,’s’) -> 1
DATATYPE(’BCd3’,’X’) -> 1
DATATYPE(’BC d3’,’X’) -> 1
Note: 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(
option
) 
returns, by default, the local date in the format: dd mon yyyy (day month year—for example, 13 Mar 1992),
with no leading zero or blank on the day. If the active language has an abbreviated form of the month
name, then it is used (for example, Jan,Feb, and so on).
You can use the following options to obtain specific formats. (Only the capitalized and highlighted letter is
needed; all characters following it are ignored.)
Base returns the number of complete days (that is, not including the current day) since and including the
Functions
Chapter 14. Functions 181
base date, 1 January 0001, in the format: dddddd (no leading zeros or blanks). The expression
DATE('B')//7 returns a number in the range 0–6that corresponds to the current day of the week,
where 0is Monday and 6is 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
returns 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 format: ddddd (no leading zeros). Example: A call to DATE(C)
on 13 March 1992 returns 33675, the number of days from 1 January 1900 to 13 March 1992.
Similarly, a call to DATE(C) on 2 January 2000 returns 2, the number of days from 1 January 2000
to 2 January 2000.
Days returns the number of days, including the current day, so far in this year in the format: ddd (no
leading zeros or blanks).
European
returns date in the format: dd/mm/yy.
Julian
returns date in the format: yyddd.
Month
returns full English name of the current month, for example, August.
Normal
returns date in the format: dd mon yyyy.This is the default.
Ordered
returns date in the format: yy/mm/dd (suitable for sorting, and so forth).
Standard
returns date in the format: yyyymmdd (suitable for sorting, and so forth).
Usa returns date in the format: mm/dd/yy.
Weekday
returns the English name for the day of the week, in mixed case, for example, Tuesday.
Here are some examples, assuming today is 13 March 1992:
DATE() -> ’13 Mar 1992’
DATE(’B’) -> 727269
DATE(’C’) -> 33675
DATE(’D’) -> 73
DATE(’E’) -> ’13/03/92’
DATE(’J’) -> 92073
DATE(’M’) -> ’March’
DATE(’N’) -> ’13 Mar 1992’
DATE(’O’) -> ’92/03/13’
DATE(’S’) -> ’19920313’
DATE(’U’) -> ’03/13/92’
DATE(’W’) -> ’Friday’
Note: 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.
Functions
182 CICS TS for VSE/ESA: REXX Guide
DBCS (Double-Byte Character Set Functions)
The following are all part of DBCS processing functions:
vDBADJUST
vDBBRACKET
vDBCENTER
vDBCJUSTIFY
vDBLEFT
vDBRIGHT
vDBRLEFT
vDBRRIGHT
vDBTODBCS
vDBTOSBCS
vDBUNBRACKET
vDBVALIDATE
vDBWIDTH
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,oriflength is greater than the number of characters from nto 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 nmust be a positive whole number. If nis greater than the length of string, the function returns
string unchanged.
Here are some examples:
DELSTR(’abcd’,3) -> ’ab’
DELSTR(’abcde’,3,2) -> ’abe’
DELSTR(’abcde’,6) -> ’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,oriflength is greater than the number of words from nto 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 nmust be a positive whole number. If nis 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 is the time’,2,2) -> ’Now time’
DELWORD(’Now is the time ’,3) -> ’Now is ’
DELWORD(’Now is the time’,5) -> ’Now is the time’
DELWORD(’Now is the time’,3,1) -> ’Now is time’
DIGITS
 DIGITS() 
returns the current setting of NUMERIC DIGITS. See the NUMERIC instruction on page “Purpose” on
page 150 for more information.
Functions
Chapter 14. Functions 183
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 ncharacters, then the result is
truncated on the left. The nmust be a positive whole number or zero.
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) -> ’ ’ /* ’09’x is unprintable in EBCDIC */
D2C(129) -> ’a’ /* ’81’x is an EBCDIC ’a’ */
D2C(129,1) -> ’a’ /* ’81’x is an EBCDIC ’a’ */
D2C(129,2) -> ’ a’ /* ’0081’x is EBCDIC ’ a’ */
D2C(257,1) -> ’ ’ /* ’01’x is unprintable in EBCDIC */
D2C(-127,1) -> ’a’ /* ’81’x is EBCDIC ’a’ */
D2C(-127,2) -> ’ a’ /* ’FF’x is unprintable EBCDIC; */
/* ’81’x is EBCDIC ’a’ */
D2C(-1,4) -> ’ ’ /* ’FFFFFFFF’x is unprintable in EBCDIC */
D2C(12,0) -> ’’ /* ’’ 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 A–Fand 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 ncharacters, it is truncated on the
left. The nmust 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) -> ’9’
D2X(129) -> ’81’
D2X(129,1) -> ’1’
D2X(129,2) -> ’81’
D2X(129,4) -> ’0081’
D2X(257,2) -> ’01’
D2X(-127,2) -> ’81’
D2X(-127,4) -> ’FF81’
D2X(12,0) -> ’’
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).
Functions
184 CICS TS for VSE/ESA: REXX Guide
ERRORTEXT
 ERRORTEXT(n) 
returns the REXX error message associated with error number n. The nmust be in the range 0–99, and
any other value is an error. Returns the null string if nis in the allowed range but is not a defined REXX
error number. See Appendix A, “Error Numbers and Messages,” on page 379 for a complete description of
error numbers and messages.
Here are some examples:
ERRORTEXT(16) -> ’Label not found’
ERRORTEXT(60) -> ’’
EXTERNALS
 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 CICS, there is no equivalent buffer. Therefore, in the CICS implementation of REXX, the
EXTERNALS function always returns a 0.
FIND
WORDPOS is the preferred built-in function for this type of word search. See page 198 for a complete
description.
 FIND(string,phrase) 
returns the word number of the first word of phrase found in string or returns 0if phrase is not found or if
there are no words in phrase. The phrase is a sequence of 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’) -> 2
FIND(’now is the time’,’is the’) -> 2
FIND(’now is the time’,’is time ’) -> 0
FORM
 FORM() 
returns the current setting of NUMERIC FORM. See the NUMERIC instruction on page “Purpose” on page
150 for more information.
Here is an example:
FORM() -> ’SCIENTIFIC’ /* by default */
FORMAT
 FORMAT(number
,
before , expnt
after
) 
Functions
Chapter 14. Functions 185
 expnt:
,
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 0causes the number to be rounded to an integer.
Here are some examples:
FORMAT(’3’,4) -> ’3’
FORMAT(’1.73’,4,0) -> ’2’
FORMAT(’1.73’,4,3) -> ’ 1.730’
FORMAT(’-.76’,4,1) -> ’ -0.8’
FORMAT(’3.03’,4) -> ’ 3.03’
FORMAT(’ - 12.73’,,4) -> ’-12.7300’
FORMAT(’ - 12.73’) -> ’-12.73’
FORMAT(’0.000’) -> ’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 0value of expt.) If the exponent would be 0when 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. The expp must be less than 10, but there is no limit on the
other arguments.
Here are some examples:
FORMAT(’12345.73’,,,2,2) -> ’1.234573E+04’
FORMAT(’12345.73’,,3,,0) -> ’1.235E+4’
FORMAT(’1.234573’,,3,,0) -> ’1.235’
FORMAT(’12345.73’,,,3,6) -> ’12345.73’
FORMAT(’1234567e5’,,3,0) -> ’123456700000.000’
FUZZ
Functions
186 CICS TS for VSE/ESA: REXX Guide
 FUZZ() 
returns the current setting of NUMERIC FUZZ. See the NUMERIC instruction on page “Purpose” on page
150 for more information.
Here is an example:
FUZZ() -> 0 /* by default */
INDEX
POS is the preferred built-in function for obtaining the position of one string in another. See page 190 for a
complete description.
 INDEX(haystack,needle
,start
) 
returns the character position of one string, needle, in another, haystack, or returns 0if 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’) -> 3
INDEX(’abcdef’,’xd’) -> 0
INDEX(’abcdef’,’bc’,3) -> 0
INDEX(’abcabc’,’bc’,3) -> 5
INDEX(’abcabc’,’bc’,6) -> 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 nis 0, which means insert before the beginning of the string. If specified, nand
length must be positive whole numbers or zero. If nis 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.Iflength 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) -> ’abc def’
INSERT(’123’,’abc’,5,6) -> ’abc 123 ’
INSERT(’123’,’abc’,5,6,’+’) -> ’abc++123+++’
INSERT(’123’,’abc’) -> ’123abc’
INSERT(’123’,’abc’,,5,’-’) -> ’123--abc’
JUSTIFY
 JUSTIFY(string,length
,pad
) 
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
Functions
Chapter 14. Functions 187
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 blue sky’,14) -> ’The blue sky’
JUSTIFY(’The blue sky’,8) -> ’The blue’
JUSTIFY(’The blue sky’,9) -> ’The blue’
JUSTIFY(’The blue sky’,9,’+’) -> ’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 0if 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’) -> 8
LASTPOS(’ ’,’abcdefghi’) -> 0
LASTPOS(’xy’,’efgxyz’) -> 4
LASTPOS(’ ’,’abc def ghi’,7) -> 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
) 
Here are some examples:
LEFT(’abc d’,8) -> ’abc d ’
LEFT(’abc d’,8,’.’) -> ’abc d...’
LEFT(’abc def’,7) -> ’abc de’
LENGTH
 LENGTH(string) 
returns the length of string.
Here are some examples:
LENGTH(’abcdefgh’) -> 8
LENGTH(’abc defg’) -> 8
LENGTH(’’) -> 0
LINESIZE
 LINESIZE() 
returns the current terminal line width (the point at which the language processor breaks lines displayed
Functions
188 CICS TS for VSE/ESA: REXX Guide
using the SAY instruction). Returns a default value of 80 if:
vNo terminal is attached.
vOutput is being redirected.
Note: To determine if a terminal is attached, specify the REXX/CICS command SCRNINFO. The values
for screen height and screen width are 0 if there is no terminal attached.
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) -> 12
MAX(17.3,19,17.03) -> 19
MAX(-7,-3,-4.3) -> -3
MAX(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,MAX(20,21)) -> 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) -> 6
MIN(17.3,19,17.03) -> 17.03
MIN(-7,-3,-4.3) -> -7
MIN(21,20,19,18,17,16,15,14,13,12,11,10,9,8,7,6,5,4,3,MIN(2,1)) -> 1
Implementation maximum: You can specify up to 20 numbers, and can nest calls to MIN if more
arguments are needed.
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.Ifnis 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 nis 1. If you specify n, it must be a positive whole
number.
Here are some examples:
Functions
Chapter 14. Functions 189
OVERLAY(’ ’,’abcdef’,3) -> ’ab def’
OVERLAY(’.’,’abcdef’,3,2) -> ’ab. ef’
OVERLAY(’qq’,’abcd’) -> ’qqcd’
OVERLAY(’qq’,’abcd’,4) -> ’abcqq’
OVERLAY(’123’,’abc’,5,6,’+’) -> ’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 0if 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’) -> 6
POS(’x’,’abc def ghi’) -> 0
POS(’ ’,’abc def ghi’) -> 4
POS(’ ’,’abc def ghi’,5) -> 8
QUEUED
 QUEUED() 
returns the number of lines remaining in the external data queue when the function is called. If no lines are
remaining, a PULL or PARSE PULL reads from the terminal input buffer. If no terminal input is waiting, this
causes a console read.
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 0and 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() -> 305
RANDOM(5,8) -> 7
RANDOM(2) -> 0/*0to2 */
RANDOM(,,1983) -> 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:
Functions
190 CICS TS for VSE/ESA: REXX Guide
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, the microsecond field of the time-of-day clock is used as the seed; and hence your
program almost always gives different results each time it is run.
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.’) -> ’.cBA’
REVERSE(’XYZ ’) -> ’ 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) -> ’ abc d’
RIGHT(’abc def’,5) -> ’c def’
RIGHT(’12’,5,’0’) -> ’00012’
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 0if it is 0; and returns 1if it is greater than 0.
Here are some examples:
SIGN(’12.3’) -> 1
SIGN(’ -0.307’) -> -1
SIGN(0.0) -> 0
SOURCELINE
 SOURCELINE(
n
) 
returns the line number of the final line in the program if you omit n, or returns the nth line in the program
Functions
Chapter 14. Functions 191
if you specify n. If specified, nmust be a positive whole number and must not exceed the number of the
final line in the program.
Here are some examples:
SOURCELINE() -> 10
SOURCELINE(1) -> ’/* 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 nis 1, and the default pad character is a blank.
Here are some examples:
SPACE(’abc def ’) -> ’abc def’
SPACE(’ abc def’,3) -> ’abc def’
SPACE(’abc def ’,1) -> ’abc def’
SPACE(’abc def ’,0) -> ’abcdef’
SPACE(’abc def ’,2,’+’) -> ’abc++def’
STORAGE
See section “External Functions Provided in REXX/CICS” on page 201.
STRIP
 STRIP(string
,
option ,char
) 
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 removes both leading and trailing characters from string. This is the default.
Leading
removes leading characters from string.
Trailing
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 ’) -> ’ab c’
STRIP(’ ab c ’,’L’) -> ’ab c ’
STRIP(’ ab c ’,’t’) -> ’abc’
STRIP(’12.7000’,,0) -> ’12.7’
STRIP(’0012.700’,,0) -> ’12.7’
SUBSTR (Substring)
Functions
192 CICS TS for VSE/ESA: REXX Guide
 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 nmust be a positive whole number. If nis 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) -> ’bc’
SUBSTR(’abc’,2,4) -> ’bc ’
SUBSTR(’abc’,2,6,’.’) -> ’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
) 
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) -> ’is the’
SUBWORD(’Now is the time’,3) -> ’the time’
SUBWORD(’Now is the time’,5) -> ’’
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.
Note: 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 */
Functions
Chapter 14. Functions 193
TIME
 TIME(
option
) 
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 1through 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.
Elapsed
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.
Hours 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).
Long 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.
Minutes
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).
Normal
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.
Reset 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.
Seconds
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).
Here are some examples, assuming that the time is 4:54 p.m.:
TIME() -> ’16:54:22’
TIME(’C’) -> ’4:54pm’
TIME(’H’) -> ’16’
TIME(’L’) -> ’16:54:22.123456’ /* Perhaps */
TIME(’M’) -> ’1014’ /* 54 + 60*16 */
TIME(’N’) -> ’16:54:22’
TIME(’S’) -> ’60862’ /* 22 + 60*(54+60*16) */
The elapsed-time clock:
Functions
194 CICS TS for VSE/ESA: REXX Guide
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’) -> 0 /* The first call */
/* pause of one second here */
time(’E’) -> 1.002345 /* or thereabouts */
/* pause of one second here */
time(’R’) -> 2.004690 /* or thereabouts */
/* pause of one second here */
time(’R’) -> 1.002345 /* or thereabouts */
Note: 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,orS) or both.
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() -> ’?R’ /* maybe */
TRACE(’O’) -> ’?R’ /* also sets tracing off */
TRACE(’?I’) -> ’O’ /* now in interactive debug */
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.
Functions
Chapter 14. Functions 195
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 a–zto uppercase A–Z), but, if you include pad, the language
processor translates the entire string to pad characters. tablei defaults to XRANGE(’00’x,’FF’x), 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’) -> ’ABCDEF’
TRANSLATE(’abbc’,’&’,’b’) -> ’a&&c’
TRANSLATE(’abcdef’,’12’,’ec’) -> ’ab2d1f’
TRANSLATE(’abcdef’,’12’,’abcd’,’.’) -> ’12..ef’
TRANSLATE(’APQRV’,,’PR’) -> ’AQV’
TRANSLATE(’APQRV’,XRANGE(’00’X,’Q’)) -> ’APQ ’
TRANSLATE(’4123’,’abcd’,’1234’) -> ’dabc’
Note: 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 ndecimal places. The default nis 0and 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 ndecimal places (or trailing zeros are added if needed to make up the
specified length). The result is never in exponential form.
Here are some examples:
TRUNC(12.3) -> 12
TRUNC(127.09782,3) -> 127.097
TRUNC(127.1,3) -> 127.100
TRUNC(127,2) -> 127.00
Note: The number is rounded according to the current setting of NUMERIC DIGITS if necessary before
the function processes it.
USERID
 USERID() 
returns the CICS signon user ID if the user is signed onto CICS or the CICS region default user ID (if one
was specified by the CICS systems programmer). User IDs are padded on the right with blanks so that the
returned value is always eight bytes long.
Here is an example:
USERID() -> ’ARTHUR’ /* Maybe */
VALUE
 VALUE(name
,
newvalue ,selector
) 
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, however, if
you want to specify selector the value must be RLS. If the selector of RLS is specified, then the variable
operated on is a REXX List System (RLS) variable, rather than a REXX variable. If you use the function to
Functions
196 CICS TS for VSE/ESA: REXX Guide
refer to REXX variables, then name must be a valid REXX symbol. (You can confirm this by using the
SYMBOL function.) Lowercase characters in name are translated to uppercase. Substitution in a
compound name (see section “Compound Symbols” on page 122) 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; A33=7; K=3; fred=’K’; list.5=’Hi’ */
VALUE(’a’k) -> ’A3’ /* looks up A3 */
VALUE(’a’k||k) -> ’7’ /* looks up A33 */
VALUE(’fred’) -> ’K’ /* looks up FRED */
VALUE(fred) -> ’3’ /* looks up K */
VALUE(fred,5) -> ’3’ /* looks up K and */
/* then sets K=5 */
VALUE(fred) -> ’5’ /* looks up K */
VALUE(’LIST.’k) -> ’Hi’ /* looks up LIST.5 */
The following example returns the VALUE of the REXX variable FRED that has been stored in an RLS
variable.
/* REXX EXEC - ASSIGN FIND VALUE OF FRED */
FRED = 7
’RLS VARPUT FRED \USERS\userid\’
X = VALUE(FRED,,RLS)
SAY X
/*Xnow=7 */
Notes:
1. 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. A reference to RLS variables never raises
NOVALUE.
2. If you specify the name as a single literal string and omit newvalue and selector, 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 17, “Conditions and Condition Traps,” on page 225.)
VERIFY
 VERIFY(string,reference
,
option ,start
) 
returns a number that, by default, indicates whether string is composed only of characters from reference;
returns 0if 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
0if 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.Ifreference is null, the function returns 0if you specify
Match; otherwise the function returns the start value.
Functions
Chapter 14. Functions 197
Here are some examples:
VERIFY(’123’,’1234567890’) -> 0
VERIFY(’1Z3’,’1234567890’) -> 2
VERIFY(’AB4T’,’1234567890’) -> 1
VERIFY(’AB4T’,’1234567890’,’M’) -> 3
VERIFY(’AB4T’,’1234567890’,’N’) -> 1
VERIFY(’1P3Q4’,’1234567890’,,3) -> 4
VERIFY(’123’,’’,N,2) -> 2
VERIFY(’ABCDE’,’’,,3) -> 3
VERIFY(’AB3CD5’,’1234567890’,’M’,4) -> 6
WORD
 WORD(string,n) 
returns the nth blank-delimited word in string or returns the null string if fewer than nwords are in string.
The nmust 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) -> ’the’
WORD(’Now is the time’,5) -> ’’
WORDINDEX
 WORDINDEX(string,n) 
returns the position of the first character in the nth blank-delimited word in string or returns 0if fewer than
nwords are in string. The nmust be a positive whole number.
Here are some examples:
WORDINDEX(’Now is the time’,3) -> 8
WORDINDEX(’Now is the time’,6) -> 0
WORDLENGTH
 WORDLENGTH(string,n) 
returns the length of the nth blank-delimited word in string or returns 0if fewer than nwords are in string.
The nmust be a positive whole number.
Here are some examples:
WORDLENGTH(’Now is the time’,2) -> 2
WORDLENGTH(’Now comes the time’,2) -> 5
WORDLENGTH(’Now is the time’,6) -> 0
WORDPOS (Word Position)
 WORDPOS(phrase,string
,start
) 
returns the word number of the first word of phrase found in string or returns 0if 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.
Functions
198 CICS TS for VSE/ESA: REXX Guide
Here are some examples:
WORDPOS(’the’,’now is the time’) -> 3
WORDPOS(’The’,’now is the time’) -> 0
WORDPOS(’is the’,’now is the time’) -> 2
WORDPOS(’is the’,’now is the time’) -> 2
WORDPOS(’is time ’,’now is the time’) -> 0
WORDPOS(’be’,’To be or not to be’) -> 2
WORDPOS(’be’,’To be or not to be’,3) -> 6
WORDS
 WORDS(string) 
returns the number of blank-delimited words in string.
Here are some examples:
WORDS(’Now is the time’) -> 4
WORDS(’ ’) -> 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 default value for end is 'FF'x.Ifstart 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’) -> ’abcdef’
XRANGE(’03’x,’07’x) -> ’0304050607’x
XRANGE(,’04’x) -> ’0001020304’x
XRANGE(’i’,’j’) -> ’898A8B8C8D8E8F9091’x /* EBCDIC */
XRANGE(’FE’x,’02’x) -> ’FEFF000102’x
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’) -> ’11000011’
X2B(’7’) -> ’0111’
X2B(’1 C1’) -> ’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(’C3’x)) -> ’11000011’
X2B(D2X(’129’)) -> ’10000001’
X2B(D2X(’12’)) -> ’1100’
Functions
Chapter 14. Functions 199
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.
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’) -> ’72s’ /* EBCDIC */
X2C(’F7f2a2’) -> ’72s’ /* EBCDIC */
X2C(’F’) -> ’ ’ /* ’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’) -> 129
X2D(’F81’) -> 3969
X2D(’FF81’) -> 65409
X2D(’c6 f0’X) -> 240 /* EBCDIC */
If you specify n, the string is taken as a signed number expressed in nhexadecimal 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 nis 0, the function
returns 0.
If necessary, hexstring is padded on the left with 0characters (note, not “sign-extended”), or truncated on
the left to ncharacters.
Here are some examples:
X2D(’81’,2) -> -127
X2D(’81’,4) -> 129
X2D(’F081’,4) -> -3967
X2D(’F081’,3) -> 129
X2D(’F081’,2) -> -127
X2D(’F081’,1) -> 1
X2D(’0031’,0) -> 0
Functions
200 CICS TS for VSE/ESA: REXX Guide
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.
External Functions Provided in REXX/CICS
Additional external functions provided in the REXX/CICS environment are discussed in this section.
STORAGE
Note: This is an authorized function.
 STORAGE(address
,
length ,data
) 
returns length bytes from the user's memory starting at address. The length is in decimal; the default is 1
byte. The address is a hexadecimal number. The high-order bit of address is ignored.
If you specify data, after the old value has been retrieved storage starting at address is overwritten with
data (the length argument has no effect on this).
Note: The STORAGE function can operate on storage above the 16MB line.
Warning: The STORAGE function, which allows a REXX user to display and/or modify the virtual storage
of the CICS region, can only be successfully invoked from an authorized exec or by an authorized user.
Examples:
/* Note that the following results vary from system to system. */
STORAGE(200000,32)
/* This returns 32 bytes of storage at hex address 200000 as a result. */
SYSSBA
 SYSSBA ( row ,col ) 
SYSSBA converts screen row,col to a set buffer address (SBA).
Operands:
row
specifies the row number counting from the top of the screen.
col
specifies the column number (counting from the left of the screen).
Example:
x = SYSSBA(10,20)
This example returns a three byte set buffer address for screen row 10, column 20 into REXX
variable x.
Note: The SYSSBA function queries the terminal model on each invocation and uses this to adjust the
SBA calculation to terminal type.
Functions
Chapter 14. Functions 201
Functions
202 CICS TS for VSE/ESA: REXX Guide
Chapter 15. Parsing
General Description
The parsing instructions are ARG, PARSE, and PULL (see section “ARG” on page 134, section “PARSE”
on page 152, and section “PULL” on page 158).
The data to parse is a source string. Parsing splits up the data in a source string and assigns pieces of it
into the variables named in a template. A template is a model specifying how to split the source string. The
simplest kind of template consists of only a list of variable names. Here is an example:
variable1 variable2 variable3
This kind of template parses the source string into blank-delimited words. More complicated templates
contain patterns in addition to variable names.
String patterns
Match characters in the source string to specify where to split it. (See section “Templates
Containing String Patterns” on page 205 for details.)
Positional patterns
Indicate the character positions at which to split the source string. (See section “Templates
Containing Positional (Numeric) Patterns” on page 206 for details.)
Parsing is essentially a two-step process.
1. Parse the source string into appropriate substrings using patterns.
2. Parse each substring into words.
Simple Templates for Parsing into Words
Here is a parsing instruction:
parse value ’time and tide’ with var1 var2 var3
The template in this instruction is: var1 var2 var3. The data to parse is between the keywords PARSE
VALUE and the keyword WITH, the source string time and tide. Parsing divides the source string into
blank-delimited words and assigns them to the variables named in the template as follows:
var1=’time’
var2=’and’
var3=’tide’
In this example, the source string to parse is a literal string, time and tide. In the next example, the
source string is a variable.
/* PARSE VALUE using a variable as the source string to parse */
string=’time and tide’
parse value string with var1 var2 var3 /* same results */
(PARSE VALUE does not convert lowercase a–zin the source string to uppercase A–Z. If you want to
convert characters to uppercase, use PARSE UPPER VALUE. See “Using UPPER” on page 209 for a
summary of the effect of parsing instructions on case.)
All of the parsing instructions assign the parts of a source string into the variables named in a template.
There are various parsing instructions because of differences in the nature or origin of source strings. (A
summary of all the parsing instructions is on page 210.)
© Copyright IBM Corp. 1992, 2010 203
The PARSE VAR instruction is similar to PARSE VALUE except that the source string to parse is always a
variable. In PARSE VAR, the name of the variable containing the source string follows the keywords PARSE
VAR. In the next example, the variable stars contains the source string. The template is star1 star2
star3.
/* PARSE VAR example */
stars=’Sirius Polaris Rigil’
parse var stars star1 star2 star3 /* star1=’Sirius’ */
/* star2=’Polaris’ */
/* star3=’Rigil’ */
All variables in a template receive new values. If there are more variables in the template than words in
the source string, the leftover variables receive null (empty) values. This is true for all parsing: for parsing
into words with simple templates and for parsing with templates containing patterns. Here is an example
using parsing into words.
/* More variables in template than (words in) the source string */
satellite=’moon’
parse var satellite Earth Mercury /* Earth=’moon’ */
/* Mercury=’’ */
If there are more words in the source string than variables in the template, the last variable in the template
receives all leftover data. Here is an example:
/* More (words in the) source string than variables in template */
satellites=’moon Io Europa Callisto...’
parse var satellites Earth Jupiter /* Earth=’moon’ */
/* Jupiter=’Io Europa Callisto...’*/
Parsing into words removes leading and trailing blanks from each word before it is assigned to a variable.
The exception to this is the word or group of words assigned to the last variable. The last variable in a
template receives leftover data, preserving extra leading and trailing blanks. Here is an example:
/* Preserving extra blanks */
solar5=’Mercury Venus Earth Mars Jupiter ’
parse var solar5 var1 var2 var3 var4
/* var1 =’Mercury’ */
/* var2 =’Venus’ */
/* var3 =’Earth’ */
/* var4 =’ Mars Jupiter ’ */
In the source string, Earth has two leading blanks. Parsing removes both of them (the word-separator
blank and the extra blank) before assigning var3=’Earth’.Mars has three leading blanks. Parsing removes
one word-separator blank and keeps the other two leading blanks. It also keeps all five blanks between
Mars and Jupiter and both trailing blanks after Jupiter.
Parsing removes no blanks if the template contains only one variable. For example:
parse value ’ Pluto ’ with var1 /* var1=’ Pluto ’*/
The Period as a Placeholder
A period in a template is a placeholder. It is used instead of a variable name, but it receives no data. It is
useful:
vAs a “dummy variable” in a list of variables
vOr to collect unwanted information at the end of a string.
The period in the first example is a placeholder. Be sure to separate adjacent periods with spaces;
otherwise, an error results.
/* Period as a placeholder */
stars=’Arcturus Betelgeuse Sirius Rigil’
parse var stars . . brightest . /* brightest=’Sirius’ */
Parsing
204 CICS TS for VSE/ESA: REXX Guide
/* Alternative to period as placeholder */
stars=’Arcturus Betelgeuse Sirius Rigil’
parse var stars drop junk brightest rest /* brightest=’Sirius’ */
A placeholder saves the overhead of unneeded variables.
Templates Containing String Patterns
Astring pattern matches characters in the source string to indicate where to split it. A string pattern can be
a:
Literal string pattern
One or more characters within quotation marks.
Variable string pattern
A variable within parentheses with no plus (+) or minus (-) or equal sign (=) before the left
parenthesis. (See page 209 for details.)
Here are two templates: a simple template and a template containing a literal string pattern:
var1 var2 /* simple template */
var1 ’, ’ var2 /* template with literal string pattern */
The literal string pattern is: ’, ’. This template:
vPuts characters from the start of the source string up to (but not including) the first character of the
match (the comma) into var1
vPuts characters starting with the character after the last character of the match (the character after the
blank that follows the comma) and ending with the end of the string into var2.
A template with a string pattern can omit some of the data in a source string when assigning data into
variables. The next two examples contrast simple templates with templates containing literal string
patterns.
/* Simple template */
name=’Smith, John’
parse var name ln fn /* Assigns: ln=’Smith,’ */
/* fn=’John’ */
Notice that the comma remains (the variable ln contains ’Smith,’). In the next example the template is ln
’,’fn. This removes the comma.
/* Template with literal string pattern */
name=’Smith, John’
parse var name ln ’, ’ fn /* Assigns: ln=’Smith’ */
/* fn=’John’ */
First, the language processor scans the source string for ', '. It splits the source string at that point. The
variable ln receives data starting with the first character of the source string and ending with the last
character before the match. The variable fn receives data starting with the first character after the match
and ending with the end of string.
A template with a string pattern omits data in the source string that matches the pattern. (There is a
special case (on page 212) in which a template with a string pattern does not omit matching data in the
source string.) We used the pattern ’, ’ (with a blank) instead of ’,’ (no blank) because, without the
blank in the pattern, the variable fn receives ' John' (including a blank).
If the source string does not contain a match for a string pattern, then any variables preceding the
unmatched string pattern get all the data in question. Any variables after that pattern receive the null
string.
A null string is never found. It always matches the end of the source string.
Parsing
Chapter 15. Parsing 205
Templates Containing Positional (Numeric) Patterns
Apositional pattern is a number that identifies the character position at which to split data in the source
string. The number must be a whole number.
An absolute positional pattern is
vA number with no plus (+) or minus (-) sign preceding it or with an equal sign (=) preceding it
vA variable in parentheses with an equal sign before the left parenthesis. (See page 209 for details on
variable positional patterns.)
The number specifies the absolute character position at which to split the source string.
Here is a template with absolute positional patterns:
variable1 11 variable2 21 variable3
The numbers 11 and 21 are absolute positional patterns. The number 11 refers to the 11th position in the
input string, 21 to the 21st position. This template:
vPuts characters 1 through 10 of the source string into variable1
vPuts characters 11 through 20 into variable2
vPuts characters 21 to the end into variable3.
Positional patterns are probably most useful for working with a file of records, such as:
character positions:
11121 40
┌──────────┬──────────┬────────────────────┐end of
FIELDS: │LASTNAME │FIRST │PSEUDONYM │record
└──────────┴──────────┴────────────────────┘
The following example uses this record structure.
/* Parsing with absolute positional patterns in template */
record.1=’Clemens Samuel Mark Twain ’
record.2=’Evans Mary Ann George Eliot ’
record.3=’Munro H.H. Saki ’
do n=1 to 3
parse var record.n lastname 11 firstname 21 pseudonym
If lastname=’Evans’ & firstname=’Mary Ann’ then say ’By George!’
end /* Says ’By George!’ after record 2 */
The source string is first split at character position 11 and at position 21. The language processor assigns
characters 1 to 10 into lastname, characters 11 to 20 into firstname, and characters 21 to 40 into
pseudonym.
The template could have been:
1 lastname 11 firstname 21 pseudonym
instead of
lastname 11 firstname 21 pseudonym
Specifying the 1is optional.
Optionally, you can put an equal sign before a number in a template. An equal sign is the same as no sign
before a number in a template. The number refers to a particular character position in the source string.
These two templates work the same:
lastname 11 first 21 pseudonym
lastname =11 first =21 pseudonym
Parsing
206 CICS TS for VSE/ESA: REXX Guide
Arelative positional pattern is a number with a plus (+) or minus (-) sign preceding it. (It can also be a
variable within parentheses, with a plus (+) or minus (-) sign preceding the left parenthesis; for details see
section “Parsing with Variable Patterns” on page 209.)
The number specifies the relative character position at which to split the source string. The plus or minus
indicates movement right or left, respectively, from the start of the string (for the first pattern) or from the
position of the last match. The position of the last match is the first character of the last match. Here is the
same example as for absolute positional patterns done with relative positional patterns:
/* Parsing with relative positional patterns in template */
record.1=’Clemens Samuel Mark Twain ’
record.2=’Evans Mary Ann George Eliot ’
record.3=’Munro H.H. Saki ’
do n=1 to 3
parse var record.n lastname +10 firstname + 10 pseudonym
If lastname=’Evans’ & firstname=’Mary Ann’ then say ’By George!’
end /* same results */
Blanks between the sign and the number are insignificant. Therefore, +10 and +10have the same
meaning. Note that +0 is a valid relative positional pattern.
Absolute and relative positional patterns are interchangeable (except in the special case (on page 212)
when a string pattern precedes a variable name and a positional pattern follows the variable name). The
templates from the examples of absolute and relative positional patterns give the same results.
│ │ │lastname 11│ │firstname 21 │ │ pseudonym │
│ │ │lastname +10│ │firstname + 10│ │ pseudonym │
└──┬───┘ └──────┬─────┘ └──────┬───────┘ └─────┬─────┘
││ │ │
(Implied Put characters Put characters Put characters
starting 1 through 10 11 through 20 21 through
point is in lastname. in firstname. end of string
position (Non─inclusive (Non─inclusive in pseudonym.
1.) stopping point stopping point
is 11 (1+10).) is 21 (11+10).)
Only with positional patterns can a matching operation back up to an earlier position in the source string.
Here is an example using absolute positional patterns:
/* Backing up to an earlier position (with absolute positional) */
string=’astronomers’
parse var string 2 var1 4 1 var2 2 4 var3 5 11 var4
say string ’study’ var1||var2||var3||var4
/* Displays: "astronomers study stars" */
The absolute positional pattern 1backs up to the first character in the source string.
With relative positional patterns, a number preceded by a minus sign backs up to an earlier position. Here
is the same example using relative positional patterns:
/* Backing up to an earlier position (with relative positional) */
string=’astronomers’
parse var string 2 var1 +2 -3 var2 +1 +2 var3 +1 +6 var4
say string ’study’ var1||var2||var3||var4 /* same results */
In the previous example, the relative positional pattern -3 backs up to the first character in the source
string.
The templates in the last two examples are equivalent.
Parsing
Chapter 15. Parsing 207
│ 2 │ │var1 4 │ │ 1 │ │var2 2│ │ 4 var3 5│ │11 var4 │
│ 2 │ │var1 +2 │ │ ─3 │ │var2 +1│ │+2 var3 +1│ │+6 var4 │
└──┬──┘ └───┬────┘ └──┬───┘ └───┬───┘ └────┬─────┘ └───┬────┘
││││ │ │
Start Non─ Go to 1. Non─ Go to 4 Go to 11
at 2. inclusive (4─3=1) inclusive (2+2=4). (5+6=11).
stopping stopping Non─inclusive
point is 4 point is stopping point
(2+2=4). 2 (1+1=2). is 5 (4+1=5).
You can use templates with positional patterns to make multiple assignments:
/* Making multiple assignments */
books=’Silas Marner, Felix Holt, Daniel Deronda, Middlemarch’
parse var books 1 Eliot 1 Evans
/* Assigns the (entire) value of books to Eliot and to Evans. */
Combining Patterns and Parsing Into Words
What happens when a template contains patterns that divide the source string into sections containing
multiple words? String and positional patterns divide the source string into substrings. The language
processor then applies a section of the template to each substring, following the rules for parsing into
words.
/* Combining string pattern and parsing into words */
name=’ John Q. Public’
parse var name fn init ’.’ ln /* Assigns: fn=’John’ */
/* init=’ Q’ */
/* ln=’ Public’ */
The pattern divides the template into two sections:
vfn init
vln
The matching pattern splits the source string into two substrings:
v’ John Q’
v’ Public’
The language processor parses these substrings into words based on the appropriate template section.
John had three leading blanks. All are removed because parsing into words removes leading and trailing
blanks except from the last variable.
Qhas six leading blanks. Parsing removes one word-separator blank and keeps the rest because init is
the last variable in that section of the template.
For the substring ’ Public’, parsing assigns the entire string into ln without removing any blanks. This
is because ln is the only variable in this section of the template. (For details about treatment of blanks,
see page 204.)
/* Combining positional patterns with parsing into words */
string=’REXX’
parse var string var1 var2 4 var3 6 var4 /* Assigns: var1=’R’ */
/* var2=’E’ */
/* var3=’ X’ */
/* var4=’ X’ */
The pattern divides the template into three sections:
vvar1 var2
vvar3
vvar4
The matching patterns split the source string into three substrings that are individually parsed into words:
Parsing
208 CICS TS for VSE/ESA: REXX Guide
v’R E’
v’X’
v’X’
The variable var1 receives ’R’;var2 receives ’E’. Both var3 and var4 receive ’X’(with a blank before
the X) because each is the only variable in its section of the template. (For details on treatment of blanks,
see page 204.)
Parsing with Variable Patterns
You may want to specify a pattern by using the value of a variable instead of a fixed string or number. You
do this by placing the name of the variable in parentheses. This is a variable reference. Blanks are not
necessary inside or outside the parentheses, but you can add them if you wish.
The template in the next parsing instruction contains the following literal string pattern ’. ’.
parse var name fn init ’. ’ ln
Here is how to specify that pattern as a variable string pattern:
strngptrn=’. ’
parse var name fn init (strngptrn) ln
If no equal, plus, or minus sign precedes the parenthesis that is before the variable name, the value of the
variable is then treated as a string pattern. The variable can be one that has been set earlier in the same
template.
Example:
/* Using a variable as a string pattern */
/* The variable (delim) is set in the same template */
SAY "Enter a date (mm/dd/yy format). =====> " /* assume 11/15/90 */
pull date
parse var date month 3 delim +1 day +2 (delim) year
/* Sets: month=’11’; delim=’/’; day=’15’; year=’90’ */
If an equal, a plus, or a minus sign precedes the left parenthesis, then the value of the variable is treated
as an absolute or relative positional pattern. The value of the variable must be a positive whole number or
zero.
The variable can be one that has been set earlier in the same template. In the following example, the first
two fields specify the starting character positions of the last two fields.
Example:
/* Using a variable as a positional pattern */
dataline = ’12 26 .....Samuel ClemensMark Twain’
parse var dataline pos1 pos2 6 =(pos1) realname =(pos2) pseudonym
/* Assigns: realname=’Samuel Clemens’; pseudonym=’Mark Twain’ */
Why is the positional pattern 6needed in the template? Remember that word parsing occurs after the
language processor divides the source string into substrings using patterns. Therefore, the positional
pattern =(pos1) cannot be correctly interpreted as =12 until after the language processor has split the
string at column 6 and assigned the blank-delimited words 12 and 26 to pos1 and pos2, respectively.
Using UPPER
Specifying UPPER on any of the PARSE instructions converts characters to uppercase (lowercase a–zto
uppercase A–Z) before parsing. The following table summarizes the effect of the parsing instructions on
case.
Parsing
Chapter 15. Parsing 209
Converts alphabetic characters to uppercase
before parsing
Maintains alphabetic characters in case entered
ARG
PARSE UPPER ARG
PARSE ARG
PARSE UPPER EXTERNAL PARSE EXTERNAL
PARSE UPPER NUMERIC PARSE NUMERIC
PULL
PARSE UPPER PULL
PARSE PULL
PARSE UPPER SOURCE PARSE SOURCE
PARSE UPPER VALUE PARSE VALUE
PARSE UPPER VAR PARSE VAR
PARSE UPPER VERSION PARSE VERSION
The ARG instruction is simply a short form of PARSE UPPER ARG. The PULL instruction is simply a short
form of PARSE UPPER PULL. If you do not desire uppercase translation, use PARSE ARG (instead of
ARG or PARSE UPPER ARG) and use PARSE PULL (instead of PULL or PARSE UPPER PULL).
Parsing Instructions Summary
Remember: All parsing instructions assign parts of the source string into the variables named in the
template. The following table summarizes where the source string comes from.
Instruction Where the source string comes from
ARG
PARSE ARG
Arguments you list when you call the program or arguments in the call to a
subroutine or function.
PARSE EXTERNAL Next line from terminal input buffer
PARSE NUMERIC Numeric control information (from NUMERIC instruction).
PULL
PARSE PULL
The string at the head of the external data queue. (If queue empty, uses default
input, typically the terminal.)
PARSE SOURCE System-supplied string giving information about the executing program.
PARSE VALUE Expression between the keyword VALUE and the keyword WITH in the instruction.
PARSE VAR name Parses the value of name.
PARSE VERSION System-supplied string specifying the language, language level, and (three-word)
date.
Parsing Instructions Examples
All examples in this section parse source strings into words.
ARG
/* ARG with source string named in REXX program invocation */
/* Program name is PALETTE. Specify 2 primary colors (yellow, */
/* red, blue) on call. Assume call is: palette red blue */
arg var1 var2 /* Assigns: var1=’RED’; var2=’BLUE’ */
If var1<>’RED’ & var1<>’YELLOW’ & var1<>’BLUE’ then signal err
If var2<>’RED’ & var2<>’YELLOW’ & var2<>’BLUE’ then signal err
total=length(var1)+length(var2)
SELECT;
When total=7 then new=’purple’
Parsing
210 CICS TS for VSE/ESA: REXX Guide
When total=9 then new=’orange’
When total=10 then new=’green’
Otherwise new=var1 /* entered duplicates */
END
Say new; exit /* Displays: "purple" */
Err:
say ’Input error--color is not "red" or "blue" or "yellow"’; exit
ARG converts alphabetic characters to uppercase before parsing. An example of ARG with the
arguments in the CALL to a subroutine is in section “Parsing Multiple Strings.”
PARSE ARG
Works the same as ARG except that PARSE ARG does not convert alphabetic characters to
uppercase before parsing.
PARSE EXTERNAL
Say "Enter Yes or No =====> "
parse upper external answer 2 .
If answer=’Y’
then say "You said ’Yes’!"
else say "You said ’No’!"
PARSE NUMERIC
parse numeric digits fuzz form
say digits fuzz form /* Displays: ’9 0 SCIENTIFIC’ */
/* (if defaults are in effect) */
PARSE PULL
PUSH ’80 7’ /* Puts data on queue */
parse pull fourscore seven /* Assigns: fourscore=’80’; seven=’7’ */
SAY fourscore+seven /* Displays: "87" */
PARSE SOURCE
parse source sysname .
Say sysname /* Displays: "CICS" */
PARSE VALUE
Example is on page 203.
PARSE VAR
Examples are throughout the chapter, starting on page 204.
PARSE VERSION
parse version . level .
say level /* Displays: "3.48" */
PULL Works the same as PARSE PULL except that PULL converts alphabetic characters to uppercase
before parsing.
Advanced Topics in Parsing
This section includes parsing multiple strings and flow charts depicting a conceptual view of parsing.
Parsing Multiple Strings
Only ARG and PARSE ARG can have more than one source string. To parse multiple strings, you can
specify multiple comma-separated templates. Here is an example:
parse arg template1, template2, template3
This instruction consists of the keywords PARSE ARG and three comma-separated templates. (For an
ARG instruction, the source strings to parse come from arguments you specify when you call a program or
CALL a subroutine or function.) Each comma is an instruction to the parser to move on to the next string.
Example:
Parsing
Chapter 15. Parsing 211
/* Parsing multiple strings in a subroutine */
num=’3’
musketeers="Porthos Athos Aramis D’Artagnon"
CALL Sub num,musketeers /* Passes num and musketeers to sub */
SAY total; say fourth /* Displays: "4" and " D’Artagnon" */
EXIT
Sub:
parse arg subtotal,...fourth
total=subtotal+1
RETURN
Note that when a REXX program is started as a command, only one argument string is recognized. You
can pass multiple argument strings for parsing:
vWhen one REXX program calls another REXX program with the CALL instruction or a function call.
vWhen programs written in other languages start a REXX program.
If there are more templates than source strings, each variable in a leftover template receives a null string.
If there are more source strings than templates, the language processor ignores leftover source strings. If
a template is empty (two commas in a row) or contains no variable names, parsing proceeds to the next
template and source string.
Combining String and Positional Patterns: A Special Case
There is a special case in which absolute and relative positional patterns do not work identically. We have
shown how parsing with a template containing a string pattern skips over the data in the source string that
matches the pattern (see page 205). But a template containing the sequence:
vstring pattern
vvariable name
vrelative positional pattern
does not skip over the matching data. A relative positional pattern moves relative to the first character
matching a string pattern. As a result, assignment includes the data in the source string that matches the
string pattern.
/* Template containing string pattern, then variable name, then */
/* relative positional pattern does not skip over any data. */
string=’REstructured eXtended eXecutor’
parse var string var1 3 junk ’X’ var2 +1 junk ’X’ var3 +1 junk
say var1||var2||var3 /* Concatenates variables; displays: "REXX" */
Here is how this template works:
│var1 3│ │junk ’X’│ │var2 +1│ │junk ’X’│ │var3 +1 │ │ junk │
└───┬───┘ └───┬────┘ └───┬───┘ └────┬────┘ └───┬────┘ └──┬───┘
││││││
Put Starting Starting Starting Starting Starting
characters at 3, put with first with char─ with with char─
1 through characters ’X’ put 1 acter after second ’X’ acter
2 in var1. up to (not (+1) first ’X’ put 1 (+1) after sec─
(Stopping including) character put up to character ond ’X’
point is first ’X’ in var2. second ’X’ in var3. put rest
3.) in junk. in junk. in junk.
var1=’RE’ junk= var2=’X’ junk= var3=’X’ junk=
’structured ’tended e’ ’ecutor’
e’
Parsing with DBCS Characters
Parsing with DBCS characters generally follows the same rules as parsing with SBCS characters. Literal
strings and symbols can contain DBCS characters, but numbers must be in SBCS characters. See
“PARSE” on page 398 for examples of DBCS parsing.
Parsing
212 CICS TS for VSE/ESA: REXX Guide
Details of Steps in Parsing
The three figures that follow are to help you understand the concept of parsing. Please note that the
figures do not include error cases.
The figures include terms whose definitions are as follows:
string start
is the beginning of the source string (or substring).
string end
is the end of the source string (or substring).
length is the length of the source string.
match start
is in the source string and is the first character of the match.
match end
is in the source string. For a string pattern, it is the first character after the end of the match. For a
positional pattern, it is the same as match start.
match position
is in the source string. For a string pattern, it is the first matching character. For a positional
pattern, it is the position of the matching character.
token is a distinct syntactic element in a template, such as a variable, a period, a pattern, or a comma.
value is the numeric value of a positional pattern. This can be either a constant or the resolved value of
a variable.
Parsing
Chapter 15. Parsing 213
┌────────────────────────────────────────┐
│
┌────────────────────────────────┐ │
│START │ │
│Token is first one in template. │ │
│Length=length(source string) │ │
│Match start=1. Match end=1. │ │
└─────────┬──────────────────────┘ │
┌────────── │ │
│ │
│ ┌───────────────────┐yes ┌────────────────────┐ │
│ │End of template? ├───│Parsing complete. │ │
│ └─────────┬─────────┘ └────────────────────┘ │
│  no │
│ ┌───────────────────┐ │
│ │CALL Find Next │ │
│ │ Pattern. │ │
│ └─────────┬─────────┘ │
│ │
│ ┌───────────────────┐ │
│ │CALL Word Parsing. │ │
│ └─────────┬─────────┘ │
│ │
│ ┌───────────────────┐ │
│ │Step to next token.│ │
│ └─────────┬─────────┘ │
│ │
│ ┌───────────────────┐ yes ┌────────────────────┐ │
│ │Token a comma? ├────│Set next source │ │
│ └─────────┬─────────┘ │string and template.├───┘
│ │ no └────────────────────┘
└────────────┘
Figure 50. Conceptual Overview of Parsing
Parsing
214 CICS TS for VSE/ESA: REXX Guide
┌────────────────────────────────────────────────┐
│
┌─────────────┐ ┌────────────────────────────────┐ │
│Start: │yes │String start=match end. │ │
│End of ├───│Match start=length + 1. │ │
│template? │ │Match end=length + 1. Return. │ │
└─────┬───────┘ └────────────────────────────────┘ │
no │
┌─────────────┐ ┌────────────────────────────────┐ │
│Token period │yes │ │ │
│or variable? ├───│Step to next token. ├───┘
└─────┬───────┘ └────────────────────────────────┘
no
┌─────────────┐ ┌─────────┐ ┌──────────┐ ┌───────────────────────────────────┐
│Token a plus?│yes │Variable │yes │Resolve │ │String start=match start. │
│ ├───│form? ├───│its value.├──│Match start=min(length + 1, │
└─────┬───────┘ └────┬────┘ └──────────┘ │ match start + value). │
│ no │ no │ │Match end=match start. Return. │
└─────────────────────┘ └───────────────────────────────────┘
┌─────────────┐ ┌─────────┐ ┌──────────┐ ┌───────────────────────────────────┐
│Token a │yes │Variable │yes │Resolve │ │String start=match start. │
│minus? ├───│form? ├───│its value.├──│Match start=max(1, match │
└─────┬───────┘ └────┬────┘ └──────────┘ │ start ─ value). │
│ no │ no │ │Match end=match start. Return. │
└─────────────────────┘ └───────────────────────────────────┘
┌─────────────┐ ┌─────────┐ ┌──────────┐ ┌───────────────────────────────────┐
│Token an │yes │Variable │yes │Resolve │ │String start=match end. │
│equal? ├───│form? ├───│its value.├──│Match start=min(length+1, value). │
└─────┬───────┘ └────┬────┘ └──────────┘ │Match end=match start. Return. │
│ no │ no │ └───────────────────────────────────┘
 └─────────────────────┘
┌─────────────┐ ┌───────────────────────────────────┐
│Token a │yes │String start=match end. │
│number? ├───│Match start=min(length+1, value). │
└─────┬───────┘ │Match end=match start. Return. │
 no └───────────────────────────────────┘
┌─────────────┐
│Token a lit─ │yes
│eral string? ├──────────────────────────┐
└─────┬───────┘ │
│no │

┌─────────────┐ ┌──────────┐ ┌───────────────┐ ┌─────────────────────────────┐
│Token a var─ │yes │Resolve │ │Match found in │yes │String start=match end. │
│iable string?├───│its value.├──│rest of string?├───│Match start=match position. │
└─────┬───────┘ └──────────┘ └──────┬────────┘ │Match end=match position + │
│ no │ no │ pattern length. Return. │
│  └─────────────────────────────┘
│ ┌────────────────────────────────┐
│ │String start=match end. │
│ │Match start=length + 1. │
│ │Match end=length + 1. Return. │
 └────────────────────────────────┘
┌─────────────┐ ┌────────────────────────────────┐
│Token a │yes │Match start=length + 1. │
│ comma? ├─────────│Match end=length + 1. Return. │
└─────────────┘ └────────────────────────────────┘
Figure 51. Conceptual View of Finding Next Pattern
Parsing
Chapter 15. Parsing 215
┌─────────────────────────┐ ┌────────────────────────┐
│Start: Match end <= │no │ │
│ string start? ├───│String end=match start. │
└───────────┬─────────────┘ └────────────────────────┘
 yes
┌─────────────────────────┐
│String end=length + 1. │
└───────────┬─────────────┘
┌──────────────────────────────────────────────────────────────────────┐
│Substring=substr(source string,string start,(string end─string start))│
│Token=previous pattern. │
└───────────┬──────────────────────────────────────────────────────────┘
 ───────────────────────────────────────────────┐
┌─────────────────────────┐no │
│Any more tokens? ├─────────────┐ │
└───────────┬─────────────┘ │ │
 yes │ │
┌─────────────────────────┐ │ │
│Step to next token. │ │ │
└───────────┬─────────────┘ │ │
│
┌─────────────────────────┐no ┌────────────────────────┐ │
│Token a variable or a ├───│Return. │ │
│period? │ └────────────────────────┘ │
└───────────┬─────────────┘ │
 yes │
┌─────────────────────────┐no │
│Any more tokens? ├─────────────┐ │
└───────────┬─────────────┘ │ │
 yes │
┌─────────────────────────┐ ┌────────────────────────┐ │
│Next token a variable or │ no │Assign rest of substring│ │
│period? ├───│to variable. │ │
└───────────┬─────────────┘ └─────────────┬──────────┘ │
 yes └───────────────│
┌─────────────────────────┐ no ┌────────────────────────┐ │
│Any substring left? ├───│Assign null string to │ │
└───────────┬─────────────┘ │variable. │ │
 yes └─────────────┬──────────┘ │
┌─────────────────────────┐ └───────────────│
│Strip any leading blanks.│ │
└───────────┬─────────────┘ │
│
┌─────────────────────────┐ no ┌────────────────────────┐ │
│Any substring left? ├───│Assign null string to │ │
└───────────┬─────────────┘ │variable. │ │
│ └─────────────┬──────────┘ │
 yes └───────────────│
┌─────────────────────────┐ no ┌────────────────────────┐ │
│Blank found in substring?├───│Assign rest of substring│ │
│ │ │to variable. │ │
└───────────┬─────────────┘ └─────────────┬──────────┘ │
 yes └───────────────│
┌───────────────────────────────────────────────────────────┐ │
│Assign word from substring to variable and step past blank.│ │
└───────────────────┬───────────────────────────────────────┘ │
└─────────────────────────────────────────┘
Figure 52. Conceptual View of Word Parsing
216 CICS TS for VSE/ESA: REXX Guide
Chapter 16. Numbers and Arithmetic
REXX defines the usual arithmetic operations (addition, subtraction, multiplication, and division) in as
natural a way as possible. What this really means is that the rules followed are those that are
conventionally taught in schools and colleges.
During the design of these facilities, however, it was found that unfortunately the rules vary considerably
(indeed much more than generally appreciated) from person to person and from application to application
and in ways that are not always predictable. The arithmetic described here is, therefore, a compromise
that (although not the simplest) should provide acceptable results in most applications.
Introduction
Numbers (that is, character strings used as input to REXX arithmetic operations and built-in functions) can
be expressed very flexibly. Leading and trailing blanks are permitted, and exponential notation can be
used. Some valid numbers are:
12 /* a whole number */
’-76’ /* a signed whole number */
12.76 /* decimal places */
’ + 0.003 ’ /* blanks around the sign and so forth */
17. /* same as "17" */
.5 /* same as "0.5" */
4E9 /* exponential notation */
0.73e-7 /* exponential notation */
In exponential notation, a number includes an exponent, a power of ten by which the number is multiplied
before use. The exponent indicates how the decimal point is shifted. Thus, in the preceding examples, 4E9
is simply a short way of writing 4000000000, and 0.73e-7 is short for 0.000000073.
The arithmetic operators include addition (+), subtraction (-), multiplication (*), power (**), division (/),
prefix plus (+), and prefix minus (-). In addition, there are two further division operators: integer divide (%)
divides and returns the integer part; remainder (//) divides and returns the remainder.
The result of an arithmetic operation is formatted as a character string according to definite rules. The
most important of these rules are as follows (see the “Definition” section for full details):
vResults are calculated up to some maximum number of significant digits (the default is 9, but you can
alter this with the NUMERIC DIGITS instruction to give whatever accuracy you need). Thus, if a result
requires more than 9 digits, it would usually be rounded to 9 digits. For example, the division of 2 by 3
would result in 0.666666667 (it would require an infinite number of digits for perfect accuracy).
vExcept for division and power, trailing zeros are preserved (this is in contrast to most popular
calculators, which remove all trailing zeros in the decimal part of results). So, for example:
2.40 + 2 -> 4.40
2.40 - 2 -> 0.40
2.40 * 2 -> 4.80
2.40 / 2 -> 1.2
This behavior is desirable for most calculations (especially financial calculations).
If necessary, you can remove trailing zeros with the STRIP function (see page 192), or by division by 1.
vA zero result is always expressed as the single digit 0.
vExponential form is used for a result depending on its value and the setting of NUMERIC DIGITS (the
default is 9). If the number of places needed before the decimal point exceeds the NUMERIC DIGITS
setting, or the number of places after the point exceeds twice the NUMERIC DIGITS setting, the
number is expressed in exponential notation:
1e6 * 1e6 -> 1E+12 /* not 1000000000000 */
1 / 3E10 -> 3.33333333E-11 /* not 0.0000000000333333333 */
© Copyright IBM Corp. 1992, 2010 217
Definition
A precise definition of the arithmetic facilities of the REXX language is given here.
Numbers
Anumber in REXX is a character string that includes one or more decimal digits, with an optional decimal
point. (See section “Exponential Notation” on page 222 for an extension of this definition.) The decimal
point may be embedded in the number, or may be a prefix or suffix. The group of digits (and optional
decimal point) constructed this way can have leading or trailing blanks and an optional sign (+or -) that
must come before any digits or decimal point. The sign can also have leading or trailing blanks.
Therefore, number is defined as:

blanks sign
blanks
digits
digits.digits
.digits
digits.
blanks

blanks
are one or more spaces
sign
is either +or −
digits
are one or more of the decimal digits 0–9.
Note that a single period alone is not a valid number.
Precision
Precision is the maximum number of significant digits that can result from an operation. This is controlled
by the instruction:
 NUMERIC DIGITS
expression
; 
The expression is evaluated and must result in a positive whole number. This defines the precision
(number of significant digits) to which calculations are carried out. Results are rounded to that precision, if
necessary.
If you do not specify expression in this instruction, or if no NUMERIC DIGITS instruction has been
processed since the start of a program, the default precision is used. The REXX standard for the default
precision is 9.
Note that NUMERIC DIGITS can set values below the default of nine. However, use small values with
care—the loss of precision and rounding thus requested affects all REXX computations, including, for
example, the computation of new values for the control variable in DO loops.
Arithmetic Operators
REXX arithmetic is performed by the operators +,-,*,/,%,//, and ** (add, subtract, multiply, divide,
integer divide, remainder, and power), which all act on two terms, and the prefix plus and minus operators,
which both act on a single term. This section describes the way in which these operations are carried out.
Before every arithmetic operation, the term or terms being operated upon have leading zeros removed
(noting the position of any decimal point, and leaving only one zero if all the digits in the number are
zeros). They are then truncated (if necessary) to DIGITS + 1 significant digits before being used in the
computation. (The extra digit is a “guard” digit. It improves accuracy because it is inspected at the end of
Numbers and Arithmetic
218 CICS TS for VSE/ESA: REXX Guide
an operation, when a number is rounded to the required precision.) The operation is then carried out under
up to double that precision, as described under the individual operations that follow. When the operation is
completed, the result is rounded if necessary to the precision specified by the NUMERIC DIGITS
instruction.
Rounding is done in the traditional manner. The digit to the right of the least significant digit in the result
(the “guard digit”) is inspected and values of 5through 9are rounded up, and values of 0through 4are
rounded down. Even/odd rounding would require the ability to calculate to arbitrary precision at all times
and is, therefore, not the mechanism defined for REXX.
A conventional zero is supplied in front of the decimal point if otherwise there would be no digit before it.
Significant trailing zeros are retained for addition, subtraction, and multiplication, according to the rules that
follow, except that a result of zero is always expressed as the single digit 0. For division, insignificant
trailing zeros are removed after rounding.
The FORMAT built-in function (see page 185) allows a number to be represented in a particular format if
the standard result provided does not meet your requirements.
Arithmetic Operation Rules—Basic Operators
The basic operators (addition, subtraction, multiplication, and division) operate on numbers as follows.
Addition and Subtraction
If either number is 0, the other number, rounded to NUMERIC DIGITS digits, if necessary, is used as the
result (with sign adjustment as appropriate). Otherwise, the two numbers are extended on the right and left
as necessary, up to a total maximum of DIGITS + 1 digits (the number with the smaller absolute value
may, therefore, lose some or all of its digits on the right) and are then added or subtracted as appropriate.
Example:
xxx.xxx + yy.yyyyy
becomes:
xxx.xxx00
+ 0yy.yyyyy
─────────────
zzz.zzzzz
The result is then rounded to the current setting of NUMERIC DIGITS if necessary (taking into account
any extra “carry digit” on the left after addition, but otherwise counting from the position corresponding to
the most significant digit of the terms being added or subtracted). Finally, any insignificant leading zeros
are removed.
The prefix operators are evaluated using the same rules; the operations +number and -number are
calculated as 0+number and 0-number, respectively.
Multiplication
The numbers are multiplied together (“long multiplication”) resulting in a number that may be as long as
the sum of the lengths of the two operands.
Example:
xxx.xxx * yy.yyyyy
becomes:
zzzzz.zzzzzzzz
Numbers and Arithmetic
Chapter 16. Numbers and Arithmetic 219
The result is then rounded, counting from the first significant digit of the result, to the current setting of
NUMERIC DIGITS.
Division
For the division:
yyy / xxxxx
the following steps are taken: First the number yyy is extended with zeros on the right until it is larger than
the number xxxxx (with note being taken of the change in the power of ten that this implies). Thus, in this
example, yyy might become yyy00. Traditional long division then takes place. This might be written:
zzzz
┌─────────
xxxxx │ yyy00
The length of the result (zzzz) is such that the rightmost zis at least as far right as the rightmost digit of
the (extended) ynumber in the example. During the division, the ynumber is extended further as
necessary. The znumber may increase up to NUMERIC DIGITS+1 digits, at which point the division stops
and the result is rounded. Following completion of the division (and rounding if necessary), insignificant
trailing zeros are removed.
Basic Operator Examples
Following are some examples that illustrate the main implications of the rules just described.
/* With: Numeric digits 5 */
12+7.00 -> 19.00
1.3-1.07 -> 0.23
1.3-2.07 -> -0.77
1.20*3 -> 3.60
7*3 -> 21
0.9*0.8 -> 0.72
1/3 -> 0.33333
2/3 -> 0.66667
5/2 -> 2.5
1/10 -> 0.1
12/12 -> 1
8.0/2 -> 4
Note: With all the basic operators, the position of the decimal point in the terms being operated upon is
arbitrary. The operations may be carried out as integer operations with the exponent being
calculated and applied afterward. Therefore, the significant digits of a result are not in any way
dependent on the position of the decimal point in either of the terms involved in the operation.
Arithmetic Operation Rules—Additional Operators
The operation rules for the power (**), integer divide (%), and remainder (//) operators follow.
Power
The ** (power) operator raises a number to a power, which may be positive, negative, or 0. The power
must be a whole number. (The second term in the operation must be a whole number and is rounded to
DIGITS digits, if necessary, as described under “Numbers Used Directly by REXX” on page 224.) If
negative, the absolute value of the power is used, and then the result is inverted (divided into 1). For
calculating the power, the number is effectively multiplied by itself for the number of times expressed by
the power, and finally trailing zeros are removed (as though the result were divided by 1).
In practice (see Note 1 on page 221 for the reasons), the power is calculated by the process of left-to-right
binary reduction. For a**n:nis converted to binary, and a temporary accumulator is set to 1. If n=0the
initial calculation is complete. (Thus, a**0 =1for all a, including 0**0.) Otherwise each bit (starting at the
first nonzero bit) is inspected from left to right. If the current bit is 1, the accumulator is multiplied by a.If
Numbers and Arithmetic
220 CICS TS for VSE/ESA: REXX Guide
all bits have now been inspected, the initial calculation is complete; otherwise the accumulator is squared
and the next bit is inspected for multiplication. When the initial calculation is complete, the temporary result
is divided into 1 if the power was negative.
The multiplications and division are done under the arithmetic operation rules, using a precision of DIGITS
+ L + 1 digits. L is the length in digits of the integer part of the whole number n(that is, excluding any
decimal part, as though the built-in function TRUNC(n)had been used). Finally, the result is rounded to
NUMERIC DIGITS digits, if necessary, and insignificant trailing zeros are removed.
Integer Division
The % (integer divide) operator divides two numbers and returns the integer part of the result. The result
returned is defined to be that which would result from repeatedly subtracting the divisor from the dividend
while the dividend is larger than the divisor. During this subtraction, the absolute values of both the
dividend and the divisor are used: the sign of the final result is the same as that which would result from
regular division.
The result returned has no fractional part (that is, no decimal point or zeros following it). If the result
cannot be expressed as a whole number, the operation is in error and will fail—that is, the result must not
have more digits than the current setting of NUMERIC DIGITS. For example, 10000000000%3 requires 10
digits for the result (3333333333) and would, therefore, fail if NUMERIC DIGITS 9 were in effect. Note that
this operator may not give the same result as truncating regular division (which could be affected by
rounding).
Remainder
The // (remainder) operator returns the remainder from integer division and is defined as being the
residue of the dividend after the operation of calculating integer division as previously described. The sign
of the remainder, if nonzero, is the same as that of the original dividend.
This operation fails under the same conditions as integer division (that is, if integer division on the same
two terms would fail, the remainder cannot be calculated).
Additional Operator Examples
Following are some examples using the power, integer divide, and remainder operators:
/* Again with: Numeric digits 5 */
2**3 -> 8
2**-3 -> 0.125
1.7**8 -> 69.758
2%3 -> 0
2.1//3 -> 2.1
10%3 -> 3
10//3 -> 1
-10//3 -> -1
10.2//1 -> 0.2
10//0.3 -> 0.1
3.6//1.3 -> 1.0
Notes:
1. A particular algorithm for calculating powers is used, because it is efficient (though not optimal) and
considerably reduces the number of actual multiplications performed. It, therefore, gives better
performance than the simpler definition of repeated multiplication. Because results may differ from
those of repeated multiplication, the algorithm is defined here.
2. The integer divide and remainder operators are defined so that they can be calculated as a by-product
of the standard division operation. The division process is ended as soon as the integer result is
available; the residue of the dividend is the remainder.
Numbers and Arithmetic
Chapter 16. Numbers and Arithmetic 221
Numeric Comparisons
The comparison operators are listed in section “Comparison” on page 117. You can use any of these for
comparing numeric strings. However, you should not use ==,\==,¬==,>>,\>>,¬>>,<<,\<<, and ¬<< for
comparing numbers because leading and trailing blanks and leading zeros are significant with these
operators.
A comparison of numeric values is effected by subtracting the two numbers (calculating the difference) and
then comparing the result with 0. That is, the operation:
A?Z
where ?is any numeric comparison operator, is identical with:
(A-Z)?’0’
It is, therefore, the difference between two numbers, when subtracted under REXX subtraction rules, that
determines their equality.
A quantity called fuzz affects the comparison of two numbers. This controls the amount by which two
numbers may differ before being considered equal for the purpose of comparison. The FUZZ value is set
by the instruction:
 NUMERIC FUZZ
expression
; 
Here expression must result in a positive whole number or zero. The default is 0.
The effect of FUZZ is to temporarily reduce the value of DIGITS by the FUZZ value for each numeric
comparison. That is, the numbers are subtracted under a precision of DIGITS minus FUZZ digits during
the comparison. Clearly the FUZZ setting must be less than DIGITS.
Thus if DIGITS = 9 and FUZZ = 1, the comparison is carried out to 8 significant digits, just as though
NUMERIC DIGITS 8 had been put in effect for the duration of the operation.
Example:
Numeric digits 5
Numeric fuzz 0
say 4.9999 = 5 /* Displays "0" */
say 4.9999 < 5 /* Displays "1" */
Numeric fuzz 1
say 4.9999 = 5 /* Displays "1" */
say 4.9999 < 5 /* Displays "0" */
Exponential Notation
The preceding description of numbers describes “pure” numbers, in the sense that the character strings
that describe numbers can be very long. For example:
10000000000 * 10000000000
would give
100000000000000000000
and
.00000000001 * .00000000001
would give
0.0000000000000000000001
Numbers and Arithmetic
222 CICS TS for VSE/ESA: REXX Guide
For both large and small numbers some form of exponential notation is useful, both to make long numbers
more readable, and to make execution possible in extreme cases. In addition, exponential notation is used
whenever the “simple” form would give misleading information.
For example:
numeric digits 5
say 54321*54321
would display 2950800000 in long form. This is clearly misleading, and so the result is expressed as
2.9508E+9 instead.
The definition of numbers is, therefore, extended as:

blanks sign
blanks
digits
digits.digits
.digits
digits.
Edigits
sign
blanks

The integer following the Erepresents a power of ten that is to be applied to the number. The Ecan be in
uppercase or lowercase.
Certain character strings are numbers even though they do not appear to be numeric to the user.
Specifically, because of the format of numbers in exponential notation, strings, such as 0E123 (0 raised to
the 123 power) and 1E342 (1 raised to the 342 power), are numeric. In addition, a comparison such as
0E123=0E567 gives a true result of 1(0 is equal to 0). To prevent problems when comparing nonnumeric
strings, use the strict comparison operators.
Here are some examples:
12E7 = 120000000 /* Displays "1" */
12E-5 = 0.00012 /* Displays "1" */
-12e4 = -120000 /* Displays "1" */
0e123 = 0e456 /* Displays "1" */
0e123 == 0e456 /* Displays "0" */
The preceding numbers are valid for input data at all times. The results of calculations are returned in
either conventional or exponential form, depending on the setting of NUMERIC DIGITS. If the number of
places needed before the decimal point exceeds DIGITS, or the number of places after the point exceeds
twice DIGITS, exponential form is used. The exponential form REXX generates always has a sign
following the Eto improve readability. If the exponent is 0, then the exponential part is omitted—that is, an
exponential part of E+0 is never generated.
You can explicitly convert numbers to exponential form, or force them to be displayed in long form, by
using the FORMAT built-in function (see page 185).
Scientific notation is a form of exponential notation that adjusts the power of ten so a single nonzero digit
appears to the left of the decimal point. Engineering notationis a form of exponential notation in which
from one to three digits (but not simply 0) appear before the decimal point, and the power of ten is always
expressed as a multiple of three. The integer part may, therefore, range from 1through 999. You can
control whether Scientific or Engineering notation is used with the instruction:
 NUMERIC FORM
SCIENTIFIC
ENGINEERING
expression
VALUE
; 
Scientific notation is the default.
Numbers and Arithmetic
Chapter 16. Numbers and Arithmetic 223
/* after the instruction */
Numeric form scientific
123.45 * 1e11 -> 1.2345E+13
/* after the instruction */
Numeric form engineering
123.45 * 1e11 -> 12.345E+12
Numeric Information
To determine the current settings of the NUMERIC options, use the built-in functions DIGITS, FORM, and
FUZZ. These functions return the current settings of NUMERIC DIGITS, NUMERIC FORM, and NUMERIC
FUZZ, respectively.
Whole Numbers
Within the set of numbers REXX understands, it is useful to distinguish the subset defined as whole
numbers. A whole number in REXX is a number that has a decimal part that is all zeros (or that has no
decimal part). In addition, it must be possible to express its integer part simply as digits within the
precision set by the NUMERIC DIGITS instruction. REXX would express larger numbers in exponential
notation, after rounding, and, therefore, these could no longer be safely described or used as whole
numbers.
Numbers Used Directly by REXX
As discussed, the result of any arithmetic operation is rounded (if necessary) according to the setting of
NUMERIC DIGITS. Similarly, when REXX directly uses a number (which has not necessarily been
involved in an arithmetic operation), the same rounding is also applied. It is just as though the number had
been added to 0.
In the following cases, the number used must be a whole number, and the largest number you can use is
999999999.
vThe positional patterns in parsing templates (including variable positional patterns)
vThe power value (right hand operand) of the power operator
vThe values of exprr and exprf in the DO instruction
vThe values given for DIGITS or FUZZ in the NUMERIC instruction
vAny number used in the numeric option in the TRACE instruction.
Errors
Two types of errors may occur during arithmetic:
vOverflow or Underflow
This error occurs if the exponential part of a result would exceed the range that the language processor
can handle, when the result is formatted according to the current settings of NUMERIC DIGITS and
NUMERIC FORM. The language defines a minimum capability for the exponential part, namely the
largest number that can be expressed as an exact integer in default precision. Because the default
precision is 9, VM supports exponents in the range -999999999 through 999999999.
Because this allows for (very) large exponents, overflow or underflow is treated as a syntax error.
vInsufficient storage
Storage is needed for calculations and intermediate results, and on occasion an arithmetic operation
may fail because of lack of storage. This is considered a terminating error as usual, rather than an
arithmetic error.
Numbers and Arithmetic
224 CICS TS for VSE/ESA: REXX Guide
Chapter 17. Conditions and Condition Traps
Acondition is a specified event or state that CALL ON or SIGNAL ON can trap. A condition trap can
modify the flow of execution in a REXX program. Condition traps are turned on or off using the ON or OFF
subkeywords of the SIGNAL and CALL instructions (see section “CALL” on page 135 and section
“SIGNAL” on page 164).
 CALL
SIGNAL
OFF condition
ON condition
NAME trapname
; 
condition and trapname are single symbols that are taken as constants. Following one of these
instructions, a condition trap is set to either ON (enabled) or OFF (disabled). The initial setting for all
condition traps is OFF.
If a condition trap is enabled and the specified condition occurs, control passes to the routine or label
trapname if you have specified trapname. Otherwise, control passes to the routine or label condition. CALL
or SIGNAL is used, depending on whether the most recent trap for the condition was set using CALL ON
or SIGNAL ON, respectively.
Note: If you use CALL, the trapname can be an internal label, a built-in function, or an external routine. If
you use SIGNAL, the trapname can be only an internal label.
The conditions and their corresponding events that can be trapped are:
ERROR
raised if a command indicates an error condition upon return. It is also raised if any command
indicates failure and neither CALL ON FAILURE nor SIGNAL ON FAILURE is active. The condition is
raised at the end of the clause that called the command but is ignored if the ERROR condition trap is
already in the delayed state. The delayed state is the state of a condition trap when the condition has
been raised but the trap has not yet been reset to the enabled (ON) or disabled (OFF) state. See note
3 on page 227.
CALL ON ERROR and SIGNAL ON ERROR trap all positive return codes, and negative return codes
only if CALL ON FAILURE and SIGNAL ON FAILURE are not set.
FAILURE
raised if a command indicates a failure condition upon return. The condition is raised at the end of the
clause that called the command but is ignored if the FAILURE condition trap is already in the delayed
state.
CALL ON FAILURE and SIGNAL ON FAILURE trap all negative return codes from commands.
HALT
raised if an external attempt is made to interrupt and end execution of the program. The condition is
usually raised at the end of the clause that was being processed when the external interruption
occurred.
NOVALUE
raised if an uninitialized variable is used:
vAs a term in an expression
vAs the name following the VAR subkeyword of a PARSE instruction
vAs a variable reference in a parsing template, a PROCEDURE instruction, or a DROP instruction.
Note: SIGNAL ON NOVALUE can trap any uninitialized variables except tails in compound
variables.
© Copyright IBM Corp. 1992, 2010 225
/* The following does not raise NOVALUE. */
signal on novalue
a.=0
say a.z
say ’NOVALUE is not raised.’
exit
novalue:
say ’NOVALUE is raised.’
You can specify this condition only for SIGNAL ON.
SYNTAX
raised if any language processing error is detected while the program is running. This includes all
kinds of processing errors, including true syntax errors and “run-time” errors, such as attempting an
arithmetic operation on nonnumeric terms. You can specify this condition only for SIGNAL ON.
Any ON or OFF reference to a condition trap replaces the previous state (ON, OFF, or DELAY, and any
trapname) of that condition trap. Thus, a CALL ON HALT replaces any current SIGNAL ON HALT (and a
SIGNAL ON HALT replaces any current CALL ON HALT), a CALL ON or SIGNAL ON with a new trap
name replaces any previous trap name, any OFF reference disables the trap for CALL or SIGNAL, and so
on.
Action Taken When a Condition Is Not Trapped
When a condition trap is currently disabled (OFF) and the specified condition occurs, the default action
depends on the condition:
vFor HALT and SYNTAX, the processing of the program ends, and a message (see Appendix A, “Error
Numbers and Messages,” on page 379) describing the nature of the event that occurred usually
indicates the condition.
vFor all other conditions, the condition is ignored and its state remains OFF.
Action Taken When a Condition Is Trapped
When a condition trap is currently enabled (ON) and the specified condition occurs, instead of the usual
flow of control, a CALL trapname or SIGNAL trapname instruction is processed automatically. You can
specify the trapname after the NAME subkeyword of the CALL ON or SIGNAL ON instruction. If you do
not specify a trapname, the name of the condition itself (ERROR, FAILURE, HALT, NOTREADY,
NOVALUE, or SYNTAX) is used.
For example, the instruction call on error enables the condition trap for the ERROR condition. If the
condition occurred, then a call to the routine identified by the name ERROR is made. The instruction call
on error name commanderror would enable the trap and call the routine COMMANDERROR if the
condition occurred.
The sequence of events, after a condition has been trapped, varies depending on whether a SIGNAL or
CALL is processed:
vIf the action taken is a SIGNAL, execution of the current instruction ceases immediately, the condition is
disabled (set to OFF), and the SIGNAL takes place in exactly the same way as usual (see page 164).
If any new occurrence of the condition is to be trapped, a new CALL ON or SIGNAL ON instruction for
the condition is required to re-enable it when the label is reached. For example, if SIGNAL ON SYNTAX
is enabled when a SYNTAX condition occurs, then, if the SIGNAL ON SYNTAX label name is not found,
a usual syntax error termination occurs.
vIf the action taken is a CALL (which can occur only at a clause boundary), the CALL is made in the
usual way (see page 135) except that the call does not affect the special variable RESULT. If the
routine should RETURN any data, then the returned character string is ignored.
Conditions and Condition Traps
226 CICS TS for VSE/ESA: REXX Guide
Because these conditions (ERROR, FAILURE, and HALT) can arise during execution of an INTERPRET
instruction, execution of the INTERPRET may be interrupted and later resumed if CALL ON was used.
As the condition is raised, and before the CALL is made, the condition trap is put into a delayed state.
This state persists until the RETURN from the CALL, or until an explicit CALL (or SIGNAL) ON (or OFF)
is made for the condition. This delayed state prevents a premature condition trap at the start of the
routine called to process a condition trap. When a condition trap is in the delayed state it remains
enabled, but if the condition is raised again, it is either ignored (for ERROR, FAILURE, or NOTREADY)
or (for the other conditions) any action (including the updating of the condition information) is delayed
until one of the following events occurs:
1. A CALL ON or SIGNAL ON, for the delayed condition, is processed. In this case a CALL or SIGNAL
takes place immediately after the new CALL ON or SIGNAL ON instruction has been processed.
2. A CALL OFF or SIGNAL OFF, for the delayed condition, is processed. In this case the condition trap
is disabled and the default action for the condition occurs at the end of the CALL OFF or SIGNAL
OFF instruction.
3. A RETURN is made from the subroutine. In this case the condition trap is no longer delayed and the
subroutine is called again immediately.
On RETURN from the CALL, the original flow of execution is resumed (that is, the flow is not affected
by the CALL).
Notes:
1. You must be extra careful when you write a syntax trap routine. Where possible, put the routine
near the beginning of the program. This is necessary because the trap routine label might not be
found if there are certain scanning errors, such as a missing ending comment. Also, the trap routine
should not contain any statements that might cause more of the program in error to be scanned.
Examples of this are calls to built-in functions with no quotation marks around the name. If the
built-in function name is in uppercase and is enclosed in quotation marks, REXX goes directly to the
function, rather than searching for an internal label.
2. In all cases, the condition is raised immediately upon detection. If SIGNAL ON traps the condition,
the current instruction is ended, if necessary. Therefore, the instruction during which an event occurs
may be only partly processed. For example, if SYNTAX is raised during the evaluation of the
expression in an assignment, the assignment does not take place. Note that the CALL for ERROR,
FAILURE, HALT, and NOTREADY traps can occur only at clause boundaries. If these conditions
arise in the middle of an INTERPRET instruction, execution of INTERPRET may be interrupted and
later resumed. Similarly, other instructions, for example, DO or SELECT, may be temporarily
interrupted by a CALL at a clause boundary.
3. The state (ON, OFF, or DELAY, and any trapname) of each condition trap is saved on entry to a
subroutine and is 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 set up by the caller.
See the CALL instruction (page 135) for details of other information that is saved during a
subroutine call.
4. The state of condition traps is not affected when an external routine is called by a CALL, even if the
external routine is a REXX program. On entry to any REXX program, all condition traps have an
initial setting of OFF.
5. While user input is processed during interactive tracing, all condition traps are temporarily set OFF.
This prevents any unexpected transfer of control—for example, should the user accidentally use an
uninitialized variable while SIGNAL ON NOVALUE is active. For the same reason, a syntax error
during interactive tracing does not cause exit from the program but is trapped specially and then
ignored after a message is given.
6. The system interface detects certain execution errors either before execution of the program starts
or after the program has ended. SIGNAL ON SYNTAX cannot trap these errors.
Note that a label is a clause consisting of a single symbol followed by a colon. Any number of
successive clauses can be labels; therefore, multiple labels are allowed before another type of clause.
Conditions and Condition Traps
Chapter 17. Conditions and Condition Traps 227
Condition Information
When any condition is trapped and causes a SIGNAL or CALL, this becomes the current trapped
condition, and certain condition information associated with it is recorded. You can inspect this information
by using the CONDITION built-in function (see page 178).
The condition information includes:
vThe name of the current trapped condition
vThe name of the instruction processed as a result of the condition trap (CALL or SIGNAL)
vThe status of the trapped condition
vAny descriptive string associated with that condition.
The current condition information is replaced when control is passed to a label as the result of a condition
trap (CALL ON or SIGNAL ON). Condition information is saved and restored across subroutine or function
calls, including one because of a CALL ON trap. Therefore, a routine called by a CALL ON can access the
appropriate condition information. Any previous condition information is still available after the routine
returns.
Descriptive Strings
The descriptive string varies, depending on the condition trapped.
ERROR
The string that was processed and resulted in the error condition.
FAILURE
The string that was processed and resulted in the failure condition.
HALT Any string associated with the halt request. This can be the null string if no string was provided.
NOVALUE
The derived name of the variable whose attempted reference caused the NOVALUE condition.
The NOVALUE condition trap can be enabled only using SIGNAL ON.
SYNTAX
Any string the language processor associated with the error. This can be the null string if you did
not provide a specific string. Note that the special variables RC and SIGL provide information on
the nature and position of the processing error. You can enable the SYNTAX condition trap only by
using SIGNAL ON.
Special Variables
A special variable is one that may be set automatically during processing of a REXX program. There are
three special variables: RC, RESULT, and SIGL. None of these has an initial value, but the program may
alter them. (For information about RESULT, see page 161.)
The Special Variable RC
For ERROR and FAILURE, the REXX special variable RC is set to the command return code, as usual,
before control is transferred to the condition label.
For SIGNAL ON SYNTAX, RC is set to the syntax error number.
The Special Variable SIGL
Following any transfer of control because of a CALL or SIGNAL, the program line number of the clause
causing the transfer of control is stored in the special variable SIGL. Where the transfer of control is
because of a condition trap, the line number assigned to SIGL is that of the last clause processed (at the
current subroutine level) before the CALL or SIGNAL took place. This is especially useful for SIGNAL ON
SYNTAX when the number of the line in error can be used, for example, to control a text editor. Typically,
Conditions and Condition Traps
228 CICS TS for VSE/ESA: REXX Guide
code following the SYNTAX label may PARSE SOURCE to find the source of the data, then call an editor
to edit the source file positioned at the line in error. Note that in this case you may have to run the
program again before any changes made in the editor can take effect.
Alternatively, SIGL can be used to help determine the cause of an error (such as the occasional failure of
a function call) as in the following example:
signal on syntax
a=a+1 /*This is to create a syntax error */
say ’SYNTAX error not raised’
exit
/* Standard handler for SIGNAL ON SYNTAX */
syntax:
say ’REXX error’ rc ’in line’ sigl’:’ "ERRORTEXT"(rc)
say "SOURCELINE"(sigl)
trace ?r; nop
This code first displays the error code, line number, and error message. It then displays the line in error,
and finally drops into debug mode to let you inspect the values of the variables used at the line in error.
Conditions and Condition Traps
Chapter 17. Conditions and Condition Traps 229
230 CICS TS for VSE/ESA: REXX Guide
Chapter 18. REXX/CICS Text Editor
REXX/CICS provides a general purpose CICS-based text editor, patterned after VM/CMS XEDIT.
The editor is provided so that execs and data can be created, updated, and viewed from within the CICS
environment.
The REXX/CICS editor includes several prefix commands (for example: C, CC, M, MM, B, A, F, P) in
common with the XEDIT editor. To use the editor, enter EDIT.
While in an editor session, commands entered on the command line can be chained by placing a “;”
between each command. Support is also provided for macros written in REXX. This lets you customize
editor settings with a profile exec, add new commands to the editor, or use the editor facilities as part of
an application.
Note: The REXX/CICS Text Editor does not support binary files.
Invocation
You can start a REXX/CICS edit session from a CICS terminal (clear screen), a REXX/CICS session,
another edit session, or a REXX exec. You can enter the editor by executing the CICS EDIT transaction
identifier (or your site-defined transaction identifier for the REXX/CICS editor). From a clear REXX/CICS
screen enter EDIT followed by a REXX File System (RFS) file identifier and an edit session is issued for
this file.
Note: If you specify REXX as a CICS transaction identifier with no exec name, the IBM supplied
REXXTRY interactive utility (CICRXTRY exec) is issued. REXXTRY provides an interactive shell for
performing REXX statements and commands.
While you are in the editor, you can start another edit session by entering EDIT fileid. The syntax for this
method of invocation is defined in the EDIT command, section “EDIT” on page 240. When you write an
exec, you can start the REXX/CICS editor session by issuing the CICS EDIT transaction identifier as a
command. If a file ID is not specified when you invoke the editor, the file ID defaults to file NONAME in
your current RFS directory. A fully qualified file ID is: poolid:\dir1\dir2\fn.ft
However, you can specify a partial file ID if the target file is in (or is going to be created in) your current
directory (as specified by the CD command).
Examples of how you can call the editor:
EDIT TEST.EXEC (From terminal using CICS transaction ID EDIT)
EDIT TEST.EXEC (From within an edit session using the EDIT editor command)
’EDIT TEST.EXEC’ (From within an exec using the EDIT command)
’EDIT TEST.EXEC’ (From terminal in a REXX/CICS REXXTRY session)
This example shows four different ways to start an edit session. The first example starts a session from
REXX/CICS. The second starts a new session from an existing session. The third starts a session from a
REXX exec. The fourth starts a session from a REXX/CICS REXXTRY session.
© Copyright IBM Corp. 1992, 2010 231
Screen Format
When you call the editor without a profile, the default screen definition is displayed as shown in the
following figure.
EDIT ---- POOL1:\USERS\USER1\TEST ------------------------------- COLUMN 1 73
COMMAND ===>
00000 ***************************** TOP OF DATA ************************
00001
00002
00003
00004
00005
00006
00007
00008
00009
00010
00011
00012
00013 **************************** BOTTOM OF DATA **********************
F1=HELP F2=LADD F3=FIL F4=SPLT F5=F F6=JN F7=BA F8=FWD F10=LFT F11=RGT F12=QUI
The first line is reserved for the title line that contains the following:
vFully qualified file ID
vColumn numbers
vDisplayed messages.
The informational lines that let you know where the top and bottom of the file is are the only lines that are
displayed when you bring up a new edit session. These lines consist of a prefix area and a data area.
The line where “*** TOP OF DATA ***” is displayed, in this example, is the current line. This is
distinguished, from the rest, by being highlighted and it is the line most of the command line commands
affect. The command line lets you interact with the editor on a high level basis. All of the screen lines,
except for the title line, may be moved for convenience.
Prefix Commands
Several prefix commands are provided by the editor. These commands are entered in the prefix area and
give you the ability to copy, move, insert, delete, and replicate lines on either an individual or a
consecutive block basis.
Individual Line Commands
The following commands work with individual lines and consist of one character:
/Specify current line in file
IInsert a line
DDelete a line
CCopy a line
MMove a line
RReplicate a line
"Synonym for replicate
When you enter one of the previous commands in the prefix area of a line, the command performs its
respective function on that line. If you enter an “I” in the prefix area of line 00000, the editor opens a new
Text Editor
232 CICS TS for VSE/ESA: REXX Guide
line just below it for input. You can also append a number to the end of the prefix command. This acts as
a replication factor. If the number “5” is appended to the “I”, five lines are opened for input instead of one.
Consecutive Block Commands
The following commands work with consecutive blocks of lines and consist of two characters:
DD Delete a block of lines
CC Copy a block of lines
MM Move a block of lines
RR Replicate a block of lines
"" Synonym for replicate
Block commands are processed in pairs. You place one command in the prefix area of the first line of the
block and place the same command in the prefix area of the last line of the block. For example, to delete
a block of lines, you place a “DD” in the prefix area of line 00001 and another “DD” in the prefix area of
line 00005. This deletes all lines between line 00001 and line 00005, inclusive. The only block prefix
command that allows a replication factor is the replicate command. So, when you specify a number with
the replicate block command you need to know how many times you want the block (not individual lines)
replicated. The replication factor must be specified with the first RR replication command.
Destination Commands
The following commands are called destination prefix commands:
AAfter
BBefore
FFollowing
PPreceding
These commands give the move and copy prefix commands a destination for a block of text. When you
enter these in the prefix area, the text from a copy or a move is placed either before or after that line
according to what destination command is specified. The replicate prefix command does not use a
destination prefix command. Instead, it places its output immediately after the block that is to be replicated.
Macros Under the REXX/CICS Editor
The editor supports REXX macros, giving the macros the ability to alter the editor settings and display the
editor screens. Macros can process all of the editor command line commands.
Text Editor
Chapter 18. REXX/CICS Text Editor 233
Example:
/* Macro to alter the setting of the REXX/CICS editor */
ADDRESS EDITSVR
’SET NUMBERS OFF’
’SET CURLINE 10’
’SET MSGLINE 2’
’SET CMDLINE TOP’
’SET CASE MIXED IGNORE’
This example addresses the editor command environment and alters the editor settings.
Example:
/* Macro to use the REXX/CICS editor as an I/O interface */
ADDRESS EDITSVR
’INPUT Some’
’INPUT More’
’INPUT DATA’
’DISPLAY’
This example enters the text Some,More, and DATA on three separate lines and then displays the current
edit screen.
Command Line Commands
The syntax and description for each of the command line commands follows.
ARBCHAR
 ARBCHAR arbchar 
ARBCHAR sets the arbitrary characters.
Operands
arbchar
specifies a printable (typeable) character.
Return Codes
0Normal return
202 Invalid operand
Example
’ARBCHAR .’
This example defines the character “.” as being the arbitrary character.
Note
The arbitrary character takes the place of text in a string. The default value for the arbchar is a “.”. For
more information, on how you can do searches with the arbitrary character, see the FIND command,
section “FIND” on page 242.
ARGS
 ARGS
(1)
arguments

Text Editor
234 CICS TS for VSE/ESA: REXX Guide
Notes:
1Ifarguments is not specified, any previously defined arguments are deleted.
ARGS stores the default parameters to be passed to the program being edited when invoked with the text
editor EXEC command.
Operands
arguments
specifies the parameter string to be passed. If you do not specify arguments, any previously defined
arguments are deleted.
Return Codes
0Normal return
Example
’ARGSABC’
’EXEC’
’ARGS’
The first line of this example defines the arguments to be passed as A,B, and C. The second line executes
the last saved copy of the file that is currently being edited, passing it the arguments defined in line one.
The last line deletes the arguments.
BACKWARD
 BAckward
1
n
*

BACKWARD scrolls backward toward the beginning of a file for a specified number of screen displays.
Operands
nspecifies the number of screen displays you want to scroll backward. If you specify an asterisk (*), the
screen scrolls to the top of the file and the current line is set to the top of the file. If nis not specified,
the screen scrolls back one display.
Return Codes
0Normal return
202 Invalid operand
Example
’BACKWARD’
This example scrolls one screen toward the top of the file.
Note
The editor, by default, sets PF7 to BACKWARD and PF8 to FORWARD.
BOTTOM
 BOTTOM 
BOTTOM scrolls to the bottom of the file.
Text Editor
Chapter 18. REXX/CICS Text Editor 235
Return Codes
0Normal return
Example
’BOTTOM’
This example scrolls to the bottom of the file.
CANCEL
 CANCEL 
CANCEL ends the current edit session without saving the changes.
Return Codes
0Normal return
210 Request failed
Example
’CANCEL’
This example quits the current editor session unconditionally, without saving any file changes.
Notes
1. CANCEL lets you exit the editor without saving changes, and without any warning messages that
changes have been made.
2. CANCEL is a synonym for QQUIT.
CASE
 CASE
(1)
MIXED RESPECT
IGNORE
UPPER RESPECT
IGNORE

Notes:
1 The default is set in the user profile.
CASE sets the case translation and interpretation preferences.
Operands
UPPER
translates lowercase characters to uppercase when entered.
MIXED
works with each character in its original form.
RESPECT
respects the case of each character while doing a search.
IGNORE
ignores the case of each character while doing a search.
Text Editor
236 CICS TS for VSE/ESA: REXX Guide
Return Codes
0Normal request
202 Invalid operand
Example
’CASE MIXED RESPECT’
This example sets the case to MIXED and the sensitivity to RESPECT. For more information on sensitivity,
see the FIND command, section “FIND” on page 242.
CHANGE
 CHANGE /string1/string2/
ALL

CHANGE changes a string in the file.
Operands
string1
specifies the string being replaced.
string2
specifies the string that replaces string1.
ALL
is a keyword indicating that all occurrences on all lines, from the current line, to the end of the file, are
changing.
/is the delimiting character.
Return Codes
0Normal return
202 Invalid operand
210 Request failed
223 Search argument not found
Example
’CHANGE /noeditor/editor/’
This example replaces the first occurrence of noeditor with editor.
Note
The CHANGE command respects the sensitivity settings of the editor when locating string1 and when
changing string2 as defined by the CASE command or the system default.
CMDLINE
 CMDLINE TOP
BOTTOM

CMDLINE sets the command line display preferences.
Operands
TOP
displays the command line on the second line of the screen.
Text Editor
Chapter 18. REXX/CICS Text Editor 237
BOTTOM
displays the command line on the bottom line of the screen.
Return Codes
0Normal return
202 Invalid operand
Example
’CMDLINE TOP’
This example places the command line on the second line of the screen.
CTLCHAR
 CTLCHAR character
OFF
ESCAPE
PROTECT
NOPROTECT
OFF

CTLCHAR sets a control character's function.
Operands
character
specifies a control character to use.
OFF
drops all definitions of control characters if OFF is used without specifying a character or drops the
specific character if one is specified.
ESCAPE
specifies that the following character in the string, passed to the RESERVED command, is a control
character.
PROTECT
specifies that the string passed to the RESERVED command is protected from user input.
NOPROTECT
specifies that user input, passed to the RESERVED command, is allowed on this string.
Return Codes
0Normal return
202 Invalid operand
Example
’CTLCHAR ! ESCAPE’
’CTLCHAR % PROTECT’
’RESERVED 20 HIGH !% Important Info’
This example defines !as the escape character and %as the field protection character. After you enter
these commands, the screen line 20 will be protected and contain the text that follows the control
characters, !%.
CURLINE
 CURLINE number 
CURLINE sets the current line display preferences.
Text Editor
238 CICS TS for VSE/ESA: REXX Guide
Operands
number
specifies the screen line number.
Return Codes
0Normal return
202 Invalid operand
Example
’CURLINE 3’
This example sets the current display line to screen line 3.
Note
The current line is displayed at the screen line number specified in this command. However, the current
line cannot be displayed on line 1 because line 1 is reserved for the title line.
DISPLAY
 DISPLAY 
DISPLAY shows the current edit screen.
Return Codes
0Normal return
210 Request failed
Example
’DISPLAY’
This example displays the current edit screen.
Note
The DISPLAY command is only useful when it runs from a macro. It displays the current edit session's
screen. When it runs from a normal terminal edit session there is no noticeable effect.
DOWN
 DOWN
1
number

DOWN scrolls forward in the file.
Operands
number
specifies the number of lines to scroll. If you do not specify number, the screen moves down only one
line.
Return Codes
0Normal return
202 Invalid operand
Text Editor
Chapter 18. REXX/CICS Text Editor 239
Example
’DOWN 5’
This example scrolls forward through the file five lines.
EDIT
 EDIT
NONAME
fileid
lib.sublib(mem.type) LIB
( MACRO macroname

EDIT opens a new edit session.
Operands
fileid
specifies the file ID of the file to be created or edited.
lib.sublib(mem.type)
specifies a VSE Librarian sublibrary and member to be edited.
LIB
is a keyword that follows a VSE Librarian sublibrary member name when a sublibrary member is being
edited.
MACRO
is a keyword specifying a group of instructions applied to the file being edited.
macroname
specifies the file name portion of the profile macro file ID (REXX exec name).
Return Codes
0Normal return
203 File not found
204 Not authorized
211 Invalid file ID
226 File is currently being edited
299 Internal error
Example
’EDIT TEST.EXEC’
This example opens an edit session for the file TEST.EXEC.
Notes
1. The directory used when editing a file, is determined as follows:
vIf a fully qualified directory ID is explicitly given, then it is always used.
vIf a partially qualified file ID is specified, then the current directory and path are searched in an
attempt to find an existing file that would match the file ID (if it were fully resolved using that
directory name).
– If such a match is successful, then the edit session is for an existing file and the file ID is fully
resolved using the directory the file was found in.
– If the file is not located in the search order, then an edit session for a new file is created, with the
fully resolved file ID specifying the current working directory (as specified by the CD command).
2. A VSE Librarian sublibrary member is distinguished by using the keyword LIB after the member name.
Members must be enclosed in parentheses, quotes are not allowed.
Text Editor
240 CICS TS for VSE/ESA: REXX Guide
3. The default user profile macro that the editor tries to call is CICEPROF. The CICEPROF macro creates
an ISPF/PDF like environment. A second profile macro, named CICXPROF, is provided. CICXPROF
creates a VM/CMS XEDIT like environment.
4. If a file ID or VSE Librarian sublibrary member name is not specified, an RFS file with the special
name, NONAME, is created.
EXEC
 EXEC
(1)
REXX_program
arguments

Notes:
1IfREXX_program is not specified, the last saved copy of the file that is currently being edited is
executed.
EXEC executes a REXX program within an editor session.
Operands
REXX_program
specifies the REXX program name to execute. If you do not specify a name, the last saved copy of
the file that is currently being edited will be executed. If any arguments have been defined using the
ARGS command, these will be passed.
arguments
specifies the arguments to be passed to the program specified in the REXX_program operand.
Return Codes
nspecifies the return code set by the exit of the called exec
0Normal return
-3 Exec not found
-10 Exec name not specified
-11 Invalid exec name
-12 GETMAIN error
-99 Internal error
Example
’EXEC TEST1.EXECXYZ’
This example executes program TEST1.EXEC and passes X,Y, and Zas arguments.
FILE
 FILe
(1)
fileid

Notes:
1Iffileid is not specified, the file is saved as the default file ID.
FILE saves the current file being edited.
Text Editor
Chapter 18. REXX/CICS Text Editor 241
Operands
fileid
specifies the file ID of the file. If you do not specify fileid, the file is saved as the default file ID.
Return Codes
0Normal return
202 Invalid operand
204 Not authorized
207 Insufficient space in file pool
210 Request failed
Example
’FILE’
This example saves the current file being edited, using the current file ID specification for the edit session.
The current file ID is initially taken from the file ID specified on the edit command, when an edit session is
created.
FIND
 Find
previous_searcharg
searcharg

FIND locates a string of text in the file.
Operands
searcharg
specifies the text string to be searched on. If you do not specify searcharg, a search is performed on
the previous search string (previous_searcharg).
Return Codes
0Normal return
202 Invalid operand
223 Search argument not found
Examples
’FIND REDT’
This example finds the first occurrence of REDT.
’FIND Redt’
If CASE is set to RESPECT then this example will not find the first occurrence of REDT. It will find the first
occurrence of Redt. For more information, see the CASE command, section “CASE” on page 236.
The searcharg can contain the arbitrary character, in which case the arbitrary character represents any
text string which might be imbedded at the arbitrary character's location.
’FIND ONE.THREE’
This example finds the first occurrence of any string with ONE and THREE joined by another string.
Notes
1. When the RESPECT flag is set with the CASE command, the case of the searcharg is respected.
Text Editor
242 CICS TS for VSE/ESA: REXX Guide
2. The search begins at the current line and continues downward until BOTTOM OF DATA is reached, or
a match is made. If BOTTOM OF DATA is reached without a match, then the current line remains
where it was before the FIND was processed, rather than making BOTTOM OF DATA the current line.
FORWARD
 FORward
1
n
*

FORWARD scrolls forward toward the end of the file for a specified number of screen displays.
Operands
nspecifies the number of screen displays you want to scroll forward. If you specify an asterisk (*), the
screen scrolls to the bottom of the file and the current line is set to the last line of data. If nis not
specified, the screen scrolls forward one display.
Return Codes
0Normal return
202 Invalid operand
Example
’FORWARD’
This example scrolls one screen toward the end of the file.
Note
The editor, by default, sets PF7 to BACKWARD and PF8 to FORWARD.
GET
 GET
fileid

GET imports an RFS file into the current edit session.
Operands
fileid
specifies the file ID of the file.
Return Codes
0Normal return
203 File not found
204 Not authorized
210 Request failed
Example
’GET POOL1:\USERS\USER1\TEST.EXEC’
This example pulls the REXX File System file TEST.EXEC in after the current line.
GETLIB
Text Editor
Chapter 18. REXX/CICS Text Editor 243
 GETLIB lib.sublib(mem.type) 
GETLIB imports a member from a VSE Librarian sublibrary into the current edit session. The file is
inserted after the current line.
Operands
lib.sublib(mem.type)
specifies a VSE Librarian sublibrary and member name.
Return Codes
0Normal return
203 File not found
204 Not authorized
210 Request failed
237 CICSEXC1 Link error
238 CICSEXC1 return code was invalid
Example
’GETLIB MYSLIB.PROJ1(MEM1.PROC)’
This example gets member MEM1.PROC from sublibrary MYSLIB.PROJ1 and puts it after the current line
in an edit session.
Note: GETLIB is the VSE equivalent of the GETPDS function available with CICS/ESA.
INPUT
 Input
(1)
text

Notes:
1Iftext is not specified, the new line is blank.
INPUT inserts a new line after the current line.
Operands
text
specifies the text being inserted on the new line. If you do not specify text, the new line is blank.
Return Codes
0Normal return
Example
’INPUT Test Input Data’
This example places the text Test Input Data on a newly inserted line after the current line.
JOIN
 JOIN 
JOIN joins two lines into one.
Text Editor
244 CICS TS for VSE/ESA: REXX Guide
Return Codes
0Normal return
210 Request failed
Example
’JOIN’
This example joins the line that the cursor is on with the line immediately following it.
LEFT
 LEFT
1
number

LEFT scrolls left in the file.
Operands
number
specifies the number of characters to scroll. If you do not specify number, the screen scrolls left one
character in the file. If you specify 0for number, the file scrolls to the far left side.
Return Codes
0Normal return
202 Invalid operand
210 Request failed
Example
’LEFT 20’
This example scrolls 20 characters to the left.
LINEADD
 LINEADD 
LINEADD adds a blank line after the cursor line.
Return Codes
0Normal return
230 Cursor is not in file area
Example
’PFKEY 2 LINEADD’
This example causes the addition of a blank line after the line where the cursor resides (if it is a file line)
whenever PF2 is pressed.
Note
LINEADD is mainly useful when assigned to a program function (PF) key. It is by default assigned to PF2.
LPREFIX
 LPREFIX prefix 
Text Editor
Chapter 18. REXX/CICS Text Editor 245
LPREFIX enters a prefix command into the current line prefix area.
Operands
prefix
specifies any standard prefix (such a C, CC, M, MM, B, A) that is entered during an edit session.
Return Codes
0Normal return
202 Invalid operand
Example
’LPREFIX D’
This example causes the deletion of the current file line.
Note
LPREFIX is provided to let you use the prefix commands from within edit macros.
MACRO
 MACRO fileid 
MACRO calls a macro.
Operands
fileid
specifies the file ID of the macro you want to run. If this file ID includes a file type suffix, then an
attempt is made to call an exec with that suffix. Otherwise, an attempt is made to call an exec whose
suffix is EXEC.
Return Codes
nspecifies the return code set by the exit of the called exec
0Normal return
-3 Exec not found
-10 Exec name not specified
-11 Invalid exec name
-12 GETMAIN error
-99 Internal error
Example
’MACRO POOL1:\USERS\USER1\TEST’
This example calls the macro, POOL1:\USERS\USER1\TEST.EXEC.
Note
Macros have the ability to make calls to the REXX/CICS editor server. Any command that you can enter
from the command line of the editor can be run from a macro.
MSGLINE
 MSGLINE
number
OFF
INFO

MSGLINE sets the message line display preferences.
Text Editor
246 CICS TS for VSE/ESA: REXX Guide
Operands
number
displays the message line on the corresponding screen line.
OFF
does not display the message line.
INFO
displays messages in the header line.
Return Codes
0Normal return
202 Invalid operand
Example
’MSGLINE 2’
This example places the message line on screen line 2.
NULLS
 NULLS ON
OFF

NULLS controls whether the fields on the screen will be written with trailing blanks or trailing nulls.
Operands
ON specifies that fields on the screen are written with trailing nulls.
OFF
specifies that fields on the screen are written with trailing blanks.
Return Codes
0Normal return
202 Invalid operand
Example
’NULLS ON’
This example causes trailing nulls on the fields of the screen.
NUMBERS
 NUMbers ON
OFF

NUMBERS sets the prefix area display preferences.
Operands
ON displays sequential numbers in the prefix area.
OFF
displays equal signs in the prefix area.
Return Codes
0Normal return
202 Invalid operand
Text Editor
Chapter 18. REXX/CICS Text Editor 247
Example
’NUMBERS ON’
This example displays sequential numbers in the prefix area.
Note
Line number sequencing is not done on the data within the edit session, but are pseudo line numbers
associated with the file lines during the edit session only.
PFKEY
 PFkey
(1)
number
text

Notes:
1Iftext is not specified, the PF key is processed.
PFKEY sets or processes a program function (PF) key.
Operands
number
specifies the PF key that is set or processed.
text
specifies the text that the PF key is set to. If you do not specify text, the PF key is processed.
Return Codes
0Normal return
202 Invalid Operand
229 Number out of range
Example
’PFKEY 3 quit’
’PFKEY 3’
This example first sets PFKEY 3 to quit and then processes the PF key.
PFKLINE
 PFKLINE TOP
BOTTOM
number
OFF

PFKLINE sets the program function (PF) key line display preferences.
Operands
TOP
displays the PF key line on the second line of the screen.
BOTTOM
displays the PF key line on the bottom line of the screen.
number
specifies the screen line number.
Text Editor
248 CICS TS for VSE/ESA: REXX Guide
OFF
removes the PF key from the display screen.
Return Codes
0Normal return
202 Invalid operand
Example
’PFKLINE BOTTOM’
This example places the PF key line on the bottom line of the screen.
QQUIT
 QQuit 
QQUIT ends the current edit session without saving changes.
Return Codes
0Normal return
Example
’QQUIT’
This example quits the current editor session unconditionally, without saving any file changes.
Notes
1. QQUIT lets you exit the editor without saving changes, and without any warning messages that
changes have been made.
2. A synonym for QQUIT is CANCEL.
QUERY
 QUERY CHANGES
CMDLINE
COLUMN
DIR
FILEID
MSGLINE
NULLS
NUMBERS
PFKLINE
PFKEY.n
RECORDS

QUERY displays the current settings of the editor.
Operands
CHANGES
displays the number of modifications to the file since it was last saved.
CMDLINE
displays the current setting of the command line. For more information see the Text Editor command,
section “CMDLINE” on page 237.
COLUMN
displays the starting column in the file that is displayed on the screen.
Text Editor
Chapter 18. REXX/CICS Text Editor 249
DIR
displays the directory that is associated with the file.
FILEID
displays the name of the file being edited.
MSGLINE
displays the current setting of the message line. For more information see the Text Editor command,
section “MSGLINE” on page 246.
NULLS
displays the current setting of NULLS. For more information see the Text Editor command, section
“NULLS” on page 247.
NUMBERS
displays the current setting of NUMBERS. For more information see the Text Editor command, section
“NUMBERS” on page 247.
PFKLINE
displays the current setting of the PFKLINE. For more information see the Text Editor command,
section “PFKLINE” on page 248.
PFKEY.n
displays the command that is processed if PFKEY nis pressed. The nis any number from 1 to 24.
RECORDS
displays the number of lines in the file.
Return Codes
0Normal return
202 Invalid operand
236 Not defined
Example
’QUERY PFKEY.1’
This example displays the command that is processed when PFKEY 1 is pressed.
QUIT
 QUIT 
QUIT ends the current edit session.
Return Codes
0Normal return
210 Request failed
Example
’QUIT’
This example exits the editor.
Note
When the current file has been changed, the editor does not let you exit until either a save is done or you
enter the QQUIT command.
RESERVED
Text Editor
250 CICS TS for VSE/ESA: REXX Guide
 REServed line HIGH
NOHIGH
OFF
text

RESERVED reserves a line on the screen for your output.
Operands
line
specifies the line that is reserved and the text is displayed.
HIGH
is a keyword specifying that the text is highlighted.
NOHIGH
is a keyword specifying that the text is the usual intensity.
OFF
is a keyword specifying that the line is freed from its reserved state.
text
specifies a string of text, with optional control characters, that is displayed on the reserved line.
Return Codes
0Normal return
202 Invalid operand
210 Request failed
229 Number out of range
Example
’CTLCHAR ! ESCAPE’
’CTLCHAR % PROTECT’
’RESERVED 20 HIGH !% Important Info’
This example displays Important Info in a high intensity, protected field on screen line 20.
RESET
 RESET 
RESET terminates any pending prefix commands.
Return Codes
0Normal return
Example
’RESET’
This example cancels all pending prefix commands.
RIGHT
 RIght
1
number

RIGHT scrolls right in the file.
Text Editor
Chapter 18. REXX/CICS Text Editor 251
Operands
number
specifies the number of characters to scroll. If you do not specify number, the screen scrolls to the
right one character in the file. If you specify 0for number, the file scrolls to the far right.
Return Codes
0Normal return
202 Invalid operand
Example
’RIGHT 20’
This example scrolls 20 characters to the right in the file.
Note
If the value you specified causes a target outside of the record, scrolling stops at the right side of the
record.
SAVE
 Save
(1)
fileid

Notes:
1Iffileid is not specified, the file is saved as the default file ID.
SAVE saves a file to an RFS file or VSE Librarian sublibrary member.
Operands
fileid
specifies the file ID of the file. If you do not specify fileid, the file is saved as the default file ID.
Return Codes
0Normal return
202 Invalid operand
207 Insufficient space in file pool
210 Request failed
Example
’SAVE SYSTEM:\USERS\USER1\TEST.EXEC’
This example saves the current file to the RFS and names it, SYSTEM:\USERS\USER1\TEST.EXEC.
SORT
 SORT *
num
A
D
1
fromcol
tocol

SORT sorts the lines from the current line on down.
Text Editor
252 CICS TS for VSE/ESA: REXX Guide
Operands
*specifies that all the lines from the current line to the end of the file are sorted.
num
specifies that the lines from the current line for the value of num are sorted.
Aspecifies that the lines are sorted in ascending order. (This is the default.)
Dspecifies that the lines are sorted in descending order.
fromcol
specifies that the lines are sorted on data beginning in this column. If you do not specify fromcol tocol,
sorting begins at the first column.
tocol
specifies that the lines are sorted on data ending in this column.
Return Codes
0Normal return
202 Invalid operand
229 Number out of range
Example
’SORT*A510’
This example sorts all lines in the file from the current line down and is sorted on columns 5 to 10.
Note
If you sort a large number of lines, the sort will work very slowly.
SPLIT
 SPLIT 
SPLIT splits a line into two lines.
Return Codes
0Normal return
210 Request failed
Example
’SPLIT’
This example splits the line, that the cursor is on, into two lines. One line contains all the text on that line
to the left of the cursor and the line following contains the remaining text (under and to the right of the
cursor).
STRIP
 STRIP 
STRIP strips the trailing blanks off all file lines.
Return Codes
0Normal return
Text Editor
Chapter 18. REXX/CICS Text Editor 253
Example
’STRIP’
This example strips all trailing blanks of each file line.
SYNONYM
 SYNONYM syn
command

SYNONYM assigns a command action to any other valid command.
Operands
syn
specifies any valid command that executes the command action for which it is a synonym.
command
specifies any valid command.
Return Codes
0Normal return
Example
’SYNONYM GL GETLIB’
This example makes GL equivalent to the command GETLIB.
TOP
 TOP 
TOP scrolls to the top of the file.
Return Codes
0Normal return
Example
’TOP’
This example scrolls to the top of the file.
TRUNC
 TRUNC column 
TRUNC truncates each line in the file to the given length.
Operands
column
specifies the last column you want to keep.
Return Codes
0Normal return
202 Invalid operand
Text Editor
254 CICS TS for VSE/ESA: REXX Guide
Example
’TRUNC 72’
This example truncates all lines in the file to a length of 72 characters.
Note
This command is useful when you are working with data sets that have sequence numbers that require
removing. The editor does not currently have support for placing or maintaining sequence numbers in a
file.
UP
 UP
1
number

UP scrolls backward in the file (towards the top of the file).
Operands
number
specifies the number of lines to scroll. If you do not specify number, the default scroll amount is set to
1.
Return Codes
0Normal return
202 Invalid operand
Example
’UP 20’
This example scrolls 20 lines backward in the file.
Text Editor
Chapter 18. REXX/CICS Text Editor 255
256 CICS TS for VSE/ESA: REXX Guide
Chapter 19. REXX/CICS File System
The REXX File System (RFS) is provided for the storage of text files and execs created with the
REXX/CICS editor, and by execs using RFS commands and data imported from outside of the REXX File
System. RFS was modeled after the Advanced Interactive Executive (AIX®) and OS/2 file systems. The
concept of directories is the main idea taken from these environments. Partitioning each directory into
several subdirectories will give a hierarchical organization.
You can access RFS functions by using the RFS command. In addition to providing the ability to perform
file I/O, the RFS command provides you the ability to do essential file system maintenance.
A file list utility (FLST) is provided as a full screen interface to the REXX File System. This utility can also
be used as a platform where other CICS work can be performed.
File Pools, Directories, and Files
File pools are sets of VSAM files. The first VSAM file in the pool contains information about the pool and
must be formatted before data can be written to the pool. All other VSAM files in the pool are extensions
of the first file and only need to be defined in the pool's list of VSAM files after they have been allocated
and defined to Access Method Services and CICS. VSAM files can be added to a file pool, at will, to
provide additional storage space in that pool. However, defining and adding space to file pools is a task for
REXX/CICS administrators or CICS Systems Programmers. File pools are given a unique one to seven
character name.
In each file pool, there is a root directory. The root directory for a file pool is named file_pool_name:\. This
directory can contain files as well as subdirectories. A subdirectory is a directory within another directory.
Subdirectories can be created within any other directory. A new directory can be created with the RFS
MKDIR command. All directories, except the root, are distinguished by a one to eight character directory
file name joined, by a period, with an optional one to eight character directory file type. This is called the
directory ID.
A file pool may be defined to be a user or non-user file pool. One directory that should exist in all user file
pools is the USERS directory. This directory contains several subdirectories that correspond to the users
on the system. When you save a file into the RFS for the first time, a new subdirectory is created in the
USERS directory. This new directory is named with your user ID if you are signed onto CICS. Otherwise,
the directory name will default to the CICS DFLTUSER value. After this directory is created, you can
create any number of subdirectories within that personal directory. You can place files in any of the
directories that you create.
Files are either data files or REXX execs. They use the same naming conventions as directories (a file
name and an optional file type joined with a period). The default file type for REXX execs is EXEC. Files
are created with the REXX/CICS editor or with the RFS DISKW command.
A fully qualified file ID consists of a file pool name followed by a :\, each directory's ID in the path followed
by a \, and the file ID, that is comprised of a file name and an optional file type.
The following example shows a fully qualified file ID. POOL1 is the file pool name, USERS and USER1
are directory ID's, and TEST.EXEC is the file ID.
Example:
POOL1:\USERS\USER1\TEST.EXEC
The following example shows file pools, directories, and files.
© Copyright IBM Corp. 1992, 2010 257
Example:
POOL1: File Pool
\ Root Directory
TEST1.EXEC File
USERS\ Subdirectory
USER1\ Subdirectory
TEST2.EXEC File
DOCS\ Subdirectory
TEST3.DOCUMENT File
USER2\ Subdirectory
LETTER.DOCUMENT File
PROJECT1\ Subdirectory
PROD1.EXEC File
DATA\ Subdirectory
PROD1.DATA File
WORK:\ File Pool and Root Directory
TEST1.DATA File
CHARTS\ Subdirectory
CHART1.DATA File
CHART2.DATA File
This example shows two file pools (POOL1 and WORK). File pool POOL1 contains a file (TEST1.EXEC)
and two subdirectories (USERS and PROJECT1). Inside the USERS subdirectory are two subdirectories
(USER1 and USER2) that correspond to user IDs (USER1 and USER2). User USER1 has a file
(TEST2.EXEC) and a subdirectory (DOCS) inside its directory. Inside the DOCS subdirectory there is
another file (TEST3.DOCUMENT). User USER2 has a file (LETTER.DOCUMENT) inside its directory. File
pool WORK contains a file (TEST1.DATA) and a subdirectory (CHARTS). Inside subdirectory CHARTS are
two files (CHART1.DATA and CHART2.DATA).
Current Directory and Path
The current directory is the current working directory, and is first in the search order when working with
REXX File System (RFS). The current directory can be set using the CD command, see section “CD” on
page 321. The CD command has a similar format to the IBM Personal Computer OS/2 and IBM Personal
Computer DOS CD commands. The syntax is CD followed by the partially or fully qualified directory name.
To change from a subdirectory back to the parent directory, type CD ... To change to another subdirectory,
CD can be followed by the subdirectory name.
In the following example, the first command sets the current directory to POOL1:\USERS\USER1 and the
second command sets the current directory to POOL1:\USERS\USER1\DOCS. The third command
changes the current directory back to POOL1:\USERS\USER1.
Example:
’CD POOL1:\USERS\USER1’
’CD DOCS’
’CD ..’
The PATH command is used to define the search order for REXX execs, after the current directory is
searched. See the PATH command, section “PATH” on page 361, for more information. The syntax is:
PATH, followed by a list, separated by spaces, of fully qualified directory names.
The following example first sets a current directory, then defines the search order.
Example:
’CD POOL1:\USERS\USER1\EXECS’
’PATH POOL1:\ POOL1:\USERS\USER1’
’EXEC TEST2.EXEC’
The exec name is fully qualified, using the directory ID of each directory in the search before the search of
each respective directory is performed. The fully qualified names are as follows:
File System
258 CICS TS for VSE/ESA: REXX Guide
’POOL1:\USERS\USER1\EXECS\TEST2.EXEC’
’POOL1:\TEST2.EXEC’
’POOL1:\USERS\USER1\TEST2.EXEC’
When the REXX/CICS command EXEC is invoked, all three directories above are searched resulting in
REXX/CICS finding the exec in the POOL1:\USERS\USER1 directory. If TEST2.EXEC existed in the
POOL1:\ directory, RFS would have stopped searching when it was found. The first copy found in the
search order is accessed.
Note: Whenever a file name is not fully qualified, RFS follows the search order looking for the exec,
beginning with the current directory. The first copy found is executed. If none are found, then an
error is returned indicating the target file or exec was not found.
Security
There are two general types of REXX/CICS File System security:
vFile access security controls access to execs and data. RFS file security can be controlled at two
levels; the CICS level, and at the RFS directory level.
1. At the CICS level, authorization to access file pool VSAM files can be given to specific users. This
gives a high level of security.
2. At the RFS directory level, user directories are private directories and can be accessed only by the
owning user (by default).
However, the owner of a directory can use the RFS AUTH command to define a directory as being
publicr, publicw, or secured. Publicr means any other REXX/CICS user has read/only access to this
directory. Publicw means any other REXX/CICS user has read/write access to this directory. Secured
means that the RFS security exit will be invoked to determine if access should be allowed. For more
information, see the RFS AUTH command, section “AUTH.” Non-user directories can be created and
their access levels defined by an authorized user.
vCommand execution security controls the use of certain REXX/CICS command, or command
keywords. For more information, on this type of REXX/CICS security, see Appendix H, “Security,” on
page 421.
RFS commands
Under the RFS command environment you issue commands to interface with RFS. If you set the
command environment to RFS, you should not specify RFS in front of RFS commands.
Example:
’RFS DISKR POOL1:\USERS\USER1\TEST.EXEC DATA.’
This example reads the contents of the RFS file TEST.EXEC into the REXX compound variable DATA.
TEST.EXEC is in the fully qualified directory: POOL1:\USERS\USER1\.
The syntax for the RFS commands follow.
AUTH
 RFS
PRIVATE
AUTH dirid
PUBLICR
PUBLICW
SECURED

AUTH authorizes access to RFS directories.
File System
Chapter 19. REXX/CICS File System 259
Operands
dirid
specifies a REXX File System directory identifier. This is partially or fully qualified. See the CD
command, “CD” on page 321, for more information.
PRIVATE
specifies that only the owner of the directory has read/write access to the files. This is the default.
PUBLICR
specifies that any user has read-only access to the files in the directory.
PUBLICW
specifies that any user has read/write access to the files in the directory.
SECURED
specifies that an external security manager grants access to the files in the directory.
Return Codes
See the RFS command, section “RFS” on page 363.
Example
’RFS AUTH POOL1:\USERS\USER1\DOCS PUBLICR’
This example makes directory DOCS a public directory. All users have read/only access to the files in
directory DOCS.
CKDIR
 RFS CKDIR dirid 
CKDIR checks for an existing RFS directory level.
Operands
dirid
specifies a REXX File System directory identifier. This is partially or fully qualified. See the CD
command, section “CD” on page 321, for more information.
Return Codes
See the RFS command, section “RFS” on page 363.
Example
’RFS CKDIR POOL1:\USERS\USER1\DOCS’
This example checks for a directory called DOCS in the existing directory POOL1:\USERS\USER1.
CKFILE
 RFS CKFILE fileid 
CKFILE checks to see if the specified, partially or fully qualified, file ID exists.
Operands
fileid
specifies the file identifier.
Return Codes
See the RFS command, section “RFS” on page 363.
File System
260 CICS TS for VSE/ESA: REXX Guide
Example
'CKFILE POOL1:\USERS\USER1\TEST.EXEC'
This example checks for a file called TEST.EXEC in the existing directory POOL1:\USERS\USER1.
COPY
 RFS COPY fileid1 fileid2 
COPY copies a file.
Operands
fileid1
specifies the source file identifier, it may be a fully or partially qualified directory and file identifier.
fileid2
specifies the target file identifier, it may be a fully or partially qualified directory and file identifier.
Note: If the target file (fileid2) already exists, the contents of fileid1 replaces it.
Return Codes
See the RFS command, section “RFS” on page 363.
Example
’RFS COPY POOL1:\USERS\USER1\TEST1.EXEC POOL1:\USERS\USER1\TEST2.EXEC’
This example copies TEST1.EXEC to TEST2.EXEC within the directory POOL1:\USERS\USER1.
DELETE
 RFS DELETE fileid 
DELETE deletes an RFS file.
Operands
fileid
specifies the name of the file to be deleted. This may be partially or fully qualified.
Return Codes
See the RFS command, section “RFS” on page 363.
Example
’RFS DELETE POOL1:\USERS\USER1\TEST1.EXEC’
This example deletes file TEST1.EXEC within directory POOL1:\USERS\USER1.
DISKR
 RFS DISKR
DATA.
fileid
stem.

DISKR reads records from an RFS file.
File System
Chapter 19. REXX/CICS File System 261
Operands
fileid
specifies the file identifier.
stem.
specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 for
more information. The default stem is DATA..
Return Codes
See the RFS command, section “RFS” on page 363.
Example
’RFS DISKR POOL1:\USERS\USER1\TEST.DATA DATA.’
This example stores the entire contents of the RFS file POOL1:\USERS\USER1\TEST.DATA in the DATA.
REXX compound variable.
Note
DATA.0 is set to the number of records read from the file. DATA.ncontains the nth record read from the
file.
DISKW
 RFS DISKW
DATA.
fileid
stem.

DISKW writes records to an RFS file from a stem. The file is overlaid with the data in the stem.
Operands
fileid
specifies the file identifier.
stem.
specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 for
more information. The default stem is DATA..
Return Codes
See the RFS command, section “RFS” on page 363.
Example
’RFS DISKW POOL1:\USERS\USER1\TEST.EXEC DATA.’
This example stores the contents of the DATA. REXX compound variable into the RFS file
POOL1:\USERS\USER1\TEST.EXEC.
Note
Set DATA.0 to the number of records to be written to the file.
GETDIR
 RFS GETDIR stem.
dirid

GETDIR returns a list of the contents of the current or specified directory into the specified REXX array.
File System
262 CICS TS for VSE/ESA: REXX Guide
Operands
stem.
specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 for
more information.
dirid
specifies a REXX File System directory level identifier. This is partially or fully qualified. See the CD
command, section “CD” on page 321, for more information.
Return Codes
See the RFS command, section “RFS” on page 363.
Example
'RFS GETDIR DIRDOC. POOL1:\USERS\USER1\DOCS'
This example places the contents of directory DOCS in the DIRDOC. REXX compound variable.
MKDIR
 RFS MKDIR dirid 
MKDIR creates a new RFS directory level.
Operands
dirid
specifies a REXX File System directory identifier. This is partially or fully qualified. See the CD
command, section “CD” on page 321, for more information.
Return Codes
See the RFS command, section “RFS” on page 363.
Example
’RFS MKDIR POOL1:\USERS\USER1\DOCS’
This example creates a new directory called DOCS in the existing directory POOL1:\USERS\USER1.
Note
Only authorized users can create directories outside of their \USERS\userid directory structure.
RDIR
 RFS RDIR dirid 
RDIR removes the specified RFS directory.
Operands
dirid
specifies a REXX File System directory identifier. This is partially or fully qualified. Refer to the CD
command, section “CD” on page 321, for more information.
Return Codes
Refer to the RFS command, section “RFS” on page 363.
File System
Chapter 19. REXX/CICS File System 263
Example
’RFS RDIR POOL1:\USERS\USER1\DOCS’
This example deletes a directory called DOCS in the existing directory POOL1:\USERS\USER1.
RENAME
 RFS RENAME fileid1 fileid2 
RENAME renames an RFS file to a new name.
Operands
fileid1
specifies the source file identifier, it may be a fully or partially qualified directory and file identifier.
fileid2
specifies the source target file identifier, it may be a fully or partially qualified directory and file
identifier.
Note: If the target file (fileid2) already exists, the contents of fileid1 replaces it.
Return Codes
See the RFS command, section “RFS” on page 363.
Example
’RFS RENAME POOL1:\USERS\USER1\TEST1.EXEC POOL1:\USERS\USER1\TEST2.EXEC’
This example renames the file POOL1:\USERS\USER1\TEST1.EXEC to POOL1:\USERS\USER1\
TEST2.EXEC.
File List Utility
The File List Utility (FLST) provides a full screen interface to the REXX File System. When running, FLST
manages RFS, calls an exec, or starts a transaction. It is meant to be a high level interface to REXX,
RFS, and CICS.
Invocation
When you want to run FLST, go to a cleared CICS screen or a cleared REXX/CICS screen, enter FLST
and FLST starts running. The FLST screen format follows.
File System
264 CICS TS for VSE/ESA: REXX Guide
USER=USER1 - DIRECTORY=\USERS\USER1
CMD FILENAME FILETYPE ATTRIBUTES RECORDS SIZE DATE TIME
TEST1 EXEC FILE 11 1 1994/03/27 10:30:29
TEST2 EXEC FILE 5 1 1994/03/27 10:31:04
COMMAND ===>
F1=HELP F2=REFRESH F3=END F7=UP 18 F8=DOWN 18 F11=EDIT F12=CANCEL
Your user ID is displayed in the upper left hand corner. The current directory is displayed beside your
user ID. The rest of the screen looks very similar to a REXX/CICS editor session. FLST uses the editor for
all I/O except for the first two lines that are displayed using the RESERVED command in the editor. The
advantages of using the REXX/CICS editor for the I/O shell are seen in the ability to search for a file name
or file type in a large directory and your ability to save the directory to a file on disk.
Macros under the REXX/CICS File List Utility
The REXX File List Utility supports REXX macros, giving the macros the ability to alter the FLST settings
and display the FLST screens. Macros can process all of the FLST commands.
The following example addresses the FLST environment and alters the FLST settings.
Example:
/* Macro to set some FLST settings */
ADDRESS FLSTSVR
’SET PFKEY 11 EDIT’
’SET PFKEY 12 CANCEL’
’SYNONYM DISCARD RFS DELETE’
FLST Commands
This section describes the FLST commands. You can type these commands anywhere on the source
FLST command column or from the command line.
Note: If data is entered in multiple places, program function keys take precedence, followed by data
entered on the command line, and finally data entered on the command column.
CANCEL
When you type CANCEL from the command line use the following syntax:
 CANCEL 
CANCEL terminates without executing any commands in the command column.
File System
Chapter 19. REXX/CICS File System 265
CD
When you type CD from the command line use the following syntax:
 CD
dirid

CD changes the current directory.
Operands
dirid
specifies a REXX File System directory level identifier. This is partially or fully qualified. See the CD
command, section “CD” on page 321, for more information.
Example
’CD TEMP’
This example changes the current directory to TEMP and updates the FLST display.
COPY
When you type COPY on the FLST command column use the following syntax:
 COPY / fileid 
COPY copies a file.
Operands
fileid
specifies the file ID of the file where the results are placed.
Note: If fileid already exists, it is replaced.
Example
’COPY / TEST3.EXEC’
This example, executed from the command column next to TEST1.EXEC, creates a new file,
TEST3.EXEC, that is identical to TEST1.EXEC.
When you type COPY from the command line use the following syntax:
 COPY fileid1 fileid2 
Operands
fileid1
specifies the file ID of the file the command acts on.
fileid2
specifies the file ID of the file where the results are placed.
Note: If fileid2 already exists, the contents of fileid1 replaces it.
Example
’COPY TEST1.EXEC TEST3.EXEC’
This example, executed from the command line, creates a new file (TEST3.EXEC) that is identical to
TEST1.EXEC.
File System
266 CICS TS for VSE/ESA: REXX Guide
DELETE
When you type DELETE on the FLST command column use the following syntax:
 DELETE 
DELETE deletes a file.
When you type DELETE from the command line use the following syntax:
 DELETE fileid 
Operands
fileid
specifies the file ID of the file the command acts on.
Example
’DELETE TEST1.EXEC’
This example, executed from the command line, deletes file TEST1.EXEC.
DOWN
When you type DOWN from the command line use the following syntax:
 DOWN
n

DOWN scrolls down one or more lines.
Operands
nspecifies the number of lines to be scrolled down.
Example
’DOWN 5’
This example scrolls forward through the list five lines.
END
When you type END from the command line use the following syntax:
 END 
END executes all commands you typed, then terminates when END is typed on the command line or used
as a PF key.
EXEC
When you type EXEC on the FLST command column use the following syntax:
 EXEC
/parameter

EXEC executes the exec, then terminates.
File System
Chapter 19. REXX/CICS File System 267
Operands
parameter
specifies the parameters passed to the exec as arguments.
Example
’EXEC / PARMS’
This example, executed on the command column next to TEST3.EXEC, executes exec TEST3.EXEC and
passes PARMS as the argument.
When you type EXEC from the command line use the following syntax:
 EXEC fileid
parameter

Operands
fileid
specifies the file ID of the file the command acts on.
parameter
specifies the parameters passed to the exec as arguments.
Return Codes
nspecifies the return code set by the exit of the called exec
0Normal return
-3 Exec not found
-10 Exec name not specified
-11 Invalid exec name
-12 GETMAIN error
-99 Internal error
Example
’EXEC TEST3 PARMS’
This example executes exec TEST3.EXEC and passes PARMS as the argument.
FLST
When you type FLST from the command line use the following syntax:
 FLST
dirid

FLST calls the file list utility.
Operands
dirid
specifies the ID of a full or partial directory. If you do not specify dirid, FLST defaults to the current
working directory.
Example
’FLST’
This example displays the file list for the member of the current working directory.
File System
268 CICS TS for VSE/ESA: REXX Guide
Note
See Chapter 19, “REXX/CICS File System,” on page 257 for more information about the REXX File
System.
MACRO
When you type MACRO from the command line use the following syntax:
 MACRO fileid 
MACRO calls a macro.
Operands
fileid
specifies the file ID of the macro you want to run. If this file ID includes a file type suffix, then an
attempt is made to call an exec with that suffix. Otherwise, an attempt is made to call an exec whose
suffix is EXEC.
Return Codes
nspecifies the return code set by the exit of the called exec
0Normal return
-3 Exec not found
-10 Exec name not specified
-11 Invalid exec name
-12 GETMAIN error
-99 Internal error
Example
’MACRO POOL1:\USERS\USER1\TEST’
This example calls the macro, POOL1:\USERS\USER1\TEST.EXEC.
Note
Macros have the ability to make calls to the REXX/CICS FLST server. Any command that can be entered
from the command line of the FLST can be run from a macro.
PFKEY
When you type PFKEY from the command line use the following syntax:
 PFkey number
text

PFKEY sets or processes a program function (PF) key.
Operands
number
specifies the PF key that is set or processed.
text
specifies the text that the PF key is set to.
Example
’PFKEY 3 quit’
’PFKEY 3’
This example first sets PFKEY 3 to quit and then processes the PF key.
File System
Chapter 19. REXX/CICS File System 269
Note
If you specify text, the PF key is set with the text. If you do not specify text, the PF key is processed.
REFRESH
When you type REFRESH on the FLST command column use the following syntax:
 REFRESH 
REFRESH refreshes the file list.
Example
’REFRESH’
This example refreshes the file list for the member of the current working directory.
RENAME
When you type RENAME on the FLST command column use the following syntax:
 RENAME / fileid 
RENAME renames a file.
Operands
fileid
specifies the new file ID.
Note: If fileid already exists, it is replaced.
Example
’RENAME / TEST4.EXEC’
This example, executed from the command column next to TEST3.EXEC, renames TEST3.EXEC to
TEST4.EXEC.
When you type RENAME from the command line use the following syntax:
 RENAME fileid1 fileid2 
Operands
fileid1
specifies the file ID of the file the command acts on.
fileid2
specifies the new file ID.
Note: If fileid2 already exists, the contents of fileid1 replaces it.
Example
’RENAME TEST3.EXEC TEST4.EXEC’
This example, executed from the command line, renames file TEST3.EXEC to TEST4.EXEC.
File System
270 CICS TS for VSE/ESA: REXX Guide
SORT
When you type SORT from the command line use the following syntax:
 SORT
DT
FN
FT
AT
RC
SZ

SORT sorts the file list.
Operands
DT specifies sorting the files by date/time. (This is the default.)
FN specifies sorting the files by file name.
FT specifies sorting the files by file type.
AT specifies sorting the files by attribute.
RC specifies sorting the file by number of records.
SZ specifies sorting the files by size.
Example
’SORT FN’
This example sorts the file list by file name.
SYNONYM
When you type SYNONYM from the command line use the following syntax:
 SYNONYM syn
command

SYNONYM assigns a command action to any other valid command.
Operands
syn
specifies any valid command that executes the command action for which it is a synonym.
command
specifies any valid command.
Example
’SYNONYM DISCARD RFS DELETE’
This example makes DISCARD equivalent to the RFS command DELETE.
File System
Chapter 19. REXX/CICS File System 271
UP
When you type UP from the command line use the following syntax:
 UP
n

UP scrolls up one or more lines.
Operands
nspecifies the number of lines to be scrolled up.
Example
’UP 5’
This example scrolls backward through the list five lines.
FLST Return Codes
FLST uses the standard return codes for the REXX/CICS File System, except where it is specified
differently. See the RFS command, section “RFS” on page 363 for more information.
Running Execs and Transactions from FLST
Most REXX/CICS execs can be run from FLST by simply entering the exec name. The exec name with its
arguments is entered on the command line, or the exec name is typed on a FLST command column. The
latter case uses the file ID as the argument for the transaction. REXX execs are run by issuing an
EXECUTE command either on the command line, in which case a file ID is needed, or on a FLST
command column.
File System
272 CICS TS for VSE/ESA: REXX Guide
Chapter 20. REXX/CICS List System
REXX/CICS provides a facility for maintaining tables or lists of data in virtual storage. This facility is called
the REXX List System (RLS). This system provides management of lists of temporary system and user
information. The externals for accessing the RLS are the RLS and CLD commands, instead of RFS and
CD commands used with the REXX File System. Also, the RLS is for data only, not for execs.
Directories and Lists
RLS has one root directory. You access the RLS system by reading its anchor address from a CICS
temporary storage queue named *CICREX*. This queue contains one item after the first access of RLS.
This item contains the address of an area of 6 fullwords. It contains RLS control information and a pointer
to the root directory. The root directory RLS is named \. This directory can contain lists, saved variables, or
special lists called queues as well as subdirectories. A subdirectory is a directory within another directory.
Subdirectories can be created within any other directory. A new directory can be created with the RLS
MKDIR command. All directories, except the root, are distinguished by a one to 250 character directory file
name. This is called the directory ID.
One RLS directory that always exists is the USERS directory. This directory contains several
subdirectories which correspond to the users on the system. When you save a list into the RLS for the first
time, a new subdirectory may be created in the USERS directory. This new directory is named with your
user ID if you are signed onto CICS. Otherwise, the directory name defaults to the value in CICS
DFLTUSER. After this directory is created, you can create any number of subdirectories within that
personal directory. You can place lists in any of the directories that you create.
Lists are always data files. They use the same naming conventions as directories.
A fully qualified list ID consists of a \, each directory's ID in the path followed by a \, and the list ID.
The following example shows a fully qualified list ID. USERS and USER1 are directory ID's, and
TEST.DATA is the list ID.
Example:
\USERS\USER1\TEST.DATA
© Copyright IBM Corp. 1992, 2010 273
The following example shows RLS directories and lists.
Example:
\ Root Directory
TEST1.DATA File
USERS\ Subdirectory
USER1\ Subdirectory
TEST2.DATA File
DOCS\ Subdirectory
TEST3.DOCUMENT File
USER2\ Subdirectory
LETTER.DOCUMENT File
PROJECT1\ Subdirectory
PROD1.INFO File
DATA\ Subdirectory
PROD1.DATA File
\ Root Directory
TEST1.DATA File
CHARTS\ Subdirectory
CHART1.DATA File
CHART2.DATA File
This example shows a list directory structure. The root directory contains a file (TEST1.DATA) and two
subdirectories (USERS and PROJECT1). Inside the USERS subdirectory are two subdirectories (USER1
and USER2) that correspond to user IDs (USER1 and USER2). User USER1 has a list (TEST2.DATA) and
a subdirectory (DOCS) inside its directory. Inside the DOCS subdirectory there is another list
(TEST3.DOCUMENT). User USER2 has a file (LETTER.DOCUMENT) inside its directory. The root
directory contains a file (TEST1.DATA) and a subdirectory (CHARTS). Inside subdirectory CHARTS are
two files (CHART1.DATA and CHART2.DATA).
Current Directory and Path
The current list directory is the current working directory, and is first in the search order when working with
REXX List System (RLS). The current list directory can be set using the CLD command, see section “CLD”
on page 325. The syntax is CLD followed by the fully or partially qualified directory name. To change from a
subdirectory back to the parent directory, type CLD ... To change to another subdirectory, CLD can be
followed by the subdirectory name.
In the following example, the first command sets the current directory to \USERS\USER1 and the second
command sets the current directory to \USERS\USER1\DOCS. The third command changes the current
directory back to \USERS\USER1.
Example:
CLD \USERS\USER1
CLD DOCS
CLD ..
Note: If CLD is never specified the default directory is \SYSTEM\nnnnnnnn\. where nnnnnnnn is an
internal REXX task number.
Security
The RLS commands are authorized REXX/CICS commands. This means they may only be executed by
an authorized user or from within an exec loaded from an authorized library.
RLS commands
Under the RLS command environment you issue commands to interface with RLS. If you set the
command environment to RLS, you should not specify RLS in front of RLS commands.
List System
274 CICS TS for VSE/ESA: REXX Guide
Example:
’RLS READ \USERS\USER1\TEST.DATA DATA.’
This example reads the contents of the RLS list \USERS\USER1\TEST.DATA into the DATA. REXX
compound variable.
The syntax for the RLS commands follow.
CKDIR
 RLS CKDIR dirid 
CKDIR checks for an existing RLS directory level.
Operands
dirid
specifies a REXX List System directory level identifier. This is partially or fully qualified. See the CLD
command, section “CLD” on page 325, for more information.
Return Codes
See the RLS command, section “RLS” on page 366.
Example
’RLS CKDIR \USERS\USER1\DOCS’
This example checks for a directory called DOCS in the existing directory \USERS\USER1.
DELETE
 RLS DELETE listname 
DELETE deletes an RLS list.
Operands
listname
specifies a REXX List System list identifier. This is partially or fully qualified. See the CLD command,
section “CLD” on page 325, for more information.
Return Codes
See the RLS command, section “RLS” on page 366.
Example
’RLS DELETE \USERS\USER1\TEST.DATA’
This example deletes RLS list TEST.DATA.
LPULL
 RLS
*QUEUE*
LPULL varname
queid

LPULL pulls a record from the top of the RLS queue.
List System
Chapter 20. REXX/CICS List System 275
Operands
varname
specifies a simple REXX variable name. It does not end in a period, distinguishing a variable name
from a stem name.
*QUEUE*
is a keyword specifying the special default name.
queid
specifies the identifier for a special type of RLS list accessed by LPULL, LPUSH, or LQUEUE.
Return Codes
See the RLS command, section “RLS” on page 366.
Example
’RLS LPULL VARA QUEUE1’
This example pulls a record from the top of the RLS queue QUEUE1.
LPUSH
 RLS
*QUEUE*
LPUSH varname
queid

LPUSH pushes a record onto the top of the RLS queue (LIFO).
Operands
varname
specifies a simple REXX variable name. It does not end in a period, distinguishing a variable name
from a stem name.
*QUEUE*
is a keyword specifying the special default name.
queid
specifies the identifier for a special type of RLS list accessed by LPULL, LPUSH, or LQUEUE.
Return Codes
See the RLS command, section “RLS” on page 366.
Example
’RLS LPUSH VARA QUEUE1’
This example pushes a record (the contents of VARA) onto the top of the RLS queue QUEUE1.
LQUEUE
 RLS
*QUEUE*
LQUEUE varname
queid

LQUEUE adds a record to the end of the RLS queue (FIFO).
List System
276 CICS TS for VSE/ESA: REXX Guide
Operands
varname
specifies a simple REXX variable name. It does not end in a period, distinguishing a variable name
from a stem name.
*QUEUE*
is a keyword specifying the special default name.
queid
specifies the identifier for a special type of RLS list accessed by LPULL, LPUSH, or LQUEUE.
Return Codes
See to the RLS command, section “RLS” on page 366.
Example
’RLS LQUEUE VARA QUEUE1’
This example adds a record (the contents of VARA) to the end of the RLS queue QUEUE1.
MKDIR
 RLS MKDIR dirid 
MKDIR creates a new RLS directory level.
Operands
dirid
specifies a REXX List System directory level identifier. This is partially or fully qualified. See the CLD
command, section “CLD” on page 325, for more information.
Return Codes
See the RLS command, section “RLS” on page 366.
Example
’RLS MKDIR \USERS\USER1\DOCS’
This example creates a new directory called DOCS in the existing directory \USERS\USER1.
READ
 RLS READ
DATA.
listname
stem. ( UPD

READ reads records from an RLS list.
Operands
listname
specifies the list identifier.
stem.
specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 for
more information. The default stem is DATA..
UPD
is a keyword that enqueues on a file for update.
List System
Chapter 20. REXX/CICS List System 277
Return Codes
See the RLS command, section “RLS” on page 366.
Example
’RLS READ \USERS\USER1\TEST.DATA DATA.’
This example stores the entire contents of the RLS list \USERS\USER1\TEST.DATA in the DATA. REXX
compound variable.
Note
DATA.0 is set to the number of records read from the list. DATA.ncontains the nth record read from the
list.
VARDROP
 RLS VARDROP varname dirid 
VARDROP deletes an RLS saved variable.
Operands
varname
specifies a simple REXX variable name. It does not end in a period, distinguishing a variable name
from a stem name.
dirid
specifies a REXX List System directory level identifier. This is partially or fully qualified. See the CLD
command, section “CLD” on page 325, for more information.
Return Codes
See the RLS command, section “RLS” on page 366.
Example
’RLS VARDROP VAR1’
This example deletes variable VAR1 from the current directory.
VARGET
 RLS VARGET varname dirid 
VARGET takes an RLS saved variable and copies it into a REXX variable of the same name.
Operands
varname
specifies a simple REXX variable name. It does not end in a period, distinguishing a variable name
from a stem name.
dirid
specifies a REXX List System directory level identifier. This is partially or fully qualified. See the CLD
command, section “CLD” on page 325, for more information.
Return Codes
See the RLS command, section “RLS” on page 366.
Example
’RLS VARGET VAR1’
List System
278 CICS TS for VSE/ESA: REXX Guide
This example copies the value of variable VAR1 from the current directory into a REXX variable named
VAR1.
VARPUT
 RLS VARPUT varname dirid 
VARPUT takes a REXX variable and copies it into an RLS saved variable of the same name.
Operands
varname
specifies a simple REXX variable name. It does not end in a period, distinguishing a variable name
from a stem name.
dirid
specifies a REXX List System directory level identifier. This is partially or fully qualified. See the CLD
command, section “CLD” on page 325, for more information.
Return Codes
See the RLS command, section “RLS” on page 366.
Example
’RLS VARPUT VAR1’
This example takes the value of REXX variable VAR1 and copies it into variable VAR1 in the current
directory.
WRITE
 RLS WRITE
DATA.
listname
stem.

WRITE writes records to an RLS list.
Operands
listname
specifies the list identifier.
stem.
specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 for
more information. The default stem is DATA..
Return Codes
See the RLS command, section “RLS” on page 366.
Example
’RLS WRITE \USERS\USER1\TEST.DATA DATA.’
This example stores the entire contents of the REXX compound variable DATA. into the RLS list
\USERS\USER1\TEST.DATA.
Note
Set DATA.0 to the number of records to be written to the list.
List System
Chapter 20. REXX/CICS List System 279
280 CICS TS for VSE/ESA: REXX Guide
Chapter 21. REXX/CICS Command Definition
The REXX/CICS Command Definition Facility provides a means of easily defining (or redefining) REXX
commands and environments.
Background
One of the greatest strengths of REXX is its extendibility. You can write your own external functions,
subroutines, or commands to extend the capabilities of the REXX language. Because of this, one of the
natural uses for REXX is as an Application Integration platform. REXX/CICS provides you the ability to
seamlessly integrate your Line Of Business (LOB) application facilities, REXX language facilities, CICS
system facilities, and various software products into an integrated software platform.
The two main methods used to extend the REXX language, in order to add function, or to provide an
interface to an external facility or product, are:
vREXX External Functions (or subroutines)
vREXX Commands (sometimes called subcommands).
As an example to distinguish between the two, let's say we want to add the capability to REXX to sort a
REXX array. This could be accomplished, for example, by adding a sort function called ARRYSORT:
x = ARRYSORT(STEM1.)
This could likewise be accomplished by adding a REXX command called ARRYSORT:
’ARRYSORT STEM1.’
Note: In the above command example, it is not necessary to place quotes around the command. It is
however good coding practice to place single or double quotes around portions of command strings
that do not involve REXX variable substitution.
REXX external functions are traditionally used to extend the capabilities of the REXX language, whereas
REXX commands are traditionally used to interface to outside applications, products or system facilities.
However, either method is capable of being used either way.
Some major differences between REXX commands and external functions are:
vFunctions always return a result, commands do not.
vFunctions raise an error condition, commands always set a return code.
Highlights
The Command Definition Facility provides the capability to:
vDefine new commands and environments easily, from a REXX exec.
vShare a common command environment with multiple independent developers.
vWrite new REXX commands in the REXX language.
vChange command's implementation language transparently.
vDefine authorized commands selectively.
vRedefine existing command names (without a code change).
Accomplishing Command Definition
You should use the DEFCMD command to perform basic command definitions that only affect your user
ID. A systems administrator or system programmer should use the DEFSCMD to perform system-wide
REXX/CICS command definitions. The DEFCMD and DEFSCMD commands are used from within a REXX
exec to define or change REXX command definitions. You can add or change your own command
definitions, using the DEFCMD command, without any special authorization. You must be a REXX/CICS
© Copyright IBM Corp. 1992, 2010 281
authorized user to use DEFSCMD to change command definitions that affect other REXX/CICS users. See
section “DEFCMD” on page 332 for more information on the DEFCMD command and section “DEFSCMD”
on page 335 for more information on the DEFSCMD command.
Command Arguments Passed to REXX Programs
When a REXX/CICS command is written in REXX and that command is used, the REXX program (defined
by DEFCMD or DEFSCMD) is either invoked or awakened (from a WAITREQ induced "sleep"). If it is
invoked, then the command string is passed as an argument to the exec. Also, if it is invoked, the very first
WAITREQ command issued (if any) falls through immediately, with the command string being placed in the
REXX variable REQUEST. If the REXX exec was already started earlier and waiting for a request (due to
an earlier WAITREQ command) then the command string is only placed in the REXX variable REQUEST.
Note: Command programs written in REXX can easily get and set the contents of REXX variables in the
REXX exec that caused them to be invoked, by using the C2S and S2C commands. See section
“C2S” on page 331 for more information on the C2S command and section “S2C” on page 373 for
more information on the S2C command.
Command Arguments Passed to Assembler Programs
In addition to the REXX language, REXX/CICS command programs may be written in assembler
language. Assembler language routines must exist in a CICS program properly defined (for example, by
using the CEDA DEFINE PROGRAM command). These programs are invoked by an EXEC CICS LINK if
the CICSLINK option was specified on the DEFCMD or DEFSCMD commands. If the DEFCMD or
DEFSCMD, on the other hand, specifies the CICSLOAD option, then the program is EXEC CICS LOADed
by the first command that causes it to be invoked for the current CICS task, and its load address is
remembered. Any subsequent commands in the same CICS task that use this program performs a direct
branch entry (by an assembler BASSM instruction) into the program. It is recommended that these
assembler programs return control by an assembler BSM instruction so that the correct mode switching (if
any) occurs.
The following describes the contents of the registers when an assembler language command program gets
control, and it describes the parameters upon entry to these programs.
Entry Specifications when DEFCMD CICSLOAD is specified:
When the code for the command program gets control by a direct branch, the contents of the
registers are:
Register 0
Unpredictable
Register 1
Address of the CICPARMS control block
Registers 2-12
Unpredictable
Register 13
Address of 18 fullword register save area
Register 14
Return address
Register 15
Entry point address
Before the program returns to the caller, it should place the return code it wants reflected into the
CICPARMS RETCODE field.
Command Definition
282 CICS TS for VSE/ESA: REXX Guide
Entry Specifications when DEFCMD CICSLINK is specified:
When the code for the command program gets control by an EXEC CICS LINK, the CICS
Commarea contains the CICPARMS control block.
Before the program returns to the caller, it should place the return code it wants reflected into the
CICPARMS RETCODE field.
CICPARMS Control Block
The following table shows the CICPARMS control block for mapping passed parameters to assembler
routines.
Table 4. CICPARMS Control Block
Offset (Decimal) Number of Bytes Field Name Description
0 12 Reserved for IBM use.
12 4 RXWBADDR REXX work block address which is required to be placed into
register 10 before calls to the CICGETV stub routine (for REXX
variable access)
16 8 ENVNAME Internal environment name taken from the DEFCMD or
DEFSCMD command definition
24 16 CICCMD Internal command name taken from the command definition, or
in the case where an asterisk was specified, the actual
command name from the command string
40 4 ARGSTR Address of the command argument string beginning with the
first non-blank character after the command name in the
command string
44 4 ARGLEN Length of above argument string, in characters
48 4 PLIST Address of a standard parsed parameter list of the command
line parsed into 8 character tokens, followed by a end of list
fence of hex high values (X'FFFFFFFFFFFFFFFF')
52 4 EPLIST Address of an extended parameter list which matches up with
the standard PLIST above, but that is in a different format. The
extended PLIST has an 8 byte entry for each token described
above. The first 4 bytes is a fullword address of the start of the
string that comprises a token. The second word contains the
length of a token, in bytes.
56 4 RETCODE Return code to be reflected in the exec immediately after the
execution of the command. This return code is automatically
placed into the special REXX variable RC.
60 4 Reserved for IBM use
64 4 USERWORD For user use so information can be passed across multiple
command routine calls
68 4 Reserved for IBM use
72 4 Reserved for IBM use
76 1 TYPEFLAG One character code that identifies the call type of the DEFCMD
or DEFSCMD definition. The code for REXX is R, for
CICSLINK is C, and for CICSLOAD is L
77 1 ITRACE Internal trace flag. This is a one character code, which has a
value of 0 through 9 to indicate if internal tracing is active and
what level of tracing is active. The value of zero indicates the
normal situation of no tracing. Values from 1 to 9 indicate that
increasingly progressively detailed tracing has been requested.
Command Definition
Chapter 21. REXX/CICS Command Definition 283
Non-REXX Language Interfaces
REXX/CICS makes it possible to transparently convert a REXX process to a non-REXX process. To do
this requires that non-REXX command routines should be able to access REXX variables in the REXX
exec that issued the command to be processed. The routine used to accomplish this is called CICGETV
and must be linkedited with your command routine, and called as is described below.
CICGETV - Call to Get, Set, or Drop a REXX Variable
 CALL CICGETV ,( operands ) 
operands:
varname_addr ,varname_len ,data_addr ,data_len ,function_name
Calls this linkedit stub subroutine from an assembler REXX/CICS command routine, so as to retrieve from,
or set or drop REXX variables in the REXX program that issued the command.
Operands
varname_addr
specifies the address of a character string containing the name of the REXX variable. The variable
name (that this address points to) must be in uppercase.
varname_len
specifies the length of the variable name.
data_addr
specifies the fullword address where the address of variable contents are.
data_len
specifies the length of area pointed to by data_addr (fullword).
function_name
specifies the particular CICGETV function to be performed. There are three choices:
GET retrieves the address and length of a REXX variable.
PUT creates or replaces a REXX variable.
DEL deletes a REXX variable.
Notes
1. Immediately before any call to the CICGETV linkedited routine stub, register 10 must be loaded with
the value of the RXWBADDR field in the passed parms (CICPARMS).
2. If a get request is issued for a variable that does not exist, the value returned is the same as the
variable name.
3. CICGETV uses a standard save area convention with R13 pointing to an 18 fullword length area. R1
points to a standard parameter list. R14 contains the return address. R15, upon entry to CICGETV,
returns CICGETV's entry point. Upon return, R15 contains the return code.
4. The CICGETV module is located in the REXX/CICS distribution library.
5. A return code of zero is reflected to indicate the success of the operation, or a decimal 99 indicating an
internal error (such as a storage limit exceeded situation).
Command Definition
284 CICS TS for VSE/ESA: REXX Guide
Chapter 22. REXX/CICS DB2 Interface
The REXX/CICS DB2 Interface provides a means of executing SQL from a REXX exec. The SQL are
prepared and executed dynamically. The REXX/CICS DB2 interface provides the results of the SQL in
REXX predefined variables.
The REXX/CICS DB2 interface supports DB2 V7.1 and above. This chapter explains how to use the
interface to DB2 from REXX/CICS. If you need more information about SQL, refer to the DB2 SQL
Reference.
The following information is provided in this chapter:
vProgramming considerations
vEmbedding SQL
Programming Considerations
To embed SQL within a REXX exec, the host command environment must be changed. The ADDRESS
instruction, followed by the name of the environment, is used to change the host command environment.
The ADDRESS instruction has two forms; one affects all commands issued after the instruction, and one
affects only a single command. For more information about host command environments, see section
“Changing the Host Command Environment” on page 83 and for more information about the ADDRESS
instruction, see section “ADDRESS” on page 132.
The REXX/CICS command environment that supports the REXX/CICS DB2 is:
EXECSQL
the command environment that supports SQL.
Note: EXECSQL is an authorized commands. You must be a REXX/CICS authorized user to use the
EXECSQL command environment.
REXX/CICS provides an exec called CICRXTRY that can be used to interactively process REXX
statements and commands. CICRXTRY can be pseudo-conversational. The PSEUDO and SETSYS
PSEUDO commands are used to turn pseudo-conversational mode on or off. If the environment is set to
pseudo-conversational, SQL statements issued from CICRXTRY will be committed. If the environment is
set to conversational, any SQL statements issued from the CICRXTRY exec will not be committed and any
resources that are locked will remain locked until you exit the CICRXTRY exec or issue a CICS
SYNCPOINT command. Similar considerations should be made if embedding SQL statements in lengthy
REXX execs.
Embedding SQL Statements
You can use the EXECSQL command environment to process the SQL. Each SQL statement is prepared
and executed dynamically using the CICS/DB2 attachment facility.
You can make each request by writing a valid SQL statement as a REXX command directed to the
EXECSQL environment. The SQL statement is made up of the following elements:
vSQL keywords
vPre-declared identifiers
vLiteral values.
Use the following syntax:
"EXECSQL statement"
or
© Copyright IBM Corp. 1992, 2010 285
ADDRESS EXECSQL
"statement"
"statement"
.
.
.
SQL can exist on more than one line. Each part of the statement is enclosed in quotes and a comma
delimits additional statement text as follows:
ADDRESS EXECSQL
"SQL text",
"additional text",
.
.
.
"final text"
The following rules apply to embedded SQL:
vYou can pass the following SQL directly to the EXECSQL command environment:
ALTER
CREATE
COMMENT ON
DELETE
DROP
EXPLAIN
GRANT
INSERT
LABEL ON
LOCK
REVOKE
SELECT
SET CURRENT SQLID
UPDATE.
vYou cannot use the following SQL:
BEGIN DECLARE SECTION
CLOSE
COMMIT
CONNECT
DECLARE CURSOR
DECLARE STATEMENT
DECLARE TABLE
DESCRIBE
END DECLARE SECTION
EXECUTE
EXECUTE IMMEDIATE
FETCH
INCLUDE
OPEN
PREPARE
ROLLBACK
SET CURRENT PACKAGESET
SET HOST VARIABLE
WHENEVER.
DB2 Interface
286 CICS TS for VSE/ESA: REXX Guide
vHost variables are not allowed within the SQL. Instead, you can use REXX variables to pass input data
to the EXECSQL environment. The REXX variables are not embedded within quotes. The output from
the EXECSQL environment is provided in REXX predefined variables (see section “Receiving the
Results”).
vWhen you code a SQL SELECT statement, you cannot use the INTO clause. Instead, the REXX/CICS
DB2 returns the requested items in compound variables with stem names equal to the DB2 column
names.
vThe default number of rows returned for a SELECT statement is 250. If you need more or less rows,
you can set the REXX variable SQL_SELECT_MAX before issuing the SELECT statement.
Receiving the Results
The EXECSQL command environment returns results in predefined REXX variables. These variables are:
RC Each operation sets this return code. Possible values are:
nSpecifies the SQLCODE if the SQL statement resulted in an error or warning.
0The SQL statement was processed by the EXECSQL environment. The REXX variables
for the SQLCA contain the completion status of the SQL statement.
30 There was not enough memory to build the SQLDSECT variable.
31 There was not enough memory to build the SQL statement area.
32 There was not enough memory to build the SQLDA variable.
33 There was not enough memory to build the results area for the SELECT statement.
SQLCODE etc
A set of SQLCA variables are updated after SQL statements are processed. The entries of the
SQLCA are described in section “Using the SQL Communications Area” on page 288.
SQL_COLNAME.n
Contains the name of each DB2 column whose data was returned by a SELECT statement.
SQL_COLUMNS should be used as the maximum value for n.
SQL_COLTYPE.n
Contains the type of each DB2 column whose data was returned by a SELECT statement.
SQL_COLUMNS should be used as the maximum value for n.
Note: Although all data types are supported, not all are displayable. REXX functions can be used
to convert the data into the format desired.
For information about the meaning of specific SQLTYPE codes found in SQL_COLTYPE, see the
DB2 Server for VSE & VM SQL Reference, SC09-2671.
SQL_COLLEN.n
Contains the length of each DB2 column whose data was returned by a SELECT statement. If the
data type is DECIMAL, the scale is placed after the length of the column (after one blank space).
SQL_COLUMNS should be used as the maximum value for n.
SQL_COLUMNS
Contains the count of the number of columns returned.
column.n
The results of a SQL SELECT statement are stored in these REXX compound variables. The
column is the name of the DB2 column. Each item contains data for one row from DB2. The count
of the number of SQL rows returned is contained in column.0. The count should be used as the
maximum value for n.
DB2 Interface
Chapter 22. REXX/CICS DB2 Interface 287
SQLCOLn.1
Some SELECT functions such as CURRENT SQLID, MAX, and AVG are not associated with a
particular DB2 column. To view the results you must reference column name SQLCOLn.1.
The nbegins with, and is incremented by one, for each function included in the SELECT
statement. All columns represented by SQLCOLnappear in the SQL_COLNAME compound
variable.
Using the SQL Communications Area
The fields that make up the SQL Communications Area (SQLCA) are automatically included by the
REXX/CICS DB2 when you issue SQL. The SQLCODE and SQLSTATE fields of the SQLCA contain SQL
return codes. These values are set by the REXX/CICS DB2 after each SQL statement is executed.
The SQLCA fields are maintained in separate variables rather than in a contiguous data area. The
variables that are maintained are defined as follows:
SQLCODE
The primary SQL return code.
SQLERRM
Error and warning message tokens. Adjacent tokens are separated by a byte containing X'FF'.
SQLERRP
Product code and, if there is an error, the name of the module that returned the error.
SQLERRD.n
Six variables containing diagnostic information. (The variable nis a number between 1 and 6.)
Note: The count of the number of SQL rows affected by the DELETE, INSERT, and UPDATE
command is contained in SQLERRD.3.
SQLWARN.n
Eleven variables containing warning flags. (The variable nis a number between 0 and 10.)
SQLSTATE
The alternate SQL return code.
Example Using SQL Statements
In the following example, the REXX/CICS exec prompts for the name of a department, obtains the names
and phone numbers of all members of that department from the EMPLOYEE table, and presents that
information on the screen.
/******************************************************/
/* Exec to list names and phone numbers by department */
/******************************************************/
/*--------------------------------------------------------------*/
/* Get the department number to be used in the select statement */
/*--------------------------------------------------------------*/
Say ’Enter a department number’
Pull dept
/*--------------------------------------------------------------*/
/* Retrieve all rows from the EMPLOYEE table for the department */
/*--------------------------------------------------------------*/
"EXECSQL SELECT LASTNAME, PHONENO FROM EMPLOYEE ",
"WHERE WORKDEPT = ’"dept"’"
If rc <> 0 then
doSay’’
Say ’Error accessing EMPLOYEE table’
Say ’RC =’ rc
Say ’SQLCODE =’ SQLCODE
DB2 Interface
288 CICS TS for VSE/ESA: REXX Guide
Exit rc
end
/*---------------------------------------*/
/* Display the members of the department */
/*---------------------------------------*/
Say ’Here are the members of Department’ dept
Don=1tolastname.0
Say lastname.n phoneno.n
End
Exit
DB2 Interface
Chapter 22. REXX/CICS DB2 Interface 289
DB2 Interface
290 CICS TS for VSE/ESA: REXX Guide
Chapter 23. REXX/CICS High-level Client/Server Support
Client/Server computing has become very popular in the Information Processing industry. Some of the
advantages of client/server computing are:
vThe ability to effectively integrate the strengths of mainframes, mini-computers, and new cost-effective
workstations, in a transparent fashion.
vThe ability to incrementally scale the size of computer's systems, up or down (right-sizing).
vThe simplification of complex application systems by breaking them down into manageable sets of
clients and servers.
vApplications and data can be distributed throughout a network for better performance, integrity or
security.
vThe ability for enterprise-wide access to data and applications, wherever they reside in the network,
from a variety of unlike computer systems or workstations.
Overview
REXX/CICS introduces REXX language Client/Server support. REXX/CICS provides a high-level
client/server capability. This capability includes:
vHigh-level, natural, transparent REXX client interface
vSupport for REXX-based application clients and servers.
High-level, Natural, Transparent REXX Client Interface
REXX/CICS supports a high-level easy to use interface from client REXX execs to application servers
through the ADDRESS keyword instruction in REXX. The ADDRESS instruction includes an external
environment name that is used to determine the name of the external procedure that is called to process
subsequent REXX command strings.
REXX/CICS provides the optional ability for the environment name (specified in the ADDRESS instruction)
to be the name of an application server. This capability is provided by the REXX/CICS DEFCMD and
DEFSCMD commands.
The DEFCMD command provides the ability to define (or redefine) REXX commands and environments,
and it provides the ability to specify whether an environment-command combination is to be handled by a
traditional CALLed routine or by an REXX application server.
Support for REXX-based Application Clients and Servers
In addition to the above REXX client interface, several facilities provide support for the use of application
servers written in REXX. One of these facilities is the WAITREQ command, which is used by servers to
wait for requests from clients. Another facility, the C2S and S2C commands, provide the ability for servers
to fetch or set the contents of client variables. Another capability, Automatic Server Initiation (ASI) provides
for servers to be started automatically when a request arrives from a client.
Value of REXX in Client/Server Computing
Some advantages of using REXX for implementing client/server solutions are:
vThe availability of REXX interpreter support under REXX/CICS with its quick development cycle and
excellent source-based interactive debugging allows the rapid prototyping and development of complex
systems.
vThe high-level client/server interfaces in REXX/CICS can improve development productivity and lower
maintenance costs
© Copyright IBM Corp. 1992, 2010 291
vBecause REXX/CICS allows REXX clients and servers to be recoded in non-REXX languages,
performance intensive parts of an application system can be selectively rewritten, if needed.
The FLST and EDIT commands that REXX/CICS provides are examples of client/server environments.
REXX/CICS Client Exec Example
/* EXAMPLE REXX/CICS EXEC */
TRACE ’O’ /* turn off source tracing */
ARG parm1 parm2 parm3
"CICS READQ TS QUEUE(MYQ) INTO(DATA) ITEM(5) NUMITEMS(1)"
if rc ¬= 0 then EXIT 100
SAY ’TSQ Data=’ data
"CICS SEND TEXT FROM(DATA) ERASE"
/* Define the SERVER EXEC as a REXX/CICS command */
'DEFCMD REXXCICS SERVER = = SERVER1 (REXX'
/* example of directing a subcommand to a server */
/* named SERVER1, which is written in REXX also */
DATA = 1
’SERVER COMMAND1 DATA’
say data /* ==> 2 */
if rc ¬= 0 then SAY ’Request to SERVER1 failed, RC=’ rc
EXIT
High-level Client/Server Support
292 CICS TS for VSE/ESA: REXX Guide
REXX/CICS Server Exec Example
/* EXAMPLE REXX/CICS SERVER1 EXEC */
TRACE ’O’ /* turn off source tracing */
/*----------------------------------------*/
/* Loop waiting on requests from clients */
/*----------------------------------------*/
Do Forever
’WAITREQ’
parse var request cmd varname
Select
When request = ’COMMAND1’ then CALL command1
When request = ’COMMAND2’ then CALL command2
When request = ’STOP’ then CALL stop_server
Otherwise
End /* Select */
End /* Do Forever */
exit
/* subroutine to process command1 */
Command1:
’C2S’ varname ’WORK’
WORK = WORK + 1
’S2C WORK’ varname
return
/* subroutine to process command2 */
Command2:
return
/* routine to shut down this server */
stop_server:
say ’The Server is stopping’
exit
High-level Client/Server Support
Chapter 23. REXX/CICS High-level Client/Server Support 293
High-level Client/Server Support
294 CICS TS for VSE/ESA: REXX Guide
Chapter 24. REXX/CICS Panel Facility
Facility
The REXX panel facility provides the REXX programmer with simple tools and commands for panel
definition and for panel input/output to 3270 type terminals. The panel facility allows easy definition of
panels using any editor. The requirement is that the panel source definition file should be in the REXX File
System (RFS) before it is further processed. The panel input/output command provides the ability within a
REXX program to dynamically change many of the field attributes statically defined by the panel definition
facility. The following example helps you see the capability and function of the panel facility and also helps
you understand and visualize the general concepts described in this chapter. An overview of the example
follows:
vDefines field control characters that set the characteristics of panel fields.
vUses the field control characters to define a panel layout. The control character definition and the panel
definition (the two parts together are called panel source) is saved in the REXX File System.
vUses the panel source to generate a panel object that is used to send or receive panels in a REXX
program.
Example of Panel Definition
define the field control characters to be used in the panel layout.
.DEFINE < blue protect
.DEFINE @ blue skip
.DEFINE ! red protect
.DEFINE > green unprotect underline
.DEFINE # green unprotect numeric right underline
define a panel named applican, which
queries an applicant’s name and address.
(this line and the above lines are treated as comments).
.PANEL applican
< Please type the requested information below @
!Applicant’s name
@Last name ...:>&lname @
@First name ..:>&fname @
@MI...........:>1&mi
!Applicant’s mailing address
@Street.......:>&mail_street @
@City.........:>&mail_city @
@State........:>2&mail_state
@Zip...:#5&mail_zip
.PANEL
** END OF SAMPLE PANEL DEFINITION.
** START OF REXX PROGRAM USING THE PREVIOUS PANEL.
/* program to query applicant’s name and address */
lname = ’’; /* null out all name parts */
fname = ’’;
mi = ’’;
mail_street = ’’;
© Copyright IBM Corp. 1992, 2010 295
mail_city = ’DALLAS’; /* prefill the most likely response for city/state */
mail_state = ’TX’;
mail_zip = ’’;
do forever;
’panel send applican cursor(lname)’;
if rc > 0 then
call error_routine;
’panel receive applican’; /* pseudo-conversational this would be separate */
if pan.aid = ’PF3’ | pan.aid = ’PF12’ then
leave;
if pan.aid = ’ENTER’ & pan.rea = 124 then
iterate;
if pan.aid = ’CLEAR’ | substr(pan.aid,1,2) = ’PA’ then
iterate; /* go to beginning of loop */
if rc > 0 then
call error_routine;
/* process the name and address */
end;
’panel end’;
exit
error_routine:
Say ’An error has occurred’
return;
** END OF REXX PROGRAM and end of sample.
Defining Panels
When you define a panel it requires two steps:
1. You must first use an editor to create the panel source file in the REXX File System. The panel source
should contain field control characters and the panel layout. The panel layout may contain field control
characters along with regular displayable text characters, and possibly, imbedded variable names.
2. Then you convert the panel source into an intermediate form (panel object) that can be used by the
panel input/output commands. The panel facility automatically generates the intermediate file when the
input/output command that is referencing that panel is first invoked or an explicit command within the
REXX environment (or a REXX exec containing the command) can be invoked to generate the
intermediate file.
Note: This automatic generation is executed whenever the panel object cannot be found or when the
panel source has a date or time change that is later than the panel object. Any change to the
panel source causes a new panel object to be created. Therefore, be cautious when you
change a panel source after a program using that panel is out of the testing phase. It is to your
advantage to move the panel source out of the RFS or into an RFS directory not accessible by
the program after the project goes into production.
Defining the Field Control Characters with the '.DEFINE' Verb
The field control characters define the attributes of fields on the panel. These control characters are
definable by using the .DEFINE verb and must precede the panel layout. The .DEFINE verb is terminated
at 'End of line' unless the continuation character (a comma) is the last character on the line . The
continuation character cannot immediately follow the .DEFINE verb because of the ambiguity of whether
the comma is the control character being defined or a continuation character. Spaces delimit each keyword
and order is unimportant except the control character that is defined must immediately follow the verb. If
any text does not start with .DEFINE in column one it is ignored and treated as a comment unless the line
is a continuation. A total of 32 control characters (including default control characters) can be actively
defined at one time. If all characters are deleted by using the DROP keyword then the five default control
Panel Facility
296 CICS TS for VSE/ESA: REXX Guide
characters are re-activated. Certain keyword combinations are incompatible and are not allowed while
others which may seem meaningless are allowed. For example, INVISIBLE and color. This may be useful
when the field attribute is changed dynamically within a REXX program (the invisible field can be made
visible which makes color meaningful).
The characteristics of the .DEFINE verb follow.
vIt must start on the first column, followed by a space, and capitalized.
vIt terminates at 'End of line' unless a continuation character (a comma) is used.
vAll keywords have a minimum of a two-character abbreviation.
vThe maximum number of control characters that you can define at one time is 32. (The default control
characters are included in this count.)
vIt must be placed before the .PANEL verb.
You can also define variable identifier control characters that let you associate REXX variables with Panel
Facility variables. Then, in your panel definition you can imbed the variable identifier control character
instead of the REXX variable name. The same REXX variable can be assigned to different variable
identifier control characters.
vA stem name must end in a period.
vA variable list can have more variables listed than are used, but less causes an error.
vMultiple variable identifier control characters can be defined and each one is independent of one
another.
.DEFINE
The format of the .DEFINE verb follows. Also, the default control characters are specified if you do not
want to define your own.
 .DEFINE char
options
VAriable
stem.
variable
DROP

options:
UNProtect
PRotect
SKip
NORmal
BRight
INVisible
DEfcolor
GReen
RED
BLUe
TUrquoise
WHite
YEllow
PInk
BLInk
REVerse
UNDerline
NOJustify
LEft
RIght
NULls
PAd ( )
BLAnks
char
NUMeric CUrsor MDT
Default field control characters
#Defcolor skip normal
+Defcolor protect bright
%Defcolor unprotect normal
Panel Facility
Chapter 24. REXX/CICS Panel Facility 297
!Defcolor unprotect bright
&Variable identifier
Operands
char
specifies the control character being defined.
VAriable
defines a REXX variable identifier control character. Variable identifier control characters are used to
associate Panel Facility control characters with REXX variable names. More than one variable control
character can be defined at one time. Following the VARIABLE keyword may be a list of variable
names (variable) or a single stem name (stem.). The variable list can contain one to 32,767 variable
names. Only one stem name can be specified and the stem name must end in a period. This period
identifies the variable as a stem and leaving off the period causes the name to be interpreted as a
simple variable.
Using a variable list and a stem name cannot be mixed. When the panel generator encounters a
variable control character a substitution is done. Simple variable lists are substituted in the same order
as listed. For example, the third variable control character is replaced with the third variable listed for
that control character. The stem variable is replaced by appending a three-character number (tail) to
the stem name. The number starts at 1 and is incremented as that stem control character is
encountered. Therefore, the tenth stem control character for a particular stem would have a 10 as the
tail (STEM.10). Since these variables are REXX variables, they must follow the REXX variable naming
rules.
DROP
drops char as a field control character.
Options
UNProtect
specifies that the field is not protected from operator input. (This is the default.)
PRotect
specifies that the field is protected from operator input.
SKip
specifies a protected field with the auto-skip feature. Operator entering a character in the last position
of the previous unprotected field causes the cursor to skip over this field.
NORmal
specifies that the field is not highlighted. (This is the default.)
BRight
specifies that the field is highlighted.
INVisible
specifies that the field is invisible.
GReen
RED
BLUe
TUrquoise
WHite
YEllow
PInk
DEfcolor
are the choices for the color.
Panel Facility
298 CICS TS for VSE/ESA: REXX Guide
Notes:
1. When you do not specify a default color, the color is based on the field type and intensity values:
protect/normal displays blue, protect/bright displays white, unprotect/normal displays green, and
unprotect/bright displays red.
2. If any field on a panel has explicitly specified a color (including DEFCOLOR), all bright fields with
DEFCOLOR or no color specified are displayed white and all normal fields with DEFCOLOR or no
color specified are displayed green. This is a 3270 hardware limitation and not the panel facility.
BLInk
specifies that the field blinks.
REVerse
specifies that the field is in reverse video.
UNDerline
specifies that the field is underlined.
NOJustify
specifies that justification is not done (left justified but blanks are not stripped).
LEft
specifies that the field is left justified (leading blanks are stripped).
RIght
specifies that the field is right justified (trailing blanks are stripped).
PAd()
specified only in the context of fields having variables. In an unprotected field the pad character fills
the character positions that are not occupied by a variable value. In a protected field, the pad
character is similar but the scope of the fill area is not the whole field as in the unprotected field. It is
bound by where the variable starts, within the protected field to either the end of the field or the start
of the next variable or text.
NULls
specifies that a field will be padded with the null character.
BLAnks
specifies that a field will be padded with blanks.
char
specifies a single character to be used to pad a field.
NUMeric
specifies a field is numeric (unprotected field only).
CUrsor
specifies that the cursor is positioned at the beginning of this field. If multiple cursor fields are defined,
then the last one defined contains the cursor. The cursor is placed in the top left corner if a cursor field
is not defined.
MDT
sets the modify bit tag on for the field. Always return this field on a read, even if the field was not
modified by the operator.
Defining the Actual PANEL Layout with the '.PANEL' Verb
Following the .DEFINE verbs should be a .PANEL verb that signals the start of the panel layout. This verb
must also start at column one and be capitalized. The lines in the panel definition should be specified in
the same positions that you want them displayed. All text entered after the panel verb is significant to the
panel generator, including blank lines, and therefore comment lines are not allowed. The first character
has to be a protect/skip or unprotect control character. The panel definition ends at the end of file or the
next .PANEL verb starting in column one. Only one panel definition per file is supported.
Panel Facility
Chapter 24. REXX/CICS Panel Facility 299
The panel layout is close to what you see, with the exception of the control characters and the imbedded
variables which are not shown when the panel is displayed. A field typed on the third line after the .PANEL
starting at column ten is positioned on the terminal screen third line, column ten.
The characteristics of the .PANEL verb follow.
vIt must start in the first column, followed by a space, and capitalized.
vIt must have a panel name on the same line as .PANEL, unless it is an end of panel indicator.
vIt must have at least one field and the first character following the .PANEL line has to be a protect, skip,
or unprotect control character.
vThe field ends at the start of the next field unless an explicit input field length is being used. An empty
field can be used to terminate a field.
vTo use a control character as a regular displayable character, type two consecutive control characters.
To display two consecutive control characters, type four consecutive control characters. For each pair of
control characters that get displayed as one character, the subsequent text in the field will be displayed
one position to the left, except if there are 7 or more consecutive spaces following the pair of control
characters.
vThe protect/skip field can have any number of variables or text that will fit in that field. A variable in a
protected field has area available for substitution, starts at the variable identifier control character, and
ends just before the next control character or text.
vSpace is not allowed between a variable identifier control character and the variable name. A space
causes the variable name to be interpreted as plain text.
vThe unprotect field can have only one associated variable.
vThe unprotected field can have a number explicitly stating the field length. The number must be
between the unprotect and variable control characters. When the explicit field length is used, a field
does not need termination. If an explicit length field is the last field of a line then a terminating field is
created with a skip attribute to force a field end.
vWhen an explicit input field length is used, all of the following field's column positions are adjusted left
or right to force proper alignment, so the explicit length field and the field immediately after abut each
other. Other fields on that line keep its spacing intact. This alignment only affects that one line, the fields
on the next line are unaffected. For example, a line has 5 fields with the 1st and 4th fields having
explicit length and spacing. Between fields 1 and 2 is 4, between 2 and 3 is 5, between 3 and 4 is 6,
and between 4 and 5 is 7. When this line is displayed, field 2 starts right after field 1 (no space),
separation between fields 2 and 3 is still 5, separation between fields 3 and 4 is still 6, and field 5
follows right after field 4 (no space). If the explicit length causes the current field or subsequent fields to
overflow into the next field, an error is returned when the panel is displayed.
vWhen a field does not terminate on the same line (for example, field spans lines), the field length varies
with the width of the screen on which the panel is being displayed. Also, if the last field has no
terminator, that field wraps the screen until the first field start is encountered.
vOnly the fields containing a variable can have its attributes dynamically changed during panel output.
vIf a protect/skip field is dynamically changed to an unprotected field, only the first variable in the field
has the operator input assigned to it. All of the contents of the input field are assigned.
vThe panel source file must reside in the REXX File System before it can be processed into the
intermediate file (panel object) used by the runtime panel facility.
.PANEL
The format of the .PANEL verb follows.
Panel Facility
300 CICS TS for VSE/ESA: REXX Guide
 .PANEL panel_name protect_cc
skip_cc variable_pair
text
variable_cc
unprotect_cc variable_cc
field_length variable_pair
.PANEL

Operands
panel_name
specifies the panel being defined. It must be one to eight characters in length and follow the rules for
REXX File System file names. (See Chapter 19, “REXX/CICS File System,” on page 257, for more
information.)
Note: The panel_name must be the same as the RFS file name. The complete RFS file name should
be panel_name.PANSRC.
protect_cc
specifies the protect field control character.
skip_cc
specifies the skip field control character.
variable_pair
specifies the variable control character followed by the variable name. (There cannot be a space
between them.)
text
displayable characters.
variable_cc
specifies the variable identifier control character.
unprotect_cc
specifies unprotect control character.
field_length
specifies the explicit input field length value.
Panel Generation and Panel Input/Output
Panel definition can be done outside the REXX environment; however, panel generation and input/output
is performed in a REXX exec or in the REXX interactive environment. The REXX interactive environment
is an ideal place to test the initial panel development. To test display the panel use the TEST panel
command. This displays the panel with no panel object file created. Also, there is no substitution for the
variables on the panel. To create the panel object use either the GENERATE, SEND, or the CONVERSE
panel commands. Use the FILE keyword to explicitly state what directory in RFS to find the panel source,
or you can let it default to the current directory. The panel source name must have the panel name as the
file name and 'PANSRC' as the file type. The panel object is created and filed in the same directory as the
panel source with the file name equal to the source file name and with a file type of 'PANOBJ'.
GENERATE creates the panel object and does not display the panel. SEND creates the panel object,
displays the panel, and attempts variable substitution. CONVERSE is similar to SEND with an implied wait
and receive.
Note: There are side affects of being in a REXX interactive environment. Several panel keywords act
differently: the cursor position on the SEND is ignored and keyboard lock is also ignored for SEND
and CONVERSE.
Panel Facility
Chapter 24. REXX/CICS Panel Facility 301
The characteristics of the PANEL command follow.
vAll the arguments or keywords are not meaningful or valid for all commands.
vThe last panel command in a REXX exec is the END command. This releases any storage held by
previous panel commands. This command needs no other operands.
vOnly the fields with associated variables can have their attributes changed dynamically.
vA panel object file is created for the panel that is being displayed if one does not exist. The file name is
the same as the panel source file name and the file type will be 'PANOBJ'.
vOnly the first variable in a protect/skip field is assigned the input entered by the terminal operator when
the field is changed to an input field.
vThe dynamic attribute changes effect the present panel execution and do not last. Subsequent panel
displays revert to what was defined statically by the panel definition step unless the attributes are again
dynamically changed.
vA SEND must be performed before a RECEIVE and the panel names must match.
vOnly the attributes indicate change, the others stay as defined statically.
vA panel sent with a position argument needs to be received with the same position values so the
operator input is assigned correctly to the REXX variables.
vEnclose the field ID list within parenthesis, when multiple fields are listed.
vThere has to be one ATTRIBUTE argument for each different attribute change.
Note: To change the number of ATTRIBUTE arguments dynamically, a REXX variable needs to be used
(put the literal attribute string in REXX variable and use the variable). For example, a program
needs to change one field to blue or to change one field to blue and another field to blinking
depending on operator input. One solution is:
field_id = ’xxxx’; /* name of field needing attribute changed*/
attr_string = ’attr(’ field_id ’blue )’;
if operator_input = y then
attr_string = attr_string ’attr(’ field_id2 ’blink )’
’panel send panel_name’ attr_string;
Note: REXX panel facility generates the panel object if the object is not found or if the object is older than
the source.
PANEL RUNTIME
The format of the PANEL RUNTIME commands follow.
 PANEL Send
Receive
Converse
Test
End
Generate
panel_name
FIle ( directory_name )
CUrsor ( field_id )
row column
ATtrib(field_id attribute_values) ALarm NOErase
POsition ( row column ) FReekb
LOckkb
CLrinput
UNProtect
options:
PRotect
SKip
Panel Facility
302 CICS TS for VSE/ESA: REXX Guide
NORmal
BRight
INVisible
GReen
RED
BLUe
TUrquoise
WHite
YEllow
PInk
DEfcolor
BLInk
REVerse
UNDerline
NOJustify
LEft
RIght
NULls
PAd ( )
BLAnks
char
NUMeric CUrsor
MDT 
Operands
Send
is the panel command that sends a panel.
Receive
is the panel command that receives a panel.
Converse
is the panel command that sends a panel and waits for operator input.
Test
is the panel command that displays a panel. An intermediate file (panel object) is not created and
variable substitutions are not attempted.
End
is a command that terminates the panel session. Command releases all storage held by the panel
facility. This command does not have arguments and any arguments supplied are ignored.
Generate
is an explicit command that creates a panel object. The panel is not displayed.
panel_name
specifies the name of the panel to input/output or generate.
FIle()
specifies the name of the RFS directory (directory_name) containing this panel. (Specified for all panel
commands except END.)
CUrsor()
(specified for SEND and CONVERSE only) positions the cursor on the panel.
field_id
specifies the REXX variable name where the cursor should be positioned on the panel.
row
specifies the row within the panel where the cursor should be positioned. The row value is relative to
the starting row of the panel. The default starting row of the panel is 1, but may be changed using the
POSITION() keyword.
column
specifies the column within the panel where the cursor should be positioned. The column value is
relative to the starting column of the panel. The default starting column of the panel is 1, but may be
changed using the POSITION() keyword.
ATtrib(field_id attribute_values)
(specified for SEND and CONVERSE only)
field_id
specifies the field whose attributes are dynamically set. It must be a variable name associated with
Panel Facility
Chapter 24. REXX/CICS Panel Facility 303
the field. The field list must be enclosed with parenthesis. Only the attributes stated are changed
and the other attributes default to what was statically defined. A field defined originally as RED and
UNDERLINE remains underlined if only blue is stated dynamically.
ALarm
(specified for SEND and CONVERSE only) sounds the bell when displaying panel. (The default is no
alarm).
NOErase
(specified for SEND and CONVERSE only) do not erase the screen before displaying this one. (The
default is erase before a panel write).
POsition()
(specified for SEND, CONVERSE, and RECEIVE only) positions the panel on the output screen. Row
(row) and column (column) specifies where the top left corner of the panel should begin. (The default
is row 1 col 1). For example, POS(5 10) means to have the panel start in row 5 and column 10, the
actual movement is 4 rows down and 9 columns to the right.
FReekb
(specified for SEND and CONVERSE only) frees the keyboard, allowing operator input. (This is the
default.)
LOckkb
(specified for SEND and CONVERSE only) locks the keyboard.
CLrinput
(specified for SEND and CONVERSE only) clears all input fields before displaying the panel. Variable
substitution is not attempted and pad characters fill the input area.
Options
UNProtect
specifies that the field is not protected from operator input.
PRotect
specifies that the field is protected from operator input.
SKip
specifies a protected field with the auto-skip feature. Operator entering a character in the last position
of the previous unprotected field causes the cursor to skip over this field.
NORmal
specifies that the field is not highlighted.
BRight
specifies that the field is highlighted.
INVisible
specifies that the field is invisible.
GReen
RED
BLUe
TUrquoise
WHite
YEllow
PInk
DEfcolor
are the choices for the color.
Panel Facility
304 CICS TS for VSE/ESA: REXX Guide
Notes:
1. When you do not specify a default color, the color is based on the field type and intensity values:
protect/normal displays blue, protect/bright displays white, unprotect/normal displays green, and
unprotect/bright displays red.
2. If any field on a panel has explicitly specified a color (including DEFCOLOR), all bright fields with
DEFCOLOR or no color specified are displayed white and all normal fields with DEFCOLOR or no
color specified are displayed green. This is a 3270 hardware limitation and not the panel facility.
BLInk
specifies that the field blinks.
REVerse
specifies that the field is in reverse video.
UNDerline
specifies that the field is underlined.
NOJustify
specifies that no justification is done (left justified but blanks are not stripped).
LEft
specifies that the field is left justified (leading blanks will be stripped).
RIght
specifies that the field is right justified (trailing blanks will be stripped).
PAd()
specified only in context of fields having variables. In an unprotected field the pad character fills the
character positions that are not occupied by a variable value. In a protected field, the pad character is
similar but the scope of the fill area is not the whole field as in the unprotected field. It is bound by
where the variable starts, within the protected field to either the end of the field or the start of the next
variable or text.
NULls
specifies that a field will be padded with the null character.
BLanks
specifies that a field will be padded with blanks.
char
specifies a single character to be used to pad a field.
NUMeric
specifies a field is numeric (unprotected field only).
CUrsor
specifies that the cursor is positioned at the beginning of this field. If multiple cursor fields are defined,
then the last one defined contains the cursor. The cursor is placed in the top left corner if a cursor field
is not defined.
MDT
(specified for SEND and CONVERSE only) sets the modify bit tag for all input fields on the panel.
PANEL Variables
The implicitly defined PANEL variables that can be used by the REXX program follow.
PAN.AID
Attention identifier that last caused panel input.
ENTER ENTER
CLEAR CLEAR
CLRP CLEAR PARTITION
PEN SELECTOR PEN
Panel Facility
Chapter 24. REXX/CICS Panel Facility 305
OPID OPERATOR ID
MSRE MAGNETIC READER
STRF STRUCTURE FIELD
TRIG TRIGGER
PA1
PA2
PA3
PF1
PF2
PF3
PF4
PF5
PF6
PF7
PF8
PF9
PF10
PF11
PF12
PF13
PF14
PF15
PF16
PF17
PF18
PF19
PF20
PF21
PF22
PF23
PF24
PAN.CURS
Position of cursor in last panel input. This is in the form of row column separated by a blank. For
example, '10 5' would be row 10 and column 5. The row and column values are absolute to the start
of the screen and are unaffected by the POSITION() keyword.
PAN.CNAM
REXX variable name (field ID) associated with the cursor position. If the field has no associated
variable then PAN_CNAM is not updated.
The PANEL error related variables follow.
PAN.REA
Reason code if warning or error occurs. REXX return code, RC, should be examined first. If the RC is
10, PAN.REA contains state codes and input codes to help in error determination. See section “State
Codes and Input Codes” on page 308 for more information.
PAN.LOC
Internal location code. Three to four-digit number used by IBM support. If the REXX variable RC
contains the value 10, the PAN.LOC should be used in conjunction with PAN.REA for error
determination.
PAN.LINE
Line number in the source panel definition where an error was detected, if error occurred during panel
object generation.
Panel Facility Return Code Information
The main return code for the panel command is set in the REXX variable, RC. Each level of return code is
accompanied by additional information in the form of a reason code and a line number (if applicable).
When an error is detected while processing panel source code (location code of 11xx or 12xx) and RC is
not 12 or 16, the REXX variable PAN.LINE contains the number of the line in error.
Panel Facility
306 CICS TS for VSE/ESA: REXX Guide
Return Codes
4Warning. Panel facility continues processing. Processing stops for other return code values.
8Programmer error
10 Programmer error, PAN.REA contains more information to help determine the cause of the error.
See section “State Codes and Input Codes” on page 308 for more information.
12 CICS command error; the CICS EIBRESP is returned in the panel reason code. If the error is not
programmer resolvable, save and collect as much information as needed to recreate the error and
contact IBM support.
14 RFS errors; reason code contains the RFS return code
16 Internal system error; save and collect as much information as needed to recreate the error and
contact IBM support.
System Error Reason Codes
401 Panel facility ran out of storage space while processing the command
402 Internal control character identifier table and control character informational table are out of
synchronization
403 Panel object data has been corrupted. First check to see the file is correct and that it is a panel
object.
404 CICS receive buffer corrupted
405 Bad validation request
406 Storage free request failed
407 Storage get request failed
408 Attempt to get/put REXX variable failed
409 Aid is unknown
410 Dynamic match error
Programmer Introduced Warning/Error Reason Codes
101 Keyword repeated or keyword within a like category was repeated. For example, RED and BLUE;
UNDERLINE and REVERSE.
102 Keywords are incompatible. For example, PROTECT and NUMERIC
103 Missing keyword or panel name
104 The control character being defined is invalid or missing
105 Panel is too large for the screen
108 Parenthesis missing
109 Pad character invalid
110 Task has no associated terminal
111 Panel has no input fields defined during a receive
112 Panel name is invalid
115 REXX variable name (or field ID) is invalid
116 Number is specified incorrectly. Explicit length value in panel source or row col value
Panel Facility
Chapter 24. REXX/CICS Panel Facility 307
117 Variable value was too long and was truncated to fit output field
118 Text field was truncated. Check to see if explicit length did not force a subsequent field to overlay
another field.
119 Bad or missing panel command. It should be SEND, RECEIVE, CONVERSE, TEST, or END.
122 A modified field was received but it had no corresponding input field definition.
124 Empty received buffer. Clear, ENTER, and the PA keys will cause this.
125 File name is invalid
126 Field identifier for the ATTRIBUTE keyword was not found in the panel.
129 Too many arguments supplied with the command
130 SEND must be performed before a RECEIVE
131 Panel source has no panel definition. '.PANEL' was probably not in column 1 or did not have a
space after.
132 Keyword encountered is unknown
133 DROP asked for a control character not presently active
136 Continuation is in effect but end of source was encountered
137 Row or column specified is too large for the current display CURSOR() or POSITION() the likely
source of error.
138 Variable identifier control character was being defined and more than one stem name was listed.
139 More variable fields defined than listed in the control character definition.
140 Explicit input field value caused field to go past screen end
143 Panel name in file does not match the panel name in the panel runtime command.
144 Panel has more rows than the present screen allows
145 Panel has more columns than the present screen allows
State Codes and Input Codes
For return code 10 the reason code (in PAN.REA) has a special meaning. It consists of two 2-digit numeric
codes, the first number stating what keyword is being processed (state code) and the second number
stating the input that caused the error condition (input code). Use the location code (in PAN.LOC) to
determine which state code list and input code list to use.
For example:
RC=10
PAN.REA = 0199
PAN.LOC = 1177
When you use the state code and input code lists for the 11xx location codes, the keyword being
processed was .DEFINE for state code 01 and the input code contained an unknown symbol for input
code 99.
State codes
State codes for 11xx location codes:
01 .DEFINE and control char
02 field type (protect/skip/unprotect)
03 color (red/blue/green/...)
04 Intensity (bright/normal/invisible)
05 Justify (left/right/nojustify)
Panel Facility
308 CICS TS for VSE/ESA: REXX Guide
06 Numeric
07 extended highlight (blink/reverse/underline)
08 MDT
09 Cursor
10 Pad()
11 Variable
12 Drop
State codes
State codes for 20xx location codes:
01 panel commands (send/receive/converse/...)
02 File()
03 Cursor()
04 Position()
05 Alarm
06 Noerase
07 Keyboard lock (lockkb/freekb)
08 Clrinput
09 Attribute
10 field type (protect/skip/unprotect)
11 color (red/blue/green/...)
12 Intensity (bright/normal/invisible)
13 Justify (left/right/nojustify)
14 Numeric
15 extended highlight (blink/reverse/underline)
16 MDT
17 Cursor
18 Pad()
19 closing parenthesis of the ATTRIBUTE argument
Input codes
Input codes for 11xx and 20xx location codes:
01 field type (protect/skip/unprotect)
02 color (red/blue/green/...)
03 Intensity (bright/normal/invisible)
04 Justify (left/right/nojustify)
05 Numeric
06 extended highlight (blink/reverse/underline)
07 MDT
08 Cursor
09 Pad()
10 Variable
11 Drop
12 (not used)
13 File()
14 Cursor()
15 Position()
16 Alarm
17 Noerase
18 Keyboard lock (lockkb/freekb)
19 Clrinput
20 Attribute
21 closing parenthesis of the ATTRIBUTE argument
98 End of command; more operands were expected
99 Unknown symbol; keyword or control character was expected
Panel Facility
Chapter 24. REXX/CICS Panel Facility 309
State Codes
State codes for 12xx location codes:
01 panel name
02 protect/skip field
03 unprotect field
04 text within a protect/skip field
05 (not implemented yet)
06 explicit input field length number
07 unprotect variable
08 protect/skip variable
Input codes
Input codes for 12xx location codes:
01 Plain displayable text
02 Explicit length number
03 Protect field control character
04 Unprotect field control character
05 Variable control character
07 End of panel
08 Invalid or unknown input
Location Codes
Numbers under 1000 are in the mainline processor.
10xx Panel generator common processor
11xx .DEFINE verb processor
12xx .PANEL verb processor
20xx Panel runtime command processor
21xx Dynamic attribute resolution processor
30xx Output 3270 data stream processor
40xx Input 3270 data stream and REXX variable assignment processor
90xx CICS interface processor
Examples of Sample Panels
Five examples of sample panel definitions follow.
Example 1
.DEFINE > prot blue
.DEFINE ? prot red
.DEFINE # unprot num green
.DEFINE < unprot invisible num
.DEFINE @ protect turq
.DEFINE + prot blue underline
.PANEL signon
> Panel signon &companyname
?&message
@ Welcome to ACME On-Line Tax Services
+Please enter your Account Number and Personal ID Number and press ENTER>
>Account Number :#7&account_num
>PIN :<4&pin
Panel Facility
310 CICS TS for VSE/ESA: REXX Guide
Example 2
.DEFINE > prot green
.DEFINE < unprot underline white
.DEFINE + var service.
.DEFINE % skip turq
.PANEL service
> Panel service &disp_date &companyname
% &salutation
% Tab the cursor to the type of service wanted and press the ENTER key.
<+> Itemized tax preparation
<+> Non-itemized tax preparation
<+> Query return status
<+> Show calendar
<+> Exit
Example 3
.DEFINE # protect bright
.DEFINE + protect
A panel to display a static message without erasing previous panel.
Notice the position of the escape sequence in lines 1 and 6.
See manual for an explanation about escape sequences.
.PANEL msgbox1
#++-------------------------------------------+++
#| |+
#| We are sorry but the service you have |+
#| chosen is not available at this time. |+
#| Press ENTER to continue. |+
#| |+
#++-------------------------------------------+++
Panel Facility
Chapter 24. REXX/CICS Panel Facility 311
Example 4
.DEFINE ) protect bright
.DEFINE + drop
.DEFINE & var msg.
A panel to display output dynamic messages.
.PANEL msgbox2
)+-------------------------------------------+#
)| |#
)| & |#
)| & |#
)| |#
)+-------------------------------------------+#
Example 5
.DEFINE > skip blue
.DEFINE < skip green right
.DEFINE % var center_days.
.DEFINE + var right_days.
.DEFINE # VAR left_days.
.DEFINE @ var pf3 pf7 pf8
.PANEL calendar
> Panel calendar &disp_date &companyname
> &disp_left_mon &disp_center_mon &disp_right_mon
>su mo tu we th fr sa su mo tu we th fr sa su mo tu we th fr sa
<# <# <# <# <# <# <# > <% <% <% <% <% <% <% > <+ <+ <+ <+ <+ <+ <+ >
<# <# <# <# <# <# <# > <% <% <% <% <% <% <% > <+ <+ <+ <+ <+ <+ <+ >
<# <# <# <# <# <# <# > <% <% <% <% <% <% <% > <+ <+ <+ <+ <+ <+ <+ >
<# <# <# <# <# <# <# > <% <% <% <% <% <% <% > <+ <+ <+ <+ <+ <+ <+ >
<# <# <# <# <# <# <# > <% <% <% <% <% <% <% > <+ <+ <+ <+ <+ <+ <+ >
<# <# > <% <% > <+ <+ >
>@ = Leave Calendar >@ = Backup a month >@ = Go forward a month
IF RC=4 & PAN.REA = 124 THEN /* warning and no input received */
Example of a REXX Panel Program
/* data base */
ACCOUNT.1234561 = ’1231 John W. Smith Mr.’
ACCOUNT.1234562 = ’1232 Jane M. Brown Miss’
ACCOUNT.1234563 = ’1233 Mary R. Scott Mrs.’
MESSAGE = ’’ /* no output message yet */
COMPANYNAME = ’ACME On-Line Tax Services’
CURS_NAME = ’ACCOUNT_NUM’ /* put cursor on LNAME field */
ATTR_STRING = ’’ /* no dynamic attributes on first send */
PATH_NAME = ’FILE(POOL1:\USERS\BLAKELY)’
CLR_INP_FIELDS = ’CLR’
Panel Facility
312 CICS TS for VSE/ESA: REXX Guide
’PANEL SEND SIGNON’ CLR_INP_FIELDS PATH_NAME ,
’CURSOR(’ CURS_NAME ’)’ ATTR_STRING
IF RC > 4 THEN /* more than a warning */
SIGNAL ERROR /* clean up and exit */
’PANEL RECEIVE SIGNON ’
IF RC > 4 THEN
SIGNAL ERROR /* clean up and exit */
ITERATE /* redisplay panel */
CLR_INP_FIELDS = ’’ /* display input fields with variable values */
IF &lnot;SEARCH(ACCOUNT_NUM) THEN /* search for account number */
DO;
MESSAGE = ’ Account Number not found, Please re-ENTER Number’
CURS_NAME = ’ACCOUNT_NUM’ /* put cursor in ACCOUNT field */
ATTR_STRING = ’ATTR( ACCOUNT_NUM REV)’
ITERATE
END;
DO;
MESSAGE = ’ PIN Number is incorrect, Please check to see your’,
’Account Number is correct and re-ENTER your PIN’;
CURS_NAME = ’PIN’;
ATTR_STRING = ’ATTR( PIN REV)’;
ITERATE ; /* display the panel again */
END;
LEAVE ;
END ; /* forever */
DISP_DATE = DATE(’U’); /* set to display current date */
MSG.1 = ’Be sure cursor is in the first column!’;
MSG.2 = ’Press ENTER or and PF key to continue.’;
SALUTATION = ’Hi’ WORD(ACCOUNT.ACCOUNT_NUM,5) ,
WORD(ACCOUNT.ACCOUNT_NUM,4) ||,
’, How may we be a service to you?’;
PAN.CNAM = ’’;
’PANEL SEND SERVICE CURSOR(SERVICE.1)’ PATH_NAME
IF RC > 4 THEN
SIGNAL ERROR; /* clean up and exit */
’PANEL RECEIVE SERVICE’
IF RC > 4 THEN
SIGNAL ERROR; /* clean up and exit */
SALUTATION = ’’; /* greeting only once */
WHEN PAN.CNAM = ’SERVICE.1’ THEN
CALL ITEMIZE_ROUTINE;
WHEN PAN.CNAM = ’SERVICE.2’ THEN
CALL NON_ITEMIZE_ROUTINE;
WHEN PAN.CNAM = ’SERVICE.3’ THEN
CALL QUERY_RET_ROUTINE;
WHEN PAN.CNAM = ’SERVICE.4’ THEN
CALL CAL;
WHEN PAN.CNAM = ’SERVICE.5’ THEN
CALL EXIT_ROUTINE;
DO;
’PANEL SEND MSGBOX2 POS(7 10) NOERASE’ PATH_NAME
IF RC > 4 THEN
SIGNAL ERROR;
’PANEL RECEIVE MSGBOX2’
IF RC > 4 THEN
SIGNAL ERROR;
END;
Panel Facility
Chapter 24. REXX/CICS Panel Facility 313
END; /* select */
END; /* do forever */
EXIT
IF SYMBOL(’ACCOUNT.ACC_NUM’) == ’VAR’ THEN
RETURN(1)
ELSE
RETURN(0);
NON_ITEMIZE_ROUTINE:
QUERY_RET_ROUTINE:
’PANEL SEND MSGBOX1 POS(7 10) NOERASE’ PATH_NAME
IF RC > 4 THEN
SIGNAL ERROR;
’PANEL RECEIVE MSGBOX1’
IF RC > 4 THEN
SIGNAL ERROR;
RETURN;
COMPANYNAME = ’ACME On-Line Tax Service’;
PATH_NAME = ’FILE(POOL1:\USERS\BLAKELY\)’
DISP_DATE = DATE(’U’);
/* calling date function in on statement ensures consistent date */
/* data save has format of YYYYMMDDNNNNNN */
DATE_SAVE = DATE(’S’) || DATE(’B’);
NUM_OF_DAYS.1 = 31;
NUM_OF_DAYS.3 = 31;
NUM_OF_DAYS.4 = 30;
NUM_OF_DAYS.5 = 31;
NUM_OF_DAYS.6 = 30;
NUM_OF_DAYS.7 = 31;
NUM_OF_DAYS.8 = 31;
NUM_OF_DAYS.9 = 30;
NUM_OF_DAYS.10 = 31;
NUM_OF_DAYS.11 = 30;
NUM_OF_DAYS.12 = 31;
MONTH_NAME.1 = ’January’;
MONTH_NAME.2 = ’February’;
MONTH_NAME.3 = ’March’;
MONTH_NAME.4 = ’April’;
MONTH_NAME.5 = ’May’;
MONTH_NAME.6 = ’June’;
MONTH_NAME.7 = ’July’;
MONTH_NAME.8 = ’August’;
MONTH_NAME.9 = ’September’;
MONTH_NAME.10 = ’October’;
MONTH_NAME.11 = ’November’;
MONTH_NAME.12 = ’December’;
TOT_DAYS = SUBSTR(DATE_SAVE,9,6)-SUBSTR(DATE_SAVE,7,2) +1;
/* save current year and month to highlight today date on display */
CUR_YEAR = SUBSTR(DATE_SAVE,1,4);
/* get month part of date. adding 0 strips the leading zero */
CUR_MONTH = SUBSTR(DATE_SAVE,5,2) +0;
YEAR = CUR_YEAR;/* these variables will change with whats displayed */
MONTH = CUR_MONTH;
IF YEAR // 400 &lnot;= 0 & YEAR //4=0THEN /* leap year? */
Panel Facility
314 CICS TS for VSE/ESA: REXX Guide
NUM_OF_DAYS.2 = 29;
ELSE
NUM_OF_DAYS.2 = 28;
FIRST_WEEKDAY = (TOT_DAYS+1) // 7;
FIRST_WEEKDAY_SAVE = FIRST_WEEKDAY;
DISP_CENTER_MON = MONTH_NAME.MONTH; /* center display month name */
CENTER_DAYS. = ’’; /* null out all unused month days */
/* starting at the first weekday of the month fill in center month */
DO I = FIRST_WEEKDAY+1 TO NUM_OF_DAYS.MONTH + FIRST_WEEKDAY ;
CENTER_DAYS.I=I-FIRST_WEEKDAY;
END;
IF MONTH = 1 THEN
LEFT_MONTH = 12;
ELSE
LEFT_MONTH = MONTH - 1;
DISP_LEFT_MON = MONTH_NAME.LEFT_MONTH; /* left display month name */
FIRST_WEEKDAY = (TOT_DAYS - NUM_OF_DAYS.LEFT_MONTH+1) // 7;
LEFT_DAYS. = ’’;
DO I = FIRST_WEEKDAY+1 TO NUM_OF_DAYS.LEFT_MONTH + FIRST_WEEKDAY ;
LEFT_DAYS.I=I-FIRST_WEEKDAY;
END;
FIRST_WEEKDAY = (TOT_DAYS + NUM_OF_DAYS.MONTH +1) // 7;
IF MONTH = 12 THEN
RIGHT_MONTH = 1;
ELSE
RIGHT_MONTH = MONTH + 1;
DISP_RIGHT_MON = MONTH_NAME.RIGHT_MONTH; /* right display month name */
RIGHT_DAYS. = ’’;
DO I = FIRST_WEEKDAY+1 TO NUM_OF_DAYS.RIGHT_MONTH + FIRST_WEEKDAY ;
RIGHT_DAYS.I=I-FIRST_WEEKDAY;
END;
ATTR_STRING = ’ATTRIB(’ CUR_DAY_FIELD ’RED )’ ;
’PANEL SEND CALENDAR’ PATH_NAME ATTR_STRING
’PANEL RECEIVE CALENDAR’
IF PAN.AID = ’PF3’ THEN
RETURN;
IF PAN.AID = ’PF7’ THEN /* go back one month request */
DO;
IF MONTH = 1 THEN /* always keep track of center month */
DO;
MONTH = 12;
YEAR = YEAR - 1;
IF YEAR // 400 &lnot;= 0 & YEAR // 4 = 0 THEN /* leap year? */
NUM_OF_DAYS.2 = 29;
ELSE
NUM_OF_DAYS.2 = 28;
END;
MONTH = MONTH - 1;
TOT_DAYS = TOT_DAYS - NUM_OF_DAYS.MONTH;
DISP_RIGHT_MON = DISP_CENTER_MON;
DISP_CENTER_MON = DISP_LEFT_MON;
DOI=1TO37;
RIGHT_DAYS.I = CENTER_DAYS.I;
CENTER_DAYS.I = LEFT_DAYS.I;
END;
Panel Facility
Chapter 24. REXX/CICS Panel Facility 315
LEFT_MONTH = 12;
ELSE
LEFT_MONTH = MONTH - 1;
FIRST_WEEKDAY = (TOT_DAYS - NUM_OF_DAYS.LEFT_MONTH +1) // 7;
DISP_LEFT_MON = MONTH_NAME.LEFT_MONTH;
LEFT_DAYS. = ’’;
DO I = FIRST_WEEKDAY+1 TO NUM_OF_DAYS.LEFT_MONTH + FIRST_WEEKDAY ;
LEFT_DAYS.I=I-FIRST_WEEKDAY;
END;
END; /* if pan.aid = ’pf7’ */
ELSE
DO;
TOT_DAYS = TOT_DAYS + NUM_OF_DAYS.MONTH;
IF MONTH = 12 THEN /* always keep track of center month */
DO;
MONTH = 1;
YEAR = YEAR + 1;
IF YEAR // 400 &lnot;= 0 & YEAR // 4 = 0 THEN /* leap year? */
NUM_OF_DAYS.2 = 29;
ELSE
NUM_OF_DAYS.2 = 28;
END;
ELSE
MONTH = MONTH + 1;
DISP_CENTER_MON = DISP_RIGHT_MON;
DOI=1TO37
LEFT_DAYS.I = CENTER_DAYS.I; /* shift the months to left */
CENTER_DAYS.I = RIGHT_DAYS.I;
END;
IF MONTH = 12 THEN /* need a new right month */
RIGHT_MONTH = 1;
ELSE
RIGHT_MONTH = MONTH + 1;
FIRST_WEEKDAY = (TOT_DAYS + NUM_OF_DAYS.MONTH +1) // 7;
RIGHT_DAYS. = ’’;
DO I = FIRST_WEEKDAY+1 TO NUM_OF_DAYS.RIGHT_MONTH + FIRST_WEEKDAY;
RIGHT_DAYS.I=I-FIRST_WEEKDAY;
END;
END; /* if pan.aid = ’pf8’ */
/* and set it to red. */
ATTR_STRING = ’’; /* assume current day not on screen */
IF YEAR = CUR_YEAR THEN
SELECT;
WHEN MONTH = CUR_MONTH THEN /* current month in middle */
DO;
CUR_DAY_FIELD = ’CENTER_DAYS.’||,
(SUBSTR(DATE_SAVE,7,2)+FIRST_WEEKDAY_SAVE);
ATTR_STRING = ’ATTRIB(’ CUR_DAY_FIELD ’RED )’ ;
END;
DO;
CUR_DAY_FIELD = ’LEFT_DAYS.’||,
(SUBSTR(DATE_SAVE,7,2)+FIRST_WEEKDAY_SAVE);
ATTR_STRING = ’ATTRIB(’ CUR_DAY_FIELD ’RED )’ ;
END;
DO;
CUR_DAY_FIELD = ’RIGHT_DAYS.’||,
Panel Facility
316 CICS TS for VSE/ESA: REXX Guide
(SUBSTR(DATE_SAVE,7,2)+FIRST_WEEKDAY_SAVE);
ATTR_STRING = ’ATTRIB(’ CUR_DAY_FIELD ’RED )’ ;
END;
END; /* select */
’PANEL RECEIVE CALENDAR’
END; /* do forever loop */
ERROR:
SAY ’RETURN CODE ’ RC
SAY ’REA CODE ’ PAN.REA
SAY ’LOC CODE ’ PAN.LOC
EXIT;
EXIT_ROUTINE:
’PANEL END’;
SENDE;
EXIT;
each definition needs to be in a separate RFS file.
******************************************************
Panel Facility
Chapter 24. REXX/CICS Panel Facility 317
318 CICS TS for VSE/ESA: REXX Guide
Chapter 25. REXX/CICS Commands
This chapter provides you with detailed reference information for all REXX/CICS commands. Return code
information for all commands is returned after command execution in the special REXX variable RC.
You can use all the commands in this chapter with the command environment name REXXCICS. This is
also the default. However, depending on how you define the command, you can use a more specific
environment name (such as CICS) instead. If you need to reset the command environment, because
another command environment is in use, enter: ADDRESS REXXCICS before you issue commands from this
chapter.
REXX/CICS supports all EXEC CICS commands, excluding System Programming (SPI) commands,
except: Handle Condition, Handle Aid, Handle Abend, Ignore Condition, Push, and Pop. The syntax for
CICS commands under REXX/CICS is documented in the CICS Transaction Server for VSE/ESA
Application Programming Reference. Mapping between the existing EXEC CICS command definitions to
the REXX commands follows:
vCICS, rather than EXEC CICS, should be used as the prefix for CICS commands.
vAll data value fields can be specified as a literal character string or as a REXX variable name.
vAll data area fields can be specified as a REXX variable name, which is either the source or the target
for the desired data.
vThe same REXX variable should not be used as both the source and target fields on a CICS command.
If this is done, the result of the command execution will be unpredictable.
vWhenever you do not specify a LENGTH option, the length is automatically determined from the length
of the related REXX variable or character string.
vWhen using the CICS ENQ command from REXX/CICS, the LENGTH parameter should be used or
unpredictable results may occur.
vNOHANDLE is automatically specified for all CICS commands. The EIBRESP value from the execution
of each command is returned in the REXX special variable RC. Also, EIB fields are placed in REXX
variables DFHEIBLK, EIBRESP, EIBRESP2, and EIBRCODE.
vFor an explanation of the return code values see the CICS Transaction Server for VSE/ESA Application
Programming Reference. For information on return codes with negative values, see Appendix B, “Return
Codes,” on page 387.
Example of EXEC CICS to REXX/CICS command mapping:
Non-REXX: EXEC CICS XCTL PROGRAM(’PGMA’) COMMAREA(COMA) LENGTH(COMAL)
REXX/CICS: "CICS XCTL PROGRAM(’PGMA’) COMMAREA(COMA)"
Note: The EXEC CICS READ, WRITE, and DELETE commands are implemented by default as
REXX/CICS authorized commands, to control their use. Refer to “Authorized REXX/CICS
Commands/Authorized Command Options” on page 417 and to Appendix H, “Security,” on page
421.
© Copyright IBM Corp. 1992, 2010 319
AUTHUSER
Note: This is an authorized command.
 AUTHUSER
;
userid 
AUTHUSER authorizes a list of user IDs.
Operands
userid
is a CICS signon user ID that becomes REXX/CICS authorized.
Return Codes
0Normal return
2602 Invalid operand or operand missing
2621 Specified user ID invalid length
2642 Error storing user ID
Example
’AUTHUSER USER2 SYSPGMR’
This example makes USER2 and SYSPGMR REXX/CICS authorized users.
Notes
1. If you are an authorized user you can use REXX/CICS authorized commands, regardless of whether
you are running in an exec that was loaded from an authorized REXX/CICS library.
2. If an error is detected in the list of user IDs, the user ID with the error is placed in the REXX special
variable, RESULT and processing of the list stops.
3. AUTHUSER commands are cumulative, that is, previous AUTHUSER command definitions remain in
effect until the CICS region is recycled.
Commands
320 CICS TS for VSE/ESA: REXX Guide
CD
 CD
dirid

CD changes the RFS file system directory.
Operands
dirid
specifies a partial or full REXX File System directory that becomes the new current working directory
for you.
If dirid is not specified, the current working directory is retrieved and placed in the REXX special
variable RESULT, instead of changing the current working directory.
A full directory ID is in the form: poolid:\dirid1\...\diridn
When a full directory ID is specified, it completely replaces the previous directory setting.
A partial directory ID does not begin with a poolid. In this case, the partial directory ID is appended to
the end of the existing directory ID. If the partial directory ID begins with two periods, this indicates
that one directory level is removed (from the right), before the new partial directory ID is appended to
the end. In this case, a backslash is required before the directory ID.
For example: If the current directory is POOL1:\USERS\USER1\ABC and you enter CD ..\XYZ the new
current directory will be POOL1:\USERS\USER1\XYZ.
The default directory ID for you is poolid:\USERS\userid\, where poolid: is the file pool identifier of the
first RFS file pool defined and userid is your CICS signon user ID. If you are not signed onto CICS,
userid defaults to the value in CICS DFLTUSER.
Return Codes
0Normal return
521 Error in retrieving file pool definition
522 Error in creating default RFS directory
523 Error in storing current RFS directory information
524 RFS directory does not exist or access not authorized
525 Error in retrieving directory information
526 Invalid file pool/directory
527 Cannot go back past root directory
528 Error setting result value
Examples
’CD \USERS\USER2\XYZ’
This example changes your current working directory to \USERS\USER2\XYZ in the file pool you are
currently using regardless of the previous directory setting.
If your current directory is \USERS\USER2 and you enter:
’CD XYZ’
then your current directory is changed to \USERS\USER2\XYZ.
Note
The CD command works in conjunction with the PATH command identifying the search order for the
execution of REXX execs. The current directory (specified by the CD command) is always searched first
Commands
Chapter 25. REXX/CICS Commands 321
for execs.
Commands
322 CICS TS for VSE/ESA: REXX Guide
CEDA
 CEDA RDO_Command 
Executes a CEDA command for resource definition online (RDO).
Operands
RDO_Command
specifies a command string passed as input to the CEDA transaction program.
Return Codes
nspecifies the return code passed back by CICS if an error is detected
0Normal return
-101 Invalid command
Any warning or error messages are placed in the variable CEDATOUT. The results of the execution, if any,
are placed in the variable CEDAEOUT. The maximum length returned in CEDAEOUT is approximately 28K
bytes. Each variable has the following format:
vBinary halfword containing inclusive length of field.
vBinary halfword containing the number of messages produced.
vBinary halfword containing the highest message-severity: 0and 4continue to execution; 8and 12 do not
continue to execution.
vVariable-length data containing:
– For CEDATOUT: messages produced from translation stage of command
– For CEDAEOUT: messages produced from execution stage of command
The format of this data is not guaranteed from release to release, but it is the same as that displayed by
CEDA.
Example
’CEDA INSTALL PROGRAM(XYZ) GROUP(ABC)’
This example shows a CICS command that is passed to the CEDA transaction program for execution.
Commands
Chapter 25. REXX/CICS Commands 323
CEMT
 CEMT master_term_cmd 
CEMT executes a CICS master terminal command from REXX.
Operands
master_term_cmd
specifies a command string passed as input to the CEMT transaction program.
Return Codes
nspecifies the return code passed back by CICS if an error is detected
0Normal return
-101 Invalid command
Any warning or error messages are placed in the variable CEMTTOUT. The results of the execution, if any,
are placed in the variable CEMTEOUT. The maximum length returned in CEMTEOUT is approximately
28K bytes. Each variable has the following format:
vBinary halfword containing inclusive length of field.
vBinary halfword containing the number of messages produced.
vBinary halfword containing the highest message-severity: 0and 4continue to execution; 8and 12 do not
continue to execution.
vVariable-length data containing:
– For CEMTTOUT: messages produced from translation stage of command
– For CEMTEOUT: messages produced from execution stage of command
The format of this data is not guaranteed from release to release, but it is the same as that displayed by
CEMT.
Example
’CEMT SET PROGRAM(XYZ) NEWCOPY’
This example shows a CICS command passed to the CEMT transaction program for execution.
Commands
324 CICS TS for VSE/ESA: REXX Guide
CLD
 CLD
dirid

CLD changes your current RLS list directory.
Operands
dirid
specifies a partial or full REXX List System directory that becomes the new current working directory
for you.
If dirid is not specified, the current working directory is retrieved and placed into the REXX variable
RESULT, instead of changing the current working directory.
A full directory ID starts with a slash and is in the form: \dirid1\...\diridn
When you specify a full directory ID, it completely replaces the previous directory setting.
A partial directory ID does not begin with a slash. In this case, the partial directory ID is appended to
the end of the existing directory ID. If the partial directory ID begins with two periods, this indicates
that one directory level is removed (from the right), before the new partial directory ID is appended to
the end. In this case, a backslash is required before the directory ID.
For example: If the current directory is \USERS\USER1\ABC and you enter CLD ..\XYZ the new
current directory will be \USERS\USER1\XYZ.
The default directory ID for you is \USERS\genid\, where genid is your CICS signon user ID. If you are
not signed onto CICS, genid defaults to the value in DFLTUSER.
Return Codes
0Normal return
923 Error in storing current RLS directory information
924 RLS directory does not exist or access not authorized
925 Error in retrieving directory information
926 Invalid directory
927 Cannot go back past root directory
928 Error setting result value
Examples
’CLD \USERS\USER2\XYZ’
This example changes your current working list directory to \USERS\USER2\XYZ regardless of the
previous directory setting.
If your current directory is \USERS\USER2 and you enter:
’CLD XYZ’
then your current directory is changed to \USERS\USER2\XYZ.
Notes
1. The current directory (specified by the CLD command) is always searched first, attempting to locate an
RLS list with the appropriate list name.
2. A fully qualified RLS file name bypasses the search of your directories.
Commands
Chapter 25. REXX/CICS Commands 325
CONVTMAP
 CONVTMAP lib.sublib(mem.type)rfs_fileid 
CONVTMAP reads a VSE Librarian sublibrary member and converts a DSECT (created by a previously
assembled BMS map) into a structure, and stores the result in a REXX File System file. The BMS map
used as input to CONVTMAP must be in assembler language format. The resulting output file is formatted
as a REXX file structure.
Operands
lib.sublib(mem.type)
specifies a VSE Librarian sublibrary member.
rfs_fileid
specifies a fully qualified REXX File system file, or only the REXX file name. If a fully qualified name is
not supplied, the curent REXX directory is used to store the file.
Return Codes
nspecifies the return code from the attempt to process the VSE Librarian sublibrary member.
0Normal return
-302 Invalid operand
-321 Invalid input record
-322 RFS error writing output file
1736 CICSEXC1 link error
1744 Not authorized
1747 CICSEXC1 return code was invalid
Example
’CONVTMAP REXX.REXC(MAP1) POOL1:\USERS\USER1\MAP1.DATA’
This example shows the input BMS map DSECT, MAP1, a member in the VSE Librarian sublibrary
REXX.REXC, being formatted and written out to the RFS file POOL1:\USERS\USER1\MAP1.DATA.
Commands
326 CICS TS for VSE/ESA: REXX Guide
COPYR2S
Note: This is an authorized command.
 COPYR2S source_vname stor_anchor offset
*length
struct_vname fieldname
struct_name fieldname

COPYR2S copies REXX variable contents to GETMAINed storage.
Operands
source_vname
specifies the REXX variable containing the value copied to the previously GETMAINed area.
Note: This value should be in quotes so that substitution does not occur.
*specifies that all the REXX variables are copied. If you specify an asterisk (*) you cannot specify
fieldname.
stor_anchor
specifies the REXX variable containing the anchor for the target storage area that was GETMAINed
earlier. This anchor consists of four bytes, containing the address of the earlier GETMAINed storage.
offset
specifies the displacement into the previously GETMAINed storage area, that the contents of the
REXX variable is copied to. The first byte of the area is indicated by a displacement of zero.
length
specifies the length in decimal bytes of the copy performed. If this length is specified, then the
contents of the source REXX variable is truncated, or padded with blanks to match this length, and
then copied. However, the source REXX variable is not altered in this process. If this length is omitted,
then the current length of the source REXX variable, is used.
struct_vname
specifies a REXX variable containing a structure definition (or mapping) of the fields in the
GETMAINed storage area. The format of the data in this variable is: field1_name length ...
fieldn_name length. This capability is provided so that field displacements are easily calculated and
changed, from a central location.
struct_name
specifies the structure file ID containing a structure definition (or mapping) of the fields in the
GETMAINed storage area.
Structures are made up of records in the following format: fieldname location length type, where:
fieldname
specifiesa1to12character symbolic name of the field.
location
specifies the position in structure that this field starts (the first position is 1).
length
specifies decimal length of this field in bytes.
type
specifies the field data type: C (character), F (fullword), or H (halfword).
fieldname
isa1to12character symbolic name associated with the destination field for this copy. This name
must exist in the above specified REXX variable or structure definition file. The fieldname must be
specified when struct_vname or struct_name is specified.
Commands
Chapter 25. REXX/CICS Commands 327
Return Codes
0Normal return
2002 Invalid operand
2021 Invalid structure definition
2022 Invalid variable structure definition
2023 Field name not found
2025 Failure processing GETVAR request
2026 Invalid numeric input
2027 RFS read error
2028 Invalid offset
2029 Invalid length value
Examples
/* Needed if entering example from the REXXTRY utility */
’PSEUDO OFF’
’CICS GETMAIN SET(WORKANC) LENGTH(200)’/* get 200 bytes of working storage */
VAR1 = ’00000000’x /* set a REXX variable with 4 bytes of hex */
’COPYR2S VAR1 WORKANC 4’
This example requests 200 bytes of virtual storage and copies the hex value of '00000000'x into bytes 4
through 7 of that area.
’CICS GETMAIN SET(WORKANC) LENGTH(200)’/* get 200 bytes of working storage */
VAR1 = ’ABC’ /* set a REXX variable with 3 characters */
struct1 = ’flda 4 fldb 2 fldc 3 fldd 8 flde 5’
’COPYR2S VAR1 WORKANC STRUCT1 FLDC’
This example requests 200 bytes of virtual storage and copies the character string ABC to position 7 of the
GETMAINed area referenced by anchor WORKANC.
Commands
328 CICS TS for VSE/ESA: REXX Guide
COPYS2R
Note: This is an authorized command.
 COPYS2R stor_anchor vname offset length
*struct_vname fieldname
struct_name fieldname

COPYS2R copies data from GETMAINed storage to a REXX variable.
Operands
stor_anchor
specifies the REXX variable containing the anchor for the target storage area that was GETMAINed
earlier. This anchor consists of four bytes, containing the address of the earlier GETMAINed storage.
specifies that all the REXX variables are copied. If you specify an asterisk (*) you cannot specify
fieldname.
vname
specifies the REXX variable containing the value to be copied from the previously GETMAINed area.
Note: This value should be in quotes so that substitution does not occur.
offset
specifies the displacement into the previously GETMAINed storage area, that the contents of the
REXX variable is copied to. The first byte of the area is indicated by a displacement of zero.
length
specifies the length in decimal bytes of the copy performed. If this length is specified, then the
contents of the source REXX variable is truncated, or padded with blanks to match this length, and
then copied. However, the source REXX variable is not altered in this process. If this length is omitted,
then the current length of the source REXX variable, is used.
struct_vname
specifies a REXX variable containing a structure definition (or mapping) of the fields in the
GETMAINed storage area. The format of the data in this variable is: field1_name length ...
fieldn_name length. This capability is provided so that field displacements are easily calculated and
changed, from a central location.
struct_name
specifies the structure file ID containing a structure definition (or mapping) of the fields in the
GETMAINed storage area.
Structures are made up of records in the following format: fieldname location length type, where:
fieldname
specifiesa1to12character symbolic name of the field.
location
specifies the position in structure that this field starts (the first position is 1).
length
specifies decimal length of this field in bytes.
type
specifies the field data type: C (character), F (fullword), or H (halfword).
fieldname
isa1to12character symbolic name associated with the destination field for this copy. This name
must exist in the above specified REXX variable or structure definition file. The fieldname must be
specified when struct_vname or struct_name is specified.
Commands
Chapter 25. REXX/CICS Commands 329
Return Codes
0Normal return
2102 Invalid operand
2121 Invalid structure definition
2122 Invalid variable structure definition
2123 Field name not found
2125 Failure processing GETVAR request
2126 Invalid numeric input
2127 RFS read error
2128 Invalid offset
2129 Invalid length value
Example
var1 = ’’ /* set REXX variable VAR1 to null */
struct1 = ’flda 4 fldb 2 fldc 3 fldd 8 flde 5’
’COPYS2R WORKANC VAR1 STRUCT1 FLDC’
This example copies three bytes of data from positions 7 through 9 of the earlier GETMAINed storage
area anchored by the fullword address in REXX variable WORKANC, and copies it to REXX variable
VAR1.
Notes
1. Anchor addresses are not limited to being set by the GETMAIN command. For example, a COPYS2R
can be used to copy a fullword address of a GETMAINed area to a REXX variable that is used as the
anchor for a subsequent COPYS2R or COPYR2S.
2. There can be multiple structure (field) definitions for a GETMAINed area; they can overlap, be nested,
and used to redefine fields.
3. Anchor addresses do not need to point to the beginning of a GETMAINed area. It is important,
however, that anchor addresses are within a GETMAINed area that you own, and that any operation
on them does not exceed their boundaries.
Commands
330 CICS TS for VSE/ESA: REXX Guide
C2S
 C2S client_rexx_varname
server_rexx_varname

C2S copies a client REXX variable to a server REXX variable.
Operands
client_rexx_varname
specifies the client REXX variable to copy from.
server_rexx_varname
is an optional name that specifies the server REXX variable to copy into. If it is not specified, it
defaults to the same as the client_rexx_varname.
Return Codes
0Normal return
2440 No variable name specified
2441 Error retrieving variable
2442 Error storing variable
2448 No client available
Example
’C2S VARA VARB’
This example shows that the contents of the client REXX variable VARA are copied into the server REXX
variable VARB. The length of VARB is the same as the length of VARA.
Notes
vThe maximum variable name length supported for this command is 250 characters.
vThis command is intended for use only by REXX/CICS server execs (for example, exec defined by
DEFCMD or DEFSCMD).
Commands
Chapter 25. REXX/CICS Commands 331
DEFCMD
 DEFCMD etarget ecmdnm
etarget *
itarget icmdnm
itarget *
==
pgmname
CICS_loadmod
execname
( CLEAR
( CICSLINK
CICSLOAD AUTH
REXX

DEFCMD defines (or redefines) REXX user commands.
Operands
etarget
is the 1 to 8 character name of the external target environment you used in a REXX exec issuing this
command. This is the external environment name that you directed the command string to. This
environment name is looked up in a table and together with the command name determines which
REXX program the command string is directed to for processing.
Note: The external target can match the environment name on the ADDRESS keyword instruction or,
if REXXCICS is the current environment (the default condition), can be specified as the first
token of the command string.
ecmdnm
is the first command name token that you used issuing this command. This is the first word of the
command name as it is known to you. If a special value of asterisk (*) is specified (as part of this
definition), then all commands that you issued with an environment name of etarget and that are not
more explicitly defined elsewhere, are covered by this command definition. Command names may be
up to 16 characters long.
itarget
specifies an internal environment name that this command definition passes to the agent that
processes the command string. This is needed so that the external environment names known to you
can be redefined without breakage of the agents that process these commands. If the internal and
external names are identical, then there is no need for you to specify the internal name. A special
value of “=” indicates that itarget is the same as etarget.
icmdnm
is the first word of the internal command name. This is the first part of the command name that is
passed to the REXX command agent to specify what command is processed. This is specified only if it
is different from ecmdnm. A special value of “=” indicates that icmdnm is the same as ecmdnm.
pgmname
specifies the CICS program that is called by an EXEC CICS LINK to process the command.
CICS_loadmod
specifies the name of the CICS program called because the CICSLOAD option was specified.
Note: The program is only loaded on the first instance of a command and its address is remembered
for subsequent commands.
execname
specifies the exec called as a REXX command server processing this command (or commands). If this
server exec is already running then this command is routed to the executing server. If a REXX server
by this name is not running, then Automatic Server Initiation (ASI) is used to start the server
automatically. The execname can be either a file name (where the file type defaults to EXEC) or it can
be in the form filename.filetype.
CICSLINK
is a keyword indicating that the processing agent for the defined REXX command is a standard CICS
program that is called by an EXEC CICS LINK.
Commands
332 CICS TS for VSE/ESA: REXX Guide
CICSLOAD
is a keyword indicating that the processing agent is a CICS program that is loaded by an EXEC
CICSLOAD.
REXX
is a keyword indicating that the processing agent for this REXX command is a REXX exec that
operates as a command server.
AUTH
Note: This is an authorized option.
is a keyword indicating that this is an authorized REXX/CICS command. It is a command that can only
be executed by an authorized REXX/CICS user (specified on AUTHUSER command) or from within an
exec loaded from an authorized library.
CLEAR
is a keyword indicating that the purpose of this DEFCMD is to clear any previous definitions for the
specified external target environment and command names.
Return Codes
0Normal return
1001 Invalid command
1021 Cannot load program
1023 Entry not found
1048 No client available
1099 Internal error
Example
’DEFCMD CICS SEND = = SENDPGM (CICSLINK’
This example defines a command called SEND for this user only. The user can issue this command, under
the default command environment of REXXCICS, by entering:
’CICS SEND arg1 arg2 ... argn’
This example shows program SENDPGM being called by an EXEC CICS LINK command to process this
command.
Notes
1. When the REXX/CICS environment name is REXXCICS (which is the default when all execs or
macros are called), then the first token of the command string is the environment name that could
have been used with an ADDRESS environment REXX instruction. This provides a more integrated
command environment and removes the need for constant environment switching by ADDRESS
instructions.
2. The calling and parameter passing sequences for command programs receiving control by an EXEC
CICS LINK and an Assembler BASSM instruction (the CICSLOAD option) are similar. Refer to
Chapter 21, “REXX/CICS Command Definition,” on page 281 for more information on writing command
programs.
3. You can use DEFCMD to dynamically tailor a user's command set on a user by user, or application by
application basis. DEFCMD commands can be placed in the user's PROFILE EXEC or in application
execs. DEFCMD can also be used to override system command definitions.
4. DEFCMD REXXCICS * is not allowed.
5. User command definitions are searched before system command definitions (except for DEFCMD,
which cannot be overridden).
6. REXX commands can be written in REXX. These REXX commands in turn call other REXX commands
which are written in REXX, in a building block fashion. Since DEFCMD hides the implementation detail
Commands
Chapter 25. REXX/CICS Commands 333
from the REXX user (programmer), a command can be quickly written in REXX and later transparently
rewritten in another language, if it becomes performance critical.
Commands
334 CICS TS for VSE/ESA: REXX Guide
DEFSCMD
Note: This is an authorized command.
 DEFSCMD etarget ecmdnm
etarget *
**
itarget icmdnm
itarget *
==
pgmname
CICS_loadmod
execname
( CLEAR
( CICSLINK
CICSLOAD
REXX
AUTH

DEFSCMD defines (or redefines) REXX system commands.
Operands
etarget
is the name of the external target environment you used in a REXX exec issuing this command. This
is the external environment name that you directed the command string to. This environment name is
looked up in a table and together with the command name determines which program, REXX exec, or
queue this command string is directed to for processing.
Note: The external target can match the environment name on the ADDRESS keyword instruction or
can be specified as the first token of the command string, if REXXCICS is the current
environment (which is the default).
ecmdnm
is the first command name token that you used issuing this command. This is the first word of the
command name as it is known to you. If a special value of asterisk (*) is specified (as part of this
definition), then all commands that you issued with an environment name of etarget and that are not
more explicitly defined elsewhere, are covered by this command definition.
itarget
specifies an internal environment name that this command definition passes to the agent that
processes the command string. This is needed so that the external environment names known to you
can be redefined without breakage of the agents that process these commands. If the internal and
external names are identical, then there is no need for you to specify the internal name. A special
value of “=” indicates that itarget is the same as etarget.
icmdnm
is the first word of the internal command name. This is the first part of the command name that is
passed to the REXX command agent to specify what command is processed. This is specified only if it
is different from ecmdnm. A special value of “=” indicates that icmdnm is the same as ecmdnm.
pgmname
specifies the CICS program that is called by an EXEC CICS LINK to process the command.
CICS_loadmod
specifies the name of the CICS program called because the CICSLOAD option was specified.
Note: The program is only loaded on the first instance of a command and its address is remembered
for subsequent commands.
execname
specifies the exec called as a REXX command server processing this command (or commands). If this
server exec is already running then this command is routed to the executing server. If a REXX server
by this name is not running, then Automatic Server Initiation (ASI) is used to start the server
automatically. The execname can be either a file name (where the file type defaults to EXEC) or it can
be in the form filename.filetype.
Commands
Chapter 25. REXX/CICS Commands 335
CICSLINK
is a keyword indicating that the processing agent for the defined REXX command is a standard CICS
program that is called by an EXEC CICS LINK.
CICSLOAD
is a keyword indicating that the processing agent is a CICS program that is loaded by an EXEC
CICSLOAD.
REXX
is a keyword indicating that the processing agent for this REXX command is a REXX exec that
operates as a command server.
AUTH
is a keyword indicating that this is an authorized REXX/CICS command. It is a command that can only
be executed by an authorized REXX/CICS user (specified on AUTHUSER command) or from within an
exec loaded from an authorized library.
CLEAR
is a keyword indicating that the purpose of this DEFSCMD is to clear any previous definitions for the
specified external target environment and command names.
Return Codes
0Normal return
1101 Invalid command
1121 Cannot load program
1123 Entry not found
1148 No client available
1199 Internal error
Example
’DEFSCMD CICS SEND = = SENDPGM (CICSLINK’
This example defines a command called SEND for this user only. The user can issue this command, under
the default command environment of REXXCICS, by entering:
’CICS SEND arg1 arg2 ... argn’
This example shows program SENDPGM being called by an EXEC CICS LINK command to process this
command.
Notes
1. When the REXX/CICS environment name is REXXCICS (which is the default when all execs or
macros are called), then the first token of the command string is the environment name that could
have been used with an ADDRESS environment REXX instruction. This provides a more integrated
command environment and removes the need for constant environment switching by ADDRESS
instructions.
2. The calling and parameter passing sequences for command programs receiving control by an EXEC
CICS LINK and an Assembler BASSM instruction (the CICSLOAD option) are similar. Refer to
Chapter 21, “REXX/CICS Command Definition,” on page 281 for more information on writing command
programs.
3. If the first two operands of DEFSCMD are all asterisks (* *) then this is a catch-all definition that
specifies a command processing agent issued for REXX commands that are not under the scope (do
not match) of any more specific command definitions.
4. User command definitions are searched before system command definitions (except for DEFSCMD,
which cannot be overridden).
Commands
336 CICS TS for VSE/ESA: REXX Guide
5. REXX commands can be written in REXX. These REXX commands in turn call other REXX commands
which are written in REXX, in a building block fashion. Since DEFSCMD hides the implementation
detail from the REXX user (programmer), a command can be quickly written in REXX and later
transparently rewritten in another language, if it becomes performance critical.
Commands
Chapter 25. REXX/CICS Commands 337
DEFTRNID
Note: This is an authorized command.
 DEFTRNID trnid execname
CLEAR

DEFTRNID is a region-wide authorized command that can be used to define the name of an exec to be
invoked for a particular CICS transaction identifier.
Operands
trnid
specifies a one to four character CICS transaction ID.
execname
specifiesa1to17character REXX/CICS exec name, in the form: filename.filetype if it is in the REXX
File System. If the exec exists in a VSE Librarian sublibrary, this is the name (a member type of .proc
is assumed).
CLEAR
is a keyword indicating that the definition be removed for this transaction ID.
Return Codes
0Normal return
1202 Invalid operand
1222 Invalid option
1223 Error storing trantable information
1225 Error retrieving trantable information
1226 Exec name length error
1228 Error setting trantable value
1233 Transaction not found in table
Example
Define a new CICS transaction ID named XYZ, make it call exec TESTEXEC when it is started, then take the
following steps:
1. Create TESTEXEC in the RFS or in a VSE Librarian sublibrary.
2. Under REXX/CICS REXXTRY utility enter command DEFTRNID XYZ TESTEXEC and exit the REXXTRY
utility.
3. Under RDO, CEDA DEFINE TRAN(XYZ) PROGRAM(CICREXD) TWASIZE(32) GROUP(REXXCICS) and install
TRAN(XYZ) GROUP(REXXCICS).
Note: TWASIZE is required on CEDA define
4. Clear the screen and type CICS transaction identifier XYZ and press ENTER. The TESTEXEC exec
should now run.
Notes
1. DEFTRNID definitions should usually be placed in the CICSTART exec that executes at REXX/CICS
startup.
2. The transaction ID has to be defined (by CEDA) to invoke the supplied CICREXD program.
Commands
338 CICS TS for VSE/ESA: REXX Guide
DIR
 DIR
dirid (stem.

DIR displays the current directory contents or optionally returns the directory contents in a REXX
compound variable.
Operands
dirid
specifies the partial or full REXX File System directory that is displayed. If you omit this, then the
current directory is displayed.
stem.
specifies the name of a stem. (A stem must end in a period.) Stem.0 contains the number of elements
in the entry. (Refer to section “Stems” on page 123 for more information.) If you omit this, the contents
are displayed on the screen.
Return Codes
0Normal return
321 Cannot access current RFS directory information
322 Invalid stem name
325 Error retrieving RFS directory
Examples
’DIR \USERS\USER2 (X.’
This example places the directory contents of \USERS\USER2 into the REXX compound variable X.1
through X.n.X.0 contains the number of elements returned.
Note
The current directory is specified by the CD command.
Commands
Chapter 25. REXX/CICS Commands 339
EDIT
 EDIT
NONAME
fileid
lib.sublib(mem.type) LIB
( MACRO macroname

EDIT opens a new edit session.
Operands
NONAME
a file ID is not specified. This is the default.
fileid
specifies the file ID of the file to be created or edited.
lib.sublib(mem.type)
specifies a VSE Librarian sublibrary and member to be edited.
LIB
is a keyword that follows a VSE Librarian sublibrary member name when a sublibrary member is being
edited.
MACRO
is a keyword specifying a group of instructions applied to the file being edited.
macroname
specifies the file name portion of the profile macro file ID (REXX exec name).
Return Codes
0Normal return
201 Invalid command
204 Not authorized
211 Invalid file ID
226 File is currently being edited
237 CICSEXC1 link error
238 CICSEXC1 return code was invalid
299 Internal error
Example
’CD \USERS\USER2\’ /* specify current working directory */
’EDIT TEST.EXEC’ /* edit an existing file in the PATH */
/* or create new file in current dir */
This example edits member TEST.EXEC in directory \USERS\USER2.
Note
Refer to Chapter 18, “REXX/CICS Text Editor,” on page 231 for more information about the REXX/CICS
editor.
Commands
340 CICS TS for VSE/ESA: REXX Guide
EXEC
 EXEC execid args 
EXEC calls a REXX exec at a lower level (as a nested exec). All variables for this new exec are kept
separate from the higher level exec, which is suspended until the nested exec ends.
Operands
execid
specifies the 1 to 17 character identifier of the exec.
args
specifies the argument string being passed to the called exec.
Return Codes
nspecifies the return code set by the exit of the called exec
0Normal return
-3 Exec not found
-10 Exec name not specified
-11 Invalid exec name
-12 GETMAIN error
-99 Internal error
Example
’EXEC ABC’
This example executes exec ABC.EXEC.
Commands
Chapter 25. REXX/CICS Commands 341
EXECDROP
Note: This is an authorized command.
 EXECDROP AUTHClib member
AUTHElib
PROClib
name
MEM
(
RFS
LIB

EXECDROP removes an EXECLOADed exec from virtual storage.
Operands
AUTHClib
indicates that member was loaded from an authorized command sublibrary.
AUTHElib
indicates that member was loaded from an authorized exec sublibrary.
LIB
indicates that a VSE Librarian sublibrary and member has been specified.
member
specifies the VSE Librarian sublibrary member that contains the exec to be removed from virtual
storage.
Note: The member type must not be specified. A member type of PROC is assumed.
MEM
indicates that a member name has been specified.
name
specifies a fully qualified RFS file name or a VSE Librarian sublibrary and member.
Note: The member type must not be specified for a sublibrary and member. A member type of PROC
is assumed.
PROClib
indicates that member was loaded from a sublibrary in the LIBDEF PROC search chain for the CICS
partition.
RFS
indicates that an RFS file has been specified.
Return Codes
0Normal return
1401 Invalid command
1402 Invalid operand
1423 Error storing EXECLOAD information
1425 Error retrieving EXECLOAD information
1448 No client available
Example
’EXECDROP POOL1:\USERS\USER2\TEST.EXEC (RFS’
This example removes RFS file from virtual storage.
Commands
342 CICS TS for VSE/ESA: REXX Guide
Note
If a partial directory ID is given, it is temporarily appended to the end of the current working directory value
to get a fully qualified directory ID.
Commands
Chapter 25. REXX/CICS Commands 343
EXECIO
 EXECIO lines
*
READ tsqname
WRITE tsqname
stem.
varname recno

EXECIO performs file input/output to a CICS temporary storage queue.
Operands
lines
specifies the number of lines to read or write. An asterisk (*) is a special case that is specified for
READ operations only, and indicates that the file is read from the target line (or line 1 if no target line
is specified) to the end of the file.
READ
reads one or more records from a CICS temporary storage queue (TSQ).
WRITE
writes (or re-writes ) one or more records to a CICS temporary storage queue.
tsqname
specifiesa1to8character temporary storage queue name.
stem.
specifies the name of a stem. (A stem must end in a period.) Refer to section “Stems” on page 123 for
more information.
varname
specifies a REXX variable name that is the source or target for this EXECIO operation.
recno
specifies a record number in the temporary storage queue that READ or WRITE begins with.
Return Codes
nspecifies the return code passed back by CICS if an error is detected
0Normal return
-202 Invalid operand
-221 Too many operands specified
-222 Recno operand out of range
-224 Lines operand invalid
Examples
x.1 = ’line 1’
x.2 = ’Line Two’
’EXECIO 2 WRITE QUEUE1 X.’
This example writes data to a CICS temporary storage queue.
’EXECIO 2 READ QUEUE1 Y.’
say y.0 /* ==> 2 */
say y.1 /* ==> ’line 1’ */
say y.2 /* ==> ’Line Two’ */
This example reads data from a temporary storage queue.
Notes
1. The maximum record length allowed is 256 bytes.
Commands
344 CICS TS for VSE/ESA: REXX Guide
2. If a stem is specified for a READ operation (and a stem should be specified if more than one record is
read), the actual number of records read is placed into stem.0.
3. Use the CICS-supplied CEBR transaction to browse temporary storage queues. For example, enter:
CEBR QUEUE1 to look at the queue created above.
4. CEBR provides PUT and GET functions that you can use to copy between external files and CICS
temporary storage queues.
Commands
Chapter 25. REXX/CICS Commands 345
EXECLOAD
Note: This is an authorized command.
 EXECLOAD AUTHClib member
AUTHElib
PROClib
name
MEM
(
RFS
LIB

EXECLOAD loads an exec into virtual storage.
Operands
AUTHClib
indicates that member must be loaded from an authorized command sublibrary.
AUTHElib
indicates that member must be loaded from an authorized exec sublibrary.
LIB
indicates that a VSE Librarian sublibrary and member has been specified.
MEM
indicates that a member name has been specified.
member
specifies the VSE Librarian sublibrary member that contains the exec to be loaded into virtual storage.
Note: The member type must not be specified. A member type of PROC is assumed.
name
specifies a fully qualified RFS file name or a VSE Librarian sublibrary and member.
Note: For a sublibrary and member, the member type must not be specified. A member type of PROC
is assumed.
PROClib
indicates that member must be loaded from a sublibrary in the LIBDEF PROC search chain for the
CICS partition.
RFS
indicates that an RFS file has been specified.
Return Codes
0Normal return
1501 Invalid command
1502 Invalid operand
1523 Error storing EXECLOAD information
1525 Error retrieving EXECLOAD information
1530 Unable to link to CICLIBR routine
1531 Error returned from CICLIBR routine
1532 Error returned from RFS READ
1547 GETMAIN error
1548 No client available
1599 Internal error
Commands
346 CICS TS for VSE/ESA: REXX Guide
Example
’EXECLOAD POOL1:\USERS\USER2\TEST.EXEC (RFS’
This example loads the exec TEST.EXEC from RFS into storage. Subsequent calls of TEXT.EXEC will use
the loaded copy.
Notes
1. If an exec is loaded into virtual storage, it is automatically shared by all users.
2. If an EXECLOAD is performed to replace an in-storage exec with a newer copy, a shadow of previous
copies is kept in virtual storage until all active execs based on these copies end. This is accomplished
by a use count.
Commands
Chapter 25. REXX/CICS Commands 347
EXECMAP
 EXECMAP 
EXECMAP returns the sublibraries and members, the number of users, the descriptor table start (in hex),
and the amount of storage required of the execs that have been loaded using EXECLOAD.
Return Codes
0Normal return
1623 EXECLOAD directory not found
Example
’EXECMAP’
If the exec POOL1:\USERS\USER1\TEST.EXEC had been EXECLOADed then this display would result.
EXEC name Use Location Size Fully Qualified Name
TEST.EXEC 0 09369083 287 POOL1:\USERS\USER1\TEST.EXEC
Commands
348 CICS TS for VSE/ESA: REXX Guide
EXPORT
 EXPORT rfs_fileid lib.sublib(mem.type) 
EXPORT exports an RFS file to a VSE Librarian sublibrary member.
Operands
rfs_fileid
specifies a fully qualified REXX File System file ID.
lib.sublib(mem.type)
specifies a VSE Librarian sublibrary and member.
Return Codes
0Normal return
1701 Invalid command
1702 Invalid operand
1723 RFS write error
1724 RFS read error
1733 Input for export not found
1736 Unexpected CICS error. This might be due to a CICSEXC1 link error.
1738 Invalid VSE Librarian member name
1741 Unsupported record format
1744 Not authorized
1747 CICSEXC1 return code was invalid
1799 Internal error
Example
’EXPORT POOL1:\USERS\USER1\TEST.DATA USER1.TEST(MEM1.PROC)
This example copies POOL1:\USERS\USER1\TEST.DATA from an RFS file to a VSE Librarian sublibrary
and member.
Notes
The sublibrary specified in lib.sublib must exist. If the member specified in lib.sublib(mem.type) exits, it
is replaced by the contents of the RFS file specified in rfs_fileid. If the member does not exist, it is
created in the specified sublibrary.
Commands
Chapter 25. REXX/CICS Commands 349
FILEPOOL
Note: This is an authorized command.
 FILEPOOL DEFINE poolid dirid fileid (
USER
FORMAT poolid
ADD poolid fileid

FILEPOOL performs RFS file pool administration activities.
Operands
DEFINE
defines a new RFS file pool.
poolid
specifies the name of the target file pool.
dirid
specifies the CICS file identifier of the file pool directory.
fileid
specifies the CICS file identifier of the VSAM file for the file pool.
USER
is an optional keyword indicating that this is a user file pool, and you automatically have a \USERS
directory created, so that multiple users share this file pool, using RFS security (as compared to CICS
security) to control access to directories.
FORMAT
formats the first file in a new RFS file pool.
ADD
adds an additional VSAM file to an existing file pool.
Return Codes
0Normal return
1802 Invalid operand
1821 Invalid file pool subcommand
1822 File pool subcommand not specified
1823 Error storing file pool information
1824 File pool ID not specified
1825 Error retrieving file pool information
1826 Invalid file pool ID
1827 Invalid file pool data retrieved
1828 File pool not defined
1829 RFS could not add library to file pool
1830 RFS could not create users directory
1831 CICS file identifier for the file pool must be specified
1832 Invalid CICS file identifier
1833 File pool variable corrupted
1834 Pool ID already exists
1835 CICS file identifier already used
1836 Could not format file pool
1837 File pool needs to be formatted first
1838 File pool ADD record is full
1839 File ID is not found
Commands
350 CICS TS for VSE/ESA: REXX Guide
Example
’FILEPOOL DEFINE POOL1 REXXDIR1 REXXLIB1 (USER’
This example defines file pool POOL1 and tells RFS the CICS file definition to use is REXXLIB1. It also
indicates to the FILEPOOL FORMAT command to issue an RFS MKDIR to build the \USERS directory.
Note
This is an authorized command, performed by a REXX/CICS administrator or systems programmer.
Commands
Chapter 25. REXX/CICS Commands 351
FLST
 FLST
dirid

FLST calls the file list utility to work with the files.
Operands
dirid
specifies an optional full or partial directory ID that a file list is displayed. If you do not specify dirid,it
defaults to the current working directory.
Return Codes
FLST returns the return code given by RFS.
Example
’FLST’
This example displays the file list for the member of the current working directory.
Notes
1. The default user profile macro that the FLST tries to call is EXEC ID FLSTPROF. The FLSTPROF
macro provides the capability for you (or a group of users) to specify your own unique defaults.
2. Refer to Chapter 19, “REXX/CICS File System,” on page 257 for more information about the REXX
File System.
Commands
352 CICS TS for VSE/ESA: REXX Guide
GETVERS
 GETVERS 
GETVERS retrieves the current REXX/CICS, program name, version, and compile time information, and
places it into the REXX variable VERSION. The returned information is in the form: VxRyMmmmm
mm/dd/yy hh.mm, where:
xspecifies the REXX/CICS Version number.
yspecifies the REXX/CICS Release number.
mm/dd/yy
specifies the compile date for the REXX/CICS base program.
hh.mm
specifies the compile time for the REXX/CICS base program.
Return Codes
0Normal return
1910 Request failed
Example
’GETVERS’
This example retrieves the current REXX/CICS version and compile time information and places it into the
REXX variable VERSION. Its format could look like: V1R1M0000 03/07/94 12:00.
Commands
Chapter 25. REXX/CICS Commands 353
HELP
 HELP
search_term

HELP browses or searches this book (the IBM REXX Development System for CICS/ TS for VSE/ESA)
online.
Operands
search_term
specifies the string you want located.
Return Codes
nspecifies the return code passed by from internal RFS or PANEL commands
0Normal return
Commands
354 CICS TS for VSE/ESA: REXX Guide
IMPORT
 IMPORT lib.sublib(mem.type)rfs_fileid 
IMPORT imports a VSE Librarian sublibrary member to an RFS file.
Operands
lib.sublib(mem.type)
specifies a VSE Librarian sublibrary and member.
rfs_fileid
specifies a fully qualified REXX File System file ID.
Return Codes
0Normal return
1701 Invalid command
1702 Invalid operand
1723 RFS write error
1724 RFS read error
1733 Input for export not found
1736 Unexpected CICS error. This might be due to a CICSEXC1 link error.
1738 Invalid VSE Librarian member name
1741 Unsupported record format
1744 Not authorized
1747 CICSEXC1 return code was invalid
1799 Internal error
Example
’IMPORT USER1.TEST(MEM1.PROC) POOL1:\USERS\USER1\TEST.DATA’
This example copies a VSE Librarian sublibrary member USER1.TEST(MEM1.PROC) to the RFS file
POOL1:\USERS\USER1\TEST.DATA.
Commands
Chapter 25. REXX/CICS Commands 355
LISTCMD
 LISTCMD
envname cmdname

LISTCMD lists REXX command definition information (previously specified by DEFCMD).
Operands
envname
specifies the name of the command environment defined using DEFCMD or DEFSCMD.
cmdname
specifies the name of a command specified in DEFCMD or DEFSCMD.
Return Codes
0Normal return
821 Invalid environment name
822 Invalid command name
Example
’LISTCMD EDITSVR MYCMD’
This example returns the information defined in DEFCMD for the subcommand MYCMD.
Commands
356 CICS TS for VSE/ESA: REXX Guide
LISTCLIB
 LISTCLIB
stem.

LISTCLIB displays the names of the authorized command libraries to the terminal or to a specified stem
array, if a stem has been specified. The libraries are displayed in their search order.
Operands
stem.
specifies the name of a stem. (A stem must end in a period.) The information returned is the name of
each VSE Librarian sublibrary specified on the last SETSYS AUTHCLIB command.
Return Codes
2226 Invalid stem varible name
2245 Error retrieving authorized library information
Example
’LISTCLIB LST.’
This example places the names of the VSE Librarian sublibraries containing authorized commands in
compound variable LST.1 through LST.n. They are returned in the search order specified on the last
SETSYS AUTHCLIB command. LST.0 contains the number of elements returned.
Commands
Chapter 25. REXX/CICS Commands 357
LISTELIB
 LISTELIB
stem.

LISTELIB displays the names of the authorized exec libraries to the terminal or to a specified stem array, if
a stem has been specified. The libraries are displayed in their search order.
Operands
stem.
specifies the name of a stem. (A stem must end in a period.) The information returned is the name of
each VSE Librarian sublibrary specified on the last SETSYS AUTHELIB command.
Return Codes
2226 Invalid stem varible name
2245 Error retrieving authorized library information
Example
’LISTELIB LST.’
This example places the names of the VSE Librarian sublibraries containing authorized commands in
compound variable LST.1 through LST.n. They are returned in the search order specified on the last
SETSYS AUTHELIB command. LST.0 contains the number of elements returned.
Commands
358 CICS TS for VSE/ESA: REXX Guide
LISTPOOL
 LISTPOOL
stem.

LISTPOOL displays RFS file pool information to the terminal or to a specified stem array, if a stem has
been specified.
Operands
stem.
specifies the name of a stem. (A stem must end in a period.) Refer to section “Stems” on page 123 for
more information. Three columns of information are returned:
vthe pool ID
vthe DLBL of the first file in the file pool
vwhether or not it contains a user's directory.
Return Codes
0Normal return
2225 Error retrieving file pool information
2226 Invalid stem variable name
Example
’LISTPOOL LST.’
This example places information about the RFS file pools into REXX compound variable LST.1 through
LST.n.LST.0 contains the number of elements returned.
Note
This is a general user command that displays all defined RFS file pools.
Commands
Chapter 25. REXX/CICS Commands 359
LISTTRNID
Note: This is an authorized command.
 LISTTRNID 
LISTTRNID lists the current transaction ID definitions created by the DEFTRNID command.
Return Codes
0Normal return
2325 Error retrieving trantable information
Example
’LISTTRNID’
The CICSTART exec defines the default transactions and their EXEC names. The resulting display is:
TRNID EXEC name
REXX CICRXTRY
EDIT CICEDIT
FLST CICFLST
End of Transaction table list.
Commands
360 CICS TS for VSE/ESA: REXX Guide
PATH
 PATH
;
dirid
lib.sublib

PATH defines the search path for REXX execs.
Operands
dirid
specifies one or more fully qualified REXX File System directories that are searched when you are
attempting to locate an exec to be executed.
A full RFS directory ID starts with a pool ID and is in the form: POOL1:\dirid1\...\diridn
When more than one directory ID is specified, a blank is used to separate them.
lib.sublib
specifies one or more VSE Librarian sublibraries.
Return Codes
0Normal return
625 Error retrieving path information
626 Invalid RFS directory name
628 Error setting RESULT value
629 Invalid VSE Librarian sublibrary
630 Error storing path information
631 No path currently defined
632 Resulting PATH contains no RFS directories or library names
Examples
’PATH POOL1:\USERS\USER2 POOL2:\USERS\USER2\PROJECT1’
This example shows that the directories in this list are searched in the order specified (from left to right).
’PATH REXX1.EXECS REXX2.EXECS’
This example shows you that the search is started with the first VSE Librarian sublibrary.
Notes
1. The dirids and libraries can be intermixed in a single PATH statement.
2. A very long PATH directory list can be created by concatenating strings together into a variable, and
then specifying this variable on the PATH command.
3. PATH command definitions are not carried across CICS restarts. To permanently change a PATH
definition, insert a PATH command into your PROFILE exec in the base directory for your user ID.
4. The PATH command is not cumulative, that is, the last PATH command replaces the previous PATH
definition.
5. If dirid or the library is not specified, the users current working path is retrieved and placed in the
REXX special variable RESULT.
6. If you receive a non-zero return code, the contents of the RESULT special variable are unpredictable.
Commands
Chapter 25. REXX/CICS Commands 361
PSEUDO
 PSEUDO ON
OFF

PSEUDO turns the pseudo-conversational mode on or off.
Operands
ON enables automatic pseudo-conversational support so that when the next REXX PULL instruction or
REXX/CICS WAITREAD command is encountered in the current exec, instead of a conversational
terminal read occurring immediately, an EXEC CICS RETURN TRANSID is used to suspend the exec
until terminal input occurs, and then the terminal read occurs.
OFF
disables (turns off) automatic pseudo-conversational support.
Return Codes
0Normal return
2502 Invalid operand
2521 Operand not specified
Example
’PSEUDO ON’
This example turns the pseudo-conversational mode on.
Note
The PSEUDO ON/OFF setting is temporary. The pseudo setting exists while the current exec is executing.
Any nested execs inherit the current setting of PSEUDO When the current exec ends, the value of pseudo
upon entry to the exec will be restored. The SETSYS PSEUDO command defines the systems default
setting of PSEUDO.
CAUTION:
PSEUDO ON will cause your REXX exec to immediately become pseudo-conversational which will
cause CICS to commit any file changes, and free any non-shared GETMAINed areas, at the next
pseudo-conversational terminal read.
Commands
362 CICS TS for VSE/ESA: REXX Guide
RFS
 RFS
PRIVATE
AUTH dirid
PUBLICR
PUBLICW
SECURED
CKDIR dirid
CKFILE fileid
COPY fileid1 fileid2
DELETE fileid
DATA.
DISKR fileid
stem.
DATA.
DISKW fileid
stem.
GETDIR stem.
dirid
MKDIR dirid
RDIR dirid
RENAME fileid1 fileid2

RFS performs file input/output to the REXX File System.
Operands
AUTH
is a command that authorizes access to RFS directories. The specified access applies to all files in
this directory.
dirid
specifies a REXX File System directory identifier. This is partially or fully qualified. Refer to the CD
command, section “CD” on page 321, for more information.
PRIVATE
specifies that only the owner of the directory has read/write access to the files. This is the default.
PUBLICR
specifies that any user has read-only access to the files in the directory.
PUBLICW
specifies that any user has read/write access to the files in the directory.
SECURED
specifies that an external security manager grants access to the files in the directory.
CKDIR
is a command that checks for an existing RFS directory level.
CKFILE
is a command that checks to see if the specified, partially or fully qualified, file ID exists.
fileid
specifies the file identifier.
COPY
is a command that copies a file, replacing any existing file.
fileid1
specifies the source file identifier, it may be a fully or partially qualified directory and file identifier.
Commands
Chapter 25. REXX/CICS Commands 363
fileid2
specifies the target file identifier, it may be a fully or partially qualified directory and file identifier.
DELETE
is a command that deletes an RFS file.
fileid
specifies the source file identifier, it may be fully or partially qualified.
DISKR
is a command that reads records from an RFS file.
stem
specifies the name of a stem. (A stem must end in a period.) Refer to section “Stems” on page 123 for
more information. The default stem is DATA.
DISKW
is a command that writes records to an RFS file.
GETDIR
is a command that returns a list of the contents of the current or specified directory into the specified
REXX array.
MKDIR
is a command that creates a new RFS directory level.
RDIR
is a command that removes the specified RFS directory.
RENAME
is a command that renames an RFS file to a new name.
fileid1
specifies the source file identifier, it may be a fully or partially qualified directory and file identifier.
fileid2
specifies the source target file identifier, it may be a fully or partially qualified directory and file
identifier.
Return Codes
0Normal return
101 Invalid command
102 Invalid operand
103 File not found
104 Not authorized
105 File already exists
107 Insufficient space in file pool
110 Request failed
111 Invalid file ID
113 Directory not found
115 Directory already exists
116 Directory not specified
121 File corrupted
122 Invalid or out of range stem.0
126 Path error
127 CICS I/O error
128 Command not valid from this location
130 Directory not empty
131 Missing operand
132 Missing file pool data record. File pool is probably not formatted.
199 Internal error
Commands
364 CICS TS for VSE/ESA: REXX Guide
Note
File access security checking is performed at the directory level, rather than the file level. If a specified file
ID is not a fully qualified ID, the current directory or PATH directories are used in an attempt to resolve the
partial name into a fully qualified name; in this case no further checking is necessary. If a fully qualified file
ID is used, the directory it resides in is checked for proper access authorization, at file open time.
Commands
Chapter 25. REXX/CICS Commands 365
RLS
 RLS CKDIR dirid
DELETE listname
*QUEUE*
LPULL varname
queid
*QUEUE*
LPUSH varname
queid
*QUEUE*
LQUEUE varname
queid
MKDIR dirid
DATA.
READ listname
stem. ( UPD
VARDROP varname dirid
VARGET varname dirid
VARPUT varname dirid
DATA.
WRITE listname
stem.

RLS performs list input/output to the REXX List System.
Operands
CKDIR
is a command that checks for an existing RLS directory level.
dirid
specifies a REXX List System directory level identifier. This is partially or fully qualified. Refer to the
CLD command, section “CLD” on page 325, for more information.
DELETE
is a command that deletes an RLS directory level or RLS list.
listname
specifies a REXX List System list identifier. This is partially or fully qualified.
LPULL
is a command that pulls a record from the top of the queue.
varname
specifies a simple REXX variable name. It does not end in a period, distinguishing a variable name
from a stem name.
*QUEUE*
specifies the special default name.
queid
is the identifier for a special type of RLS list accessed by LPULL, LPUSH, or LQUEUE.
LPUSH
is a command that pushes a record onto the top of the queue (LIFO).
LQUEUE
is a command that adds a record to the end of the queue (FIFO).
Commands
366 CICS TS for VSE/ESA: REXX Guide
MKDIR
is a command that creates a new RLS directory level.
READ
is a command that reads records from an RLS list into a stem.
listname
specifies the list identifier.
stem.
specifies the name of a stem. (A stem must end in a period.) Refer to section “Stems” on page 123 for
more information. The default stem is DATA..
UPD
enqueues on a list for update.
VARDROP
is a keyword indicating that an RLS variable is deleted.
VARGET
is a command that takes an RLS variable and copies it into a REXX variable of the same name.
VARPUT
is a command that takes a REXX variable and copies it into an RLS variable of the same name.
WRITE
is a command that writes records to an RLS list from a stem.
Return Codes
0Normal return
701 Invalid command
702 Invalid operand
713 Directory not found
715 Directory already exists
716 Directory not specified
723 List not found
726 List not specified
728 List is in update mode
729 List is not in update mode
730 User is not signed on
732 Queue empty
733 Named queue not found
736 Stem or variable not specified
737 Stem or variable name too long
738 Stem or variable count invalid
743 Block not found
746 CICGETV error
747 GETMAIN error
748 FREEMAIN error
749 ENQ error
750 DEQ error
751 Dynamic area GETMAIN error
752 Error in saved variable data
753 Saved variable not found
754 User not owner of list
Commands
Chapter 25. REXX/CICS Commands 367
SCRNINFO
 SCRNINFO 
SCRNINFO returns a two-digit decimal screen height (in lines) in the variable SCRNHT, and returns a
three-digit decimal screen width (in columns) in the variable SCRNWD.
Return Codes
nspecifies the return code passed back by CICS if an error is detected
0Normal return
-499 Internal error
Example
’SCRNINFO’
Notes
1. The screen information that is returned is obtained by doing an EXEC CICS ASSIGN SCRNHT(scrnht)
SCRNWD(scrnwd).
2. The values for screen height and screen width is 0 if there is no terminal attached.
Commands
368 CICS TS for VSE/ESA: REXX Guide
SET
 SET
(1)
ENG
LANG
CANFR
FRANC
GER
ESPAN
UCENG
HANZI
KANJI
1024
MAXVSTOR
kilobytes
RETRieve pfkeynn
TERM CEBRxxxx
TERMOUT
NOTERM tsq_name
CANCEL

Notes:
1 If no parameters are passed to the SET command, then SET creates a stem variable (SET.) that
contains all of the processing options for the user that was created by the SET or SETSYS
commands.
SET sets the REXX/CICS processing options for the current user.
Operands
LANG
specifies that one of the following languages are available:
ENG
English
CANFR
Canadian French
FRANC
French
GER
German
ESPAN
Spanish
UCENG
Uppercase English
HANZI
Traditional Chinese
KANJi
Kanji
MAXVSTOR
is a keyword placing limits on virtual storage use.
kilobytes
specifies the number of kilobytes.
Commands
Chapter 25. REXX/CICS Commands 369
RETRieve
allows a PF key being set to retrieve the last line entered.
pfkeynn
specifies the PF key number.
TERMOUT
sends terminal line-mode output to a CICS temporary storage queue (for example: SAY and TRACE
output) even when a terminal is attached.
TERM
specifies that linemode output will be sent to the terminal.
NOTERM
specifies that terminal line-mode output is not displayed on the terminal.
CANCEL
specifies that linemode output will not be sent to a CICS temporary storage queue.
tsq_name
specifies the CICS temporary storage queue name. The default tsq_name is CEBRxxxx where xxxx is
your terminal ID. (If you enter the CEBR transaction without specifying a TSQ name, this is the default
name that is used.)
Return Codes
0Normal return
421 Invalid SET subcommand
422 Error storing variable
423 Invalid language
425 Invalid MAXVSTOR operand
426 Invalid RETRIEVE PFkey operand
427 Invalid TERMOUT operand
Example
’SET TERMOUT TERM TSQ1’
This example sets the processing option to send terminal line-mode output to temporary storage queue
TSQ1.
Notes
1. SET LANG only affects REXX syntax messages.
2. Multiple REXX/CICS users can be using different languages at the same time in the same region.
Commands
370 CICS TS for VSE/ESA: REXX Guide
SETSYS
Note: This is an authorized command.
 SETSYS
LANG ENG
CANFR
FRANC
GER
ESPAN
UCENG
HANZI
KANJI
1024
MAXVSTOR
kilobytes
RETRieve pfkeynn
ON
PSEUDO
OFF
AUTHClib lib.sublib
AUTHElib lib.sublib

SETSYS sets the REXX/CICS processing options for the system.
Operands
LANG
specifies that one of the following languages are available:
ENG
English
CANFR
Canadian French
FRANC
French
GER
German
ESPAN
Spanish
UCENG
Uppercase English
HANZI
Traditional Chinese
KANJi
Kanji
MAXVSTOR
is a keyword placing limits on virtual storage use.
kilobytes
specifies the number of kilobytes.
RETRieve
allows a PF key being set to retrieve the last line entered.
Commands
Chapter 25. REXX/CICS Commands 371
pfkeynn
specifies the PF key number.
PSEUDO
establishes the default region-wide REXX/CICS automatic pseudo-conversational setting. For more
information on the PSEUDO command, see section “PSEUDO” on page 362.
ON specifies that the automatic pseudo-conversational setting is on. This is the default.
OFF
specifies that the automatic pseudo-conversational setting is off.
AUTHCLIB
establishes the VSE Librarian sublibraries containing the REXX/CICS authorized commands.
lib.sublib
the name of the VSE Librarian sublibraries containing the REXX/CICS authorized commands.
AUTHELIB
establishes the VSE Librarian sublibraries containing the REXX/CICS authorized execs.
lib.sublib
the name of the VSE Librarian sublibraries containing the REXX/CICS authorized execs.
Return Codes
0Normal return
2721 Invalid SETSYS subcommand
2722 Error storing variable
2723 Invalid language
2725 Invalid MAXVSTOR operand
2726 Invalid RETRIEVE PFkey operand
2727 Invalid TERMOUT operand
2732 Invalid PSEUDO operand
2735 Invalid VSE Librarian sublibrary name
2739 VARGET for AUTHCLIB or AUTHELIB failed
2740 Too many sublibraries specified
Example
’SETSYS RETRIEVE 12’
This example set PF key 12 as the retrieve key.
Commands
372 CICS TS for VSE/ESA: REXX Guide
S2C
 S2C server_rexx_varname
client_rexx_varname

S2C copies a server REXX variable to a client REXX variable.
Operands
server_rexx_varname
is the name of the server REXX variable copying from.
client_rexx_varname
is the optional name of the client REXX variable copying into. If you do not specify, it defaults to the
same as the server_rexx_varname.
Return Codes
0Normal return
2840 No variable name specified
2841 Error retrieving variable
2842 Error storing variable
2848 No client available
Example
’S2C VARA VARB’
This example shows the contents of the server REXX variable VARA copying into the client REXX variable
VARB. The length of VARB is the same as the length of VARA.
Notes
1. The maximum length allowed of a varname, for this command, is 250 characters. If a longer name is
specified, only the first 250 characters are used.
2. The maximum length of a variable copied by S2C is 6000 bytes.
3. You can only use the S2C command from a server exec.
Commands
Chapter 25. REXX/CICS Commands 373
TERMID
 TERMID 
TERMID returns the four-character CICS terminal ID from the CICS field EIBTRMID in the variable
TERMID.
Return Codes
0Normal return
2921 Error in obtaining terminal ID
2928 Error setting TERMID value
Example
’TERMID’
This example places the CICS terminal ID from the CICS field EIBTRMID in the variable TERMID.
Commands
374 CICS TS for VSE/ESA: REXX Guide
WAITREAD
 WAITREAD 
WAITREAD performs full screen terminal input and places the results into the compound variable with:
WAITREAD.0
containing the number of elements returned.
WAITREAD.1
containing the AID description.
WAITREAD.2
containing the cursor position.
WAITREAD.3 through WAITREAD.n
remaining 3270 fields that have been modified.
Return Codes
0Normal return
3021 No terminal is attached
3099 Internal error
Example
’WAITREAD’
This example reads input from the terminal screen and places the results in the REXX compound variable
WAITREAD.1 through WAITREAD.n.
Note
A read modified is performed to the terminal and an array is returned with information from this read. The
format of these elements is: field_row field_column data
Commands
Chapter 25. REXX/CICS Commands 375
WAITREQ
 WAITREQ 
WAITREQ is used only in REXX servers causing the server to wait for a request. After a request is
received, it is placed into REXX variable REQUEST.
Return Codes
0Normal return
3121 WAITREQ not enabled
3122 Exec not a server
3123 Error saving request variable
3199 Internal error
Note: The return code reflected to the client program is the value of the REXX server variable at entry to
the WAITREQ command or at exit of the server exec.
Example
’WAITREQ’
This example causes the server exec to be suspended until another request for the server is encountered.
When the request is encountered the server exec is restored to its presuspended status with a new
request value.
Commands
376 CICS TS for VSE/ESA: REXX Guide
Part 3. Appendixes
© Copyright IBM Corp. 1992, 2010 377
378 CICS TS for VSE/ESA: REXX Guide
Appendix A. Error Numbers and Messages
External interfaces to the language processor can generate three of the error messages either before the
language processor gains control or after control has left the language processor. Therefore, SIGNAL ON
SYNTAX cannot trap these errors. The error numbers involved are: 3 and 5 (if the initial requirements for
storage could not be met) and 26 (if on exit the returned string could not be converted to form a valid
return code). Error 4 can be trapped only by SIGNAL ON HALT or CALL ON HALT. Five errors the
language processor detects cannot be trapped by SIGNAL ON SYNTAX unless the label SYNTAX appears
earlier in the program than the clause with the error. These errors include: 6, 12, 13, 22, and 30. The
following is a list of the error codes and their associated CICS messages:
Table 5. List of Error Codes and CICS Messages
Error code CICS message Error code CICS message
No number CICREX255T Error 26 CICREX466E
Error 3 CICREX451E Error 27 CICREX467E
Error 4 CICREX452E Error 28 CICREX486E
Error 5 CICREX450E Error 29 CICREX487E
Error 6 CICREX453E Error 30 CICREX468E
Error 7 CICREX454E Error 31 CICREX469E
Error 8 CICREX455E Error 32 CICREX492E
Error 9 CICREX456E Error 33 CICREX488E
Error 10 CICREX457E Error 34 CICREX470E
Error 11 CICREX458E Error 35 CICREX471E
Error 12 CICREX459E Error 36 CICREX472E
Error 13 CICREX460E Error 37 CICREX473E
Error 14 CICREX461E Error 38 CICREX489E
Error 15 CICREX462E Error 39 CICREX474E
Error 16 CICREX463E Error 40 CICREX475E
Error 17 CICREX465E Error 41 CICREX476E
Error 18 CICREX491E Error 42 CICREX477E
Error 19 CICREX482E Error 43 CICREX478E
Error 20 CICREX483E Error 44 CICREX479E
Error 21 CICREX464E Error 45 CICREX480E
Error 22 CICREX449E Error 46 CICREX218E
Error 23 CICREX1106E Error 47 CICREX219E
Error 24 CICREX484E Error 48 CICREX490E
Error 25 CICREX485E Error 49 CICREX481E
In these messages, the term “language processor” refers to the REXX/CICS interpreter.
In addition to the following error messages, the language processor issues this terminal (unrecoverable)
message:
CICREX255T Insufficient storage for Exec
interpreter
Explanation: There is insufficient storage for the
language processor to initialize itself.
© Copyright IBM Corp. 1992, 2010 379
System action: Execution is terminated at the point of
the error.
User response: Redefine storage and reissue the
command.
The following are the REXX error messages:
CICREX218E Error 46 Invalid variable reference
Explanation: Within an ARG, DROP, PARSE, PULL,
or PROCEDURE instruction, the syntax of a variable
reference (a variable whose value is to be used,
indicated by its name being enclosed in parentheses) is
incorrect. The right parenthesis that should immediately
follow the variable name may be missing.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX219E Error 47 Unexpected label
Explanation: A label, being used incorrectly, was
encountered in the expression being evaluated for an
INTERPRET instruction or in an expression entered
during interactive debug.
System action: Execution stops.
User response: Do not use a label in these
expressions.
CICREX449E Error 22 running fn ft, line nn: Invalid
character string
Explanation: A character string scanned with
OPTIONS ETMODE in effect contains one of the
following:
vUnmatched shift-out (SO) and shift-in (SI) control
characters
vAn odd number of bytes between the shift-out (SO)
and shift-in (SI) characters.
System action: Execution stops.
User response: Correct the incorrect character string
in the EXEC file.
CICREX450E Error 5 running fn ft, line nn: User
storage exhausted or request exceeds
limit
Explanation: While trying to process a program, the
language processor was unable to get the resources it
needed to continue. (For example, it could not get the
space needed for its work areas, variables, and so on.)
The program that called the language processor may
already have used up most of the available storage
itself. Or a request for storage may have been for more
than the implementation maximum.
System action: Execution stops.
User response: Run the exec or macro on its own, or
check a program issuing NUCXLOAD for a possible
loop that has not terminated properly. See your system
administrator for additional storage requirements.
CICREX451E Error 3 running fn ft: Program is
unreadable
Explanation: The REXX program could not be read.
This is probably due to bad data in the exec file or an
I/O error.
System action: Execution stops.
User response: Examine and correct the exec file.
Note: Sequence numbers are not allowed in columns
73 through 80 in a REXX exec.
CICREX452E Error 4 running fn ft, line nn: Program
interrupted
Explanation: The system interrupted execution of your
REXX program. Certain utility modules may force this
condition if they detect a disastrous error condition.
System action: Execution stops.
User response: Look for a problem with a utility
module called in your exec or macro.
CICREX453E Error 6 running fn ft, line nn:
Unmatched “/*” or quote
Explanation: A comment or literal string was started
but never finished. This could be because the language
processor detected:
vThe end of the file (or the end of data in an
INTERPRET statement) without finding the ending
“*/” for a comment or the ending quote for a literal
string
vThe end of the line for a literal string.
System action: Execution stops.
User response: Edit the exec and add the closing “*/”
or quote. You can also insert a TRACE SCAN statement
at the top of your program and rerun it. The resulting
output should show where the error exists.
CICREX454E Error 7 running fn ft, line nn: WHEN or
OTHERWISE expected
Explanation: The language processor expects a
series of WHENs and an OTHERWISE within a
SELECT statement. This message is issued when any
other instruction is found or if all WHEN expressions are
found to be false and an OTHERWISE is not present.
The error is often caused by forgetting the DO and END
instructions around the list of instructions following a
WHEN. For example:
WRONG RIGHT
Select Select
Error Numbers and Messages
380 CICS TS for VSE/ESA: REXX Guide
When a1=b1 then When a1=b1 then DO
Say ’A1 equals B1’ Say ’A1 equals B1’
exit exit
Otherwise nop end
end Otherwise nop
end
System action: Execution stops.
User response: Make the necessary corrections.
CICREX455E Error 8 running fn ft, line nn:
Unexpected THEN or ELSE
Explanation: The language processor has found a
THEN or an ELSE that does not match a corresponding
IF clause. This situation is often caused by using an
incorrect DO-END in the THEN part of a complex
IF-THEN-ELSE construction. For example,
WRONG RIGHT
If a1=b1 then do; If a1=b1 then do;
Say EQUALS Say EQUALS
exit exit
else end
Say NOT EQUALS else
Say NOT EQUALS
System action: Execution stops.
User response: Make the necessary corrections.
CICREX456E Error 9 running fn ft, line nn:
Unexpected WHEN or OTHERWISE
Explanation: The language processor has found a
WHEN or OTHERWISE instruction outside of a
SELECT construction. You may have accidentally
enclosed the instruction in a DO-END construction by
leaving off an END instruction, or you may have tried to
branch to it with a SIGNAL statement (which cannot
work because the SELECT is then terminated).
System action: Execution stops.
User response: Make the necessary correction.
CICREX457E Error 10 running fn ft, line nn:
Unexpected or unmatched END
Explanation: The language processor has found more
ENDs in your program than DOs or SELECTs, or the
ENDs were placed so that they did not match the DOs
or SELECTs. Putting the name of the control variable on
ENDs that close repetitive loops can help locate this
kind of error.
This message can be caused if you try to signal into the
middle of a loop. In this case, the END will be
unexpected because the previous DO will not have
been executed. Remember, also, that SIGNAL
terminates any current loops, so it cannot be used to
transfer control from one place inside a loop to another.
This message can also be caused if you place an END
immediately after a THEN or ELSE construction or if
you specified a name on the END keyword that does
not match the name following DO.
System action: Execution stops.
User response: Make the necessary corrections. It
may be helpful to use TRACE Scan to show the
structure of the program, making it easier to find your
error. Putting the name of the control variable on ENDs
that close repetitive loops can also help locate this kind
of error.
CICREX458E Error 11 running fn ft, line nn: Control
stack full
Explanation: This message is issued if you exceed
the limit of 250 levels of nesting of control structures
(DO-END, IF-THEN-ELSE, and so forth) or when user
storage limit is reached, whichever is less.
This message could be caused by a looping
INTERPRET instruction, such as:
line=’INTERPRET line’
INTERPRET line
These lines would loop until they exceeded the nesting
level limit and this message would be issued. Similarly,
a recursive subroutine that does not terminate correctly
could loop until it causes this message.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX459E Error 12 running fn ft, line nn: Clause
too long
Explanation: You have exceeded the limit for the
length of the internal representation of a clause. The
actual limit is the amount of storage that can be
obtained on a single request.
If the cause of this message is not obvious to you, it
may be due to a missing quote that has caused a
number of lines to be included in one long string. In this
case, the error probably occurred at the start of the data
included in the clause traceback (flagged by +++ on the
console).
The internal representation of a clause does not include
comments or multiple blanks that are outside of strings.
Note also that any symbol (name) or string gains two
characters in length in the internal representation.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX460E Error 13 running fn ft, line nn: Invalid
character in program
Explanation: The language processor found an
incorrect character outside of a literal (quoted) string.
Valid characters are:
Error Numbers and Messages
Appendix A. Error Numbers and Messages 381
(Alphamerics)
A-Z a-z 0-9
(Name Characters)
@#£$.?!_
(Special Characters)
&*()-+=\¬'";:<,>/|
If surrounded by X'0E' (shift-out) and X'0F' (shift-in), and
if ETMODE is on, the following are also valid
characters:
X'41' - X'FE' (DBCS Characters)
Some causes of this error are:
1. Using accented and other language-specific
characters in symbols.
2. Using DBCS characters without ETMODE in effect.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX461E Error 14 running fn ft, line nn:
Incomplete DO/SELECT/IF
Explanation: The language processor has reached
the end of the file (or end of data for an INTERPRET
instruction) and has found that there is a DO or
SELECT without a matching END, or an IF that is not
followed by a THEN clause.
System action: Execution stops.
User response: Make the necessary corrections. You
can use TRACE Scan to show the structure of the
program, making it easier to find where the missing
END or THEN should be. Putting the name of the
control variable on ENDs that close repetitive loops can
also help locate this kind of error.
CICREX462E Error 15 running fn ft, line nn: Invalid
hexadecimal or binary string
Explanation: Binary strings are new in REXX and the
language processor may now be considering the string
in your statement to be binary when that was not your
intention.
For the language processor, hexadecimal strings cannot
have leading or trailing blanks and can have imbedded
blanks only at byte boundaries. Only the digits 0–9and
the letters a–fand A–Fare allowed. Similarly, binary
strings can have blanks only at the boundaries of
groups of four binary digits, and only the digits 0and 1
are allowed.
The following are all valid hexadecimal or binary
constants:
’13’x ’0101 1100’b
’A3C2 1c34’x ’001100’B
’1de8’x "0 11110000"b
You may have mistyped one of the digits, for example,
typing a letter oinstead of 0. Or you may have put the
1-character symbol X,x,B,orb(the name of the
variable Xor B, respectively) after a literal string, when
the string is not intended as a hexadecimal or binary
specification. In this case, use the explicit concatenation
operator (||) to concatenate the string to the value of
the symbol.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX463E Error 16 running fn ft, line nn: Label
not found
Explanation: The language processor could not find
the label specified by a SIGNAL instruction or a label
matching an enabled condition when the corresponding
(trapped) event occurred. You may have mistyped the
label or forgotten to include it, or you may have typed it
in mixed case when it needs to be in uppercase.
System action: Execution stops. The name of the
missing label is included in the error traceback.
User response: Make the necessary corrections.
CICREX464E Error 21 running fn ft, line nn: Invalid
data on end of clause
Explanation: You have followed a clause, such as
SELECT or NOP, by some data other than a comment.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX465E Error 17 running fn ft, line nn:
Unexpected PROCEDURE
Explanation: The language processor encountered a
PROCEDURE instruction in an incorrect position. This
could occur because no internal routines are active,
because a PROCEDURE instruction has already been
encountered in the internal routine, or because the
PROCEDURE instruction was not the first instruction
executed after the CALL or function invocation. This
error can be caused by “dropping through” to an internal
routine, rather than invoking it with a CALL or a function
call.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX466E Error 26 running fn ft, line nn: Invalid
whole number
Explanation: The language processor found an
expression in the NUMERIC instruction, a parsing
positional pattern, or the right-hand term of the
exponentiation (**) operator that did not evaluate to a
Error Numbers and Messages
382 CICS TS for VSE/ESA: REXX Guide
whole number, or was greater than the limit, for these
uses, of 999999999.
This message can also be issued if the return code
passed back from an EXIT or RETURN instruction
(when a REXX program is called as a command) is not
a whole number or will not fit in a general register. This
error may be due to mistyping the name of a symbol so
that it is not the name of a variable in the expression on
any of these statements. This might be true, for
example, if you entered “EXIT CR” instead of “EXIT
RC”.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX467E Error 27 running fn ft, line nn: Invalid
DO syntax
Explanation: The language processor found a syntax
error in the DO instruction. You might have used BY,
TO, FOR, WHILE, OR UNTIL twice, or used a WHILE
and an UNTIL.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX468E Error 30 running fn ft, line nn: Name
or string > 250 characters
Explanation: The language processor found a variable
or a literal (quoted) string that is longer than the limit.
The limit for names is 250 characters, following any
substitutions. A possible cause of this error is the use of
a period (.) in a name, causing an unexpected
substitution.
The limit for a literal string is 250 characters. This error
can be caused by leaving off an ending quote (or
putting a single quote in a string) because several
clauses can be included in the string. For example, the
string ’don’t’ should be written as ’don’’t’ or "don’t".
System action: Execution stops.
User response: Make the necessary corrections.
CICREX469E Error 31 running fn ft, line nn: Name
starts with number or “.”
Explanation: The language processor found a symbol
whose name begins with a numeric digit or a period (.).
The REXX language rules do not allow you to assign a
value to a symbol whose name begins with a number or
a period because you could then redefine numeric
constants, and that would be catastrophic.
System action: Execution stops.
User response: Rename the variable correctly. It is
best to start a variable name with an alphabetic
character, but some other characters are allowed.
CICREX470E Error 34 running fn ft, line nn: Logical
value not 0 or 1
Explanation: The language processor found an
expression in an IF, WHEN, DO WHILE, or DO UNTIL
phrase that did not result ina0or1.Anyvalue
operated on by a logical operator (¬, \, |, &, or &&) must
result ina0or1.Forexample, the phrase “If result then
exit rc” will fail if result has a value other than 0 or 1.
Thus, the phrase would be better written as If
result¬=0 then exit rc.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX471E Error 35 running fn ft, line nn: Invalid
expression
Explanation: The language processor found a
grammatical error in an expression. This could be
because:
vYou ended an expression with an operator.
vYou specified, in an expression, two operators next to
one another with nothing in between them.
vYou did not specify an expression when one was
required.
vYou did not specify a right parenthesis when one was
required.
vYou used special characters (such as operators) in
an intended character expression without enclosing
them in quotation marks.
An example of the last case is that LISTFILE***
should be written as LISTFILE ’* * *’ (if LISTFILE is
not a variable) or even as ’LISTFILE***’.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX472E Error 36 running fn ft, line nn:
Unmatched “(” in expression
Explanation: The language processor found an
unmatched parenthesis within an expression. You will
get this message if you include a single parenthesis in a
command without enclosing it in quotation marks. For
example, COPY A B C A B D (REP should be written as
COPYABCABD’(’REP.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX473E Error 37 running fn ft, line nn:
Unexpected “,” or “)”
Explanation: The language processor found a comma
(,) outside a routine invocation or too many right
parentheses in an expression. You will get this message
if you include a comma in a character expression
without enclosing it in quotation marks. For example,
the instruction:
Error Numbers and Messages
Appendix A. Error Numbers and Messages 383
Say Enter A, B, or C
should be written as:
Say ’Enter A, B, or C’
System action: Execution stops.
User response: Make the necessary corrections.
CICREX474E Error 39 running fn ft, line nn:
Evaluation stack overflow
Explanation: The language processor was not able to
evaluate the expression because it is too complex
(many nested parentheses, functions, and so forth).
System action: Execution stops.
User response: Break up the expressions by
assigning subexpressions to temporary variables.
CICREX475E Error 40 running fn ft, line nn: Invalid
call to routine
Explanation: The language processor encountered an
incorrectly used call to a routine. Some possible causes
are:
vYou passed incorrect data (arguments) to the built-in
or external routine (this depends on the actual
routine).
vYou passed too many arguments to the built-in,
external, or internal routine.
vThe module invoked was not compatible with the
language processor.
If you were not trying to invoke a routine, you may have
a symbol or a string adjacent to a “(” when you meant it
to be separated by a space or an operator. This causes
it to be seen as a function call. For example, TIME(4+5)
should probably be written as TIME*(4+5).
System action: Execution stops.
User response: Make the necessary corrections.
CICREX476E Error 41 running fn ft, line nn: Bad
arithmetic conversion
Explanation: The language processor found a term in
an arithmetic expression that was not a valid number or
that had an exponent outside the allowed range of
-999999999 to +999999999.
You may have mistyped a variable name, or included an
arithmetic operator in a character expression without
putting it in quotation marks. For example, the
command MSG * Hi! should be written as ’MSG * Hi!’,
otherwise the language processor will try to multiply
“MSG” by “Hi!”.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX477E Error 42 running fn ft, line nn:
Arithmetic overflow/underflow
Explanation: The language processor encountered a
result of an arithmetic operation that required an
exponent greater than the limit of 9 digits (more than
999999999 or less than -999999999).
This error can occur during evaluation of an expression
(often as a result of trying to divide a number by 0), or
during the stepping of a DO loop control variable.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX478E Error 43 running fn ft, line nn: Routine
not found
Explanation: The language processor was unable to
find a routine called in your program. You invoked a
function within an expression, or in a subroutine invoked
by CALL, but the specified label is not in the program,
or is not the name of a built-in function, and
REXX/CICS is unable to locate it externally.
The simplest, and probably most common, cause of this
error is mistyping the name. Another possibility may be
that one of the standard function packages is not
available.
If you were not trying to invoke a routine, you may have
put a symbol or string adjacent to a “(” when you meant
it to be separated by a space or operator. The language
processor would see that as a function invocation. For
example, the string 3(4+5) should be written as 3*(4+5).
System action: Execution stops.
User response: Make the necessary corrections.
CICREX479E Error 44 running fn ft, line nn:
Function did not return data
Explanation: The language processor invoked an
external routine within an expression. The routine
seemed to end without error, but it did not return data
for use in the expression.
This may be due to specifying the name of a module
that is not intended for use as a REXX function. It
should be called as a command or subroutine.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX480E Error 45 running fn ft, line nn: No data
specified on function RETURN
Explanation: A REXX program has been called as a
function, but an attempt is being made to return (by a
RETURN; instruction) without passing back any data.
Similarly, an internal routine, called as a function, must
Error Numbers and Messages
384 CICS TS for VSE/ESA: REXX Guide
end with a RETURN statement specifying an
expression.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX481E Error 49 running fn ft, line nn:
Language processor failure
Explanation: The language processor carries out
numerous internal self-consistency checks. It issues this
message if it encounters a severe error.
System action: Execution stops.
User response: Report any occurrence of this
message to your IBM representative.
CICREX482E Error 19 running fn ft, line nn: String
or symbol expected
Explanation: The language processor expected a
symbol following the CALL or SIGNAL instructions, but
none was found. You may have omitted the string or
symbol, or you may have inserted a special character
(such as a parenthesis) in it.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX483E Error 20 running fn ft, line nn: Symbol
expected
Explanation: The language processor either expected
a symbol following the CALL ON, CALL OFF, END,
ITERATE, LEAVE, NUMERIC, PARSE, PROCEDURE,
SIGNAL ON, or SIGNAL OFF keywords or expected a
list of symbols or variable references following the
DROP, UPPER, or PROCEDURE (with EXPOSE option)
keywords. Either there was no symbol when one was
required or some other characters were found.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX484E Error 24 running fn ft, line nn: Invalid
TRACE request
Explanation: The language processor issues this
message when:
vThe action specified on a TRACE instruction, or the
argument to the TRACE built-in function, starts with a
letter that does not match one of the valid alphabetic
character options. The valid options are A, C, E, F, I,
L, N, O, R, or S.
vAn attempt is made to request TRACE Scan when
inside any control construction or while in interactive
debug
vIn interactive trace, you enter a number that is not a
whole number.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX485E Error 25 running fn ft, line nn: Invalid
sub-keyword found
Explanation: The language processor expected a
particular sub-keyword at this position in an instruction
and something else was found. For example, the
NUMERIC instruction must be followed by the
sub-keyword DIGITS, FUZZ, or FORM. If NUMERIC is
followed by anything else, this message is issued.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX486E Error 28 running fn ft, line nn: Invalid
LEAVE or ITERATE
Explanation: The language processor encountered an
incorrect LEAVE or ITERATE instruction. The instruction
was incorrect because of one of the following:
vNo loop is active.
vThe name specified on the instruction does not match
the control variable of any active loop.
Note that internal routine calls and the INTERPRET
instruction protect DO loops by making them inactive.
Therefore, for example, a LEAVE instruction in a
subroutine cannot affect a DO loop in the calling
routine.
You can cause this message to be issued if you use the
SIGNAL instruction to transfer control within or into a
loop. A SIGNAL instruction terminates all active loops,
and any ITERATE or LEAVE instruction issued then
would cause this message to be issued.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX487E Error 29 running fn ft, line nn:
Environment name too long
Explanation: The language processor encountered an
environment name specified on an ADDRESS
instruction that is longer than the limit of 8 characters.
System action: Execution stops.
User response: Specify the environment name
correctly.
CICREX488E Error 33 running fn ft, line nn: Invalid
expression result
Explanation: The language processor encountered an
expression result that is incorrect in its particular
context. The result may be incorrect in one of the
following:
vADDRESS VALUE expression
vNUMERIC DIGITS expression
vNUMERIC FORM VALUE expression
Error Numbers and Messages
Appendix A. Error Numbers and Messages 385
vNUMERIC FUZZ expression
vOPTIONS expression
vSIGNAL VALUE expression
vTRACE VALUE expression.
(FUZZ must be smaller than DIGITS.)
System action: Execution stops.
User response: Make the necessary corrections.
CICREX489E Error 38 running fn ft, line nn: Invalid
template or pattern
Explanation: The language processor found an
incorrect special character, for example %, within a
parsing template, or the syntax of a variable trigger was
incorrect (no symbol was found after a left parenthesis).
This message is also issued if the WITH sub-keyword is
omitted in a PARSE VALUE instruction.
System action: Execution stops.
User response: Make the necessary corrections.
CICREX490E Error 48 running fn ft, line nn: Failure
in system service
Explanation: The language processor halts execution
of the program because some system service, such as
user input or output or manipulation of the console
stack, has failed to work correctly.
System action: Execution stops.
User response: Ensure that your input is correct and
that your program is working correctly. If the problem
persists, notify your system support personnel.
CICREX491E Error 18 running fn ft, line nn: THEN
expected
Explanation: All REXX IF and WHEN clauses must be
followed by a THEN clause. Another clause was found
before a THEN statement was found.
System action: Execution stops.
User response: Insert a THEN clause between the IF
or WHEN clause and the following clause.
CICREX492E Error 32 running fn ft, line nn: Invalid
use of stem
Explanation: The REXX program attempted to change
the value of a symbol that is a stem. (A stem is that part
of a symbol up to the first period. You use a stem when
you want to affect all variables beginning with that
stem.) This may be in the UPPER instruction where the
action in this case is unknown, and therefore in error.
System action: Execution stops.
User response: Change the program so that it does
not attempt to change the value of a stem.
CICREX1106E Error 23 running fn ft, line nn: Invalid
SBCS/DBCS mixed string.
Explanation: A character string that has unmatched
SO-SI pairs (that is, an SO without an SI) or an odd
number of bytes between the SO-SI characters was
processed with OPTIONS EXMODE in effect.
System action: Execution stops.
User response: Correct the incorrect character string.
Error Numbers and Messages
386 CICS TS for VSE/ESA: REXX Guide
Appendix B. Return Codes
This appendix is a list of all the REXX/CICS return codes.
Panel Facility
4Warning. Panel facility continues processing
8Programmer error
10 Programmer error with state information
12 CICS command error
14 RFS errors; reason code contains the RFS return code
16 Internal system error
See Chapter 24, “REXX/CICS Panel Facility,” on page 295, for additional codes (for example: state and
reason codes).
SQL
nspecifies the SQLCODE if the SQL statement resulted in an error or warning
0The SQL statement was processed by the EXECSQL environment
30 There was not enough memory to build the SQLDSECT variable
31 There was not enough memory to build the SQL statement area
32 There was not enough memory to build the SQLDA variable
33 There was not enough memory to build the results area for the SELECT statement
RFS and FLST
0Normal return
101 Invalid command
102 Invalid operand
103 File not found
104 Not authorized
105 File already exists
107 Insufficient space in filepool
110 Request failed
111 Invalid file ID
113 Directory not found
115 Directory already exists
116 Directory not specified
121 File corrupted
122 Invalid or out of range stem.0
126 Path error
127 CICS I/O error
128 Command not valid from this location
130 Directory not empty
131 Missing operand
132 Missing file pool data record. File pool is probably not formatted.
199 Internal error
EDITOR and EDIT
0Normal return
201 Invalid command
202 Invalid operand
203 File not found
204 Not authorized
© Copyright IBM Corp. 1992, 2010 387
207 Insufficient space in filepool
210 Request failed
211 Invalid file ID
223 Search argument not found
226 File is currently being edited
229 Number out of range
230 Cursor is not in file area
231 Out of virtual storage
232 Prefix command conflict
236 Not defined
237 CICSEXC1 link error
238 CICSEXC1 return code was invalid
299 Internal error
DIR
0Normal return
321 Cannot access current RFS directory information
322 Invalid stem name
325 Error retrieving RFS directory
SET
0Normal return
421 Invalid SET subcommand
422 Error storing variable
423 Invalid language
425 Invalid MAXVSTOR operand
426 Invalid RETRIEVE PFkey operand
427 Invalid TERMOUT operand
CD
0Normal return
521 Error in retrieving filepool definition
522 Error in creating default RFS directory
523 Error in storing current RFS directory information
524 RFS directory does not exist or access not authorized
525 Error in retrieving directory information
526 Invalid filepool/directory
527 Cannot go back past root directory
528 Error setting result value
PATH
0Normal return
625 Error retrieving path information
626 Invalid RFS directory name
628 Error setting RESULT value
629 Invalid VSE Librarian sublibrary
630 Error storing path information
631 No path currently defined
632 Resulting PATH contains no RFS directories or library names
RLS
0Normal return
701 Invalid command
Return Codes
388 CICS TS for VSE/ESA: REXX Guide
702 Invalid operand
713 Directory not found
715 Directory already exists
716 Directory not specified
723 List not found
726 List not specified
728 List is in update mode
729 List is not in update mode
730 User is not signed on
732 Queue empty
733 Named queue not found
736 Stem or variable not specified
737 Stem or variable name too long
738 Stem or variable count invalid
743 Block not found
746 CICGETV error
747 GETMAIN error
748 FREEMAIN error
749 ENQ error
750 DEQ error
751 Dynamic area GETMAIN error
752 Error in saved variable data
753 Saved variable not found
754 User not owner of list
LISTCMD
0Normal return
821 Invalid environment name
822 Invalid command name
CLD
0Normal return
923 Error in storing current RLS directory information
924 RLS directory does not exist or access not authorized
925 Error in retrieving directory information
926 Invalid directory
927 Cannot go back past root directory
928 Error setting result value
DEFCMD
0Normal return
1001 Invalid command
1021 Cannot load program
1023 Entry not found
1048 No client available
1099 Internal error
DEFSCMD
0Normal return
1101 Invalid command
1121 Cannot load program
1123 Entry not found
1148 No client available
Return Codes
Appendix B. Return Codes 389
1199 Internal error
DEFTRNID
0Normal return
1202 Invalid operand
1222 Invalid option
1223 Error storing trantable information
1225 Error retrieving trantable information
1226 Exec name length error
1228 Error setting trantable value
1233 Transaction not found in table
EXECDROP
0Normal return
1401 Invalid command
1402 Invalid operand
1423 Error storing EXECLOAD information
1425 Error retrieving EXECLOAD information
1448 No client available
EXECLOAD
0Normal return
1501 Invalid command
1502 Invalid operand
1523 Error storing EXECLOAD information
1525 Error retrieving EXECLOAD information
1530 Unable to link to CICLIBR routine
1531 Error returned from CICLIBR routine
1532 Error returned from RFS READ
1547 GETMAIN error
1548 No client available
1599 Internal error
EXECMAP
0Normal return
1623 EXECLOAD directory not found
EXPORT and IMPORT
0Normal return
1701 Invalid command
1702 Invalid operand
1723 RFS write error
1724 RFS read error
1733 Input for export not found
1736 Unexpected CICS error
1738 Invalid VSE Librarian member name
1741 Unsupported record format
1744 Not authorized
1747 CICSEXC1 return code was invalid
1799 Internal error
Return Codes
390 CICS TS for VSE/ESA: REXX Guide
FILEPOOL
0Normal return
1802 Invalid operand
1821 Invalid file pool subcommand
1822 Filepool subcommand not specified
1823 Error storing file pool information
1824 File pool ID not specified
1825 Error retrieving file pool information
1826 Invalid file pool ID
1827 Invalid file pool data retrieved
1828 File pool not defined
1829 RFS could not add library to file pool
1830 RFS could not create users directory
1831 CICS file indentifier for the file pool must be specified
1832 Invalid CICS file indentifier
1833 File pool variable corrupted
1834 Pool ID already exists
1835 CICS file indentifier already used
1836 Could not format file pool
1837 File pool needs to be formatted first
1838 File pool ADD record is full
1839 File ID is not found
LISTCLIB and LISTELIB
2226 Invalid stem variable name
2245 Error retrieving authorized library information
GETVERS
0Normal return
1910 Request failed
COPYR2S
0Normal return
2002 Invalid operand
2021 Invalid structure definition
2022 Invalid variable structure definition
2023 Field name not found
2025 Failure processing GETVAR request
2026 Invalid numeric input
2027 RFS read error
2028 Invalid offset
2029 Invalid length value
COPYS2R
0Normal return
2102 Invalid operand
2121 Invalid structure definition
2122 Invalid variable structure definition
2123 Field name not found
2125 Failure processing GETVAR request
2126 Invalid numeric input
2127 RFS read error
2128 Invalid offset
Return Codes
Appendix B. Return Codes 391
2129 Invalid length value
LISTPOOL
0Normal return
2225 Error retrieving filepool information
2226 Invalid stem variable name
LISTTRNID
0Normal return
2325 Error retrieving trantable information
C2S
0Normal return
2440 No variable name specified
2441 Error retrieving variable
2442 Error storing variable
2448 No client available
PSEUDO
0Normal return
2502 Invalid operand
2521 Operand not specified
AUTHUSER
0Normal return
2602 Invalid operand or operand missing
2621 Specified user ID invalid length
2642 Error storing user ID
SETSYS
0Normal return
2721 Invalid SETSYS subcommand
2722 Error storing variable
2723 Invalid language
2725 Invalid MAXVSTOR operand
2726 Invalid RETRIEVE PFkey operand
2727 Invalid TERMOUT operand
2732 Invalid PSEUDO operand
2735 Invalid VSE Librarian sublibrary name
2739 VARGET for AUTHCLIB or AUTHELIB failed
2740 Too many sublibraries specified
S2C
0Normal return
2840 No variable name specified
2841 Error retrieving variable
2842 Error storing variable
2848 No client available
TERMID
0Normal return
Return Codes
392 CICS TS for VSE/ESA: REXX Guide
2921 Error in obtaining terminal ID
2928 Error setting TERMID value
WAITREAD
0Normal return
3021 No terminal is attached
3099 Internal error
WAITREQ
0Normal return
3121 WAITREQ not enabled
3122 Exec not a server
3123 Error saving request variable
3199 Internal error
EXEC
nspecifies the return code set by the exit of the called exec
0Normal return
-3 Exec not found
-10 Exec name not specified
-11 Invalid exec name
-12 GETMAIN error
-99 Internal error
CEDA and CEMT
nspecifies the return code passed back by CICS if an error is detected
0Normal return
-101 Invalid command
EXECIO
nspecifies the return code passed back by CICS if an error is detected
0Normal return
-202 Invalid operand
-221 Too many operands specified
-222 Recno operand out of range
-224 Lines operand invalid
CONVTMAP
nspecifies the return code from the attempt to process the VSE Librarian sublibrary member
0Normal return
-302 Invalid operand
-321 Invalid input record
-322 RFS error writing output file
1736 CICSEXC1 link error
1744 Not authorized
SCRNINFO
nspecifies the return code passed back by CICS if an error is detected
0Normal return
-499 Internal error
Return Codes
Appendix B. Return Codes 393
CICS
-521 Command not supported
-522 Invalid command or keyword
-523 Option must be specified
-524 Unsupported option specified
-525 Conflicting options specified
-526 Implied option not specified
-527 Redundant specification for option
-528 Value for option not specified
-529 Value specified for option which should not have a value
-530 Value specified for option is not numeric
-531 Invalid value
-532 Value specified is too long
-533 Value specified is too short
-534 Value not specified
-535 Variable table overflow
-536 Number of variables exceeds variable table limit
-537 Argument must be a variable
-538 Variable does not exist
-539 Invalid variable name
-540 Master system trace flag must be on for tracing
-541 Parsing error
-542 Generic name is invalid
-543 Missing right parenthesis
-544 Ambiguous value/keyword
-545 RIDFLD must be fullword variable
-546 RIDFLd must be variable
-547 Invalid GETVAR return code
-548 Internal GETVAR error
-549 Bad PUTVAR return code
-550 PUTVAR failed
-551 Unable to obtain storage
-552 Exec CICS command table not found
Return Codes
394 CICS TS for VSE/ESA: REXX Guide
Appendix C. Double-Byte Character Set (DBCS) Support
A Double-Byte Character Set supports languages that have more characters than can be represented by 8
bits (such as Korean Hangeul and Japanese kanji). REXX has a full range of DBCS functions and
handling techniques.
These include:
vSymbol and string handling capabilities with DBCS characters
vAn option that allows DBCS characters in symbols, comments, and literal strings.
vAn option that allows data strings to contain DBCS characters.
vA number of functions that specifically support the processing of DBCS character strings
vDefined DBCS enhancements to current instructions and functions.
Note: The use of DBCS does not affect the meaning of the built-in functions as described in Chapter 14,
“Functions,” on page 171. This explains how the characters in a result are obtained from the
characters of the arguments by such actions as selecting, concatenating, and padding. The
appendix describes how the resulting characters are represented as bytes. This internal
representation is not usually seen if the results are printed. It may be seen if the results are
displayed on certain terminals.
General Description
The following characteristics help define the rules used by DBCS to represent extended characters:
vEach DBCS character consists of 2 bytes.
vThere are no DBCS control characters.
vThe codes are within the ranges defined in the table, which shows the valid DBCS code for the DBCS
blank. You cannot have a DBCS blank in a simple symbol, in the stem of a compound variable, or in a
label.
Table 6. DBCS Ranges
Byte EBCDIC
1st X'41' to X'FE'
2nd X'41' to X'FE'
DBCS blank X'4040'
vDBCS alphanumeric and special symbols
A DBCS contains double-byte representation of alphanumeric and special symbols corresponding to
those of the Single-Byte Character Set (SBCS). In EBCDIC, the first byte of a double-byte alphanumeric
or special symbol is X'42' and the second is the same hex code as the corresponding EBCDIC code.
Here are some examples:
X’42C1’ is an EBCDIC double-byte A
X’4281’ is an EBCDIC double-byte a
X’427D’ is an EBCDIC double-byte quote
vNo case translation
In general, there is no concept of lowercase and uppercase in DBCS.
vNotational conventions
This appendix uses the following notational conventions:
© Copyright IBM Corp. 1992, 2010 395
DBCS character -> .A .B .C .D
SBCS character -> abcde
DBCS blank -> ’. ’
EBCDIC shift-out (X’0E’) -> <
EBCDIC shift-in (X’0F’) -> >
Note: In EBCDIC, the shift-out (SO) and shift-in (SI) characters distinguish DBCS characters from SBCS
characters.
Enabling DBCS Data Operations and Symbol Use
The OPTIONS instruction controls how REXX regards DBCS data. To enable DBCS operations, use the
EXMODE option. To enable DBCS symbols, use the ETMODE option on the OPTIONS instruction; this
must be the first instruction in the program. (See page 151 for more information.)
If OPTIONS ETMODE is in effect, the language processor does validation to ensure that SO and SI are
paired in comments. Otherwise, the contents of the comment are not checked. The comment delimiters (/*
and */) must be SBCS characters.
Symbols and Strings
In DBCS, there are DBCS-only symbols and strings and mixed symbols and strings.
DBCS-Only Symbols and Mixed SBCS/DBCS Symbols
A DBCS-only symbol consists of only non-blank DBCS codes as indicated in Table 6 on page 395.
A mixed DBCS symbol is formed by a concatenation of SBCS symbols, DBCS-only symbols, and other
mixed DBCS symbols. In EBCDIC, the SO and SI bracket the DBCS symbols and distinguish them from
the SBCS symbols.
The default value of a DBCS symbol is the symbol itself, with SBCS characters translated to uppercase.
Aconstant symbol must begin with an SBCS digit (0–9) or an SBCS period. The delimiter (period) in a
compound symbol must be an SBCS character.
DBCS-Only Strings and Mixed SBCS/DBCS Strings
A DBCS-only string consists of only DBCS characters. A mixed SBCS/DBCS string is formed by a
combination of SBCS and DBCS characters. In EBCDIC, the SO and SI bracket the DBCS data and
distinguish it from the SBCS data. Because the SO and SI are needed only in the mixed strings, they are
not associated with the DBCS-only strings.
In EBCDIC:
DBCS-only string -> .A.B.C
Mixed string -> ab<.A.B>
Mixed string -> <.A.B>
Mixed string -> ab<.C.D>ef
396 CICS TS for VSE/ESA: REXX Guide
Validation
The user must follow certain rules and conditions when using DBCS.
DBCS Symbol Validation
DBCS symbols are valid only if you comply with the following rules:
vThe DBCS portion of the symbol must be an even number of bytes in length
vDBCS alphanumeric and special symbols are regarded as different to their corresponding SBCS
characters. Only the SBCS characters are recognized by REXX in numbers, instruction keywords, or
operators
vDBCS characters cannot be used as special characters in REXX
vSO and SI cannot be contiguous
vNesting of SO or SI is not permitted
vSO and SI must be paired
vNo part of a symbol consisting of DBCS characters may contain a DBCS blank.
vEach part of a symbol consisting of DBCS characters must be bracketed with SO and SI.
These examples show some possible misuses:
<.A.BC> -> Incorrect because of odd byte length
<.A.B><.C> -> Incorrect contiguous SO/SI
<> -> Incorrect contiguous SO/SI (null DBCS symbol)
<.A<.B>.C> -> Incorrectly nested SO/SI
<.A.B.C -> Incorrect because SO/SI not paired
<.A. .B> -> Incorrect because contains blank
’. A<.B><.C> -> Incorrect symbol
Mixed String Validation
The validation of mixed strings depends on the instruction, operator, or function. If you use a mixed string
with an instruction, operator, or function that does not allow mixed strings, this causes a syntax error.
The following rules must be followed for mixed string validation:
vDBCS strings must be an even number of bytes in length, unless you have SO and SI.
EBCDIC only:
vSO and SI must be paired in a string.
vNesting of SO or SI is not permitted.
These examples show some possible misuses:
’ab<cd’ -> INCORRECT - not paired
’<.A<.B>.C> -> INCORRECT - nested
’<.A.BC>’ -> INCORRECT - odd byte length
The end of a comment delimiter is not found within DBCS character sequences. For example, when the
program contains /*<*/, then the */ is not recognized as ending the comment because the scanning is
looking for the >(SI) to go with the <(SO) and not looking for */.
When a variable is created, modified, or referred to in a REXX program under OPTIONS EXMODE, it is
validated whether it contains a correct mixed string or not. When a referred variable contains a mixed
string that is not valid, it depends on the instruction, function, or operator whether it causes a syntax error.
The ARG, PARSE, PULL, PUSH, QUEUE, SAY, TRACE, and UPPER instructions all require valid mixed
strings with OPTIONS EXMODE in effect.
Instruction Examples
Here are some examples that illustrate how instructions work with DBCS.
Appendix C. Double-Byte Character Set (DBCS) Support 397
PARSE
In EBCDIC:
x1 = ’<><.A.B><. . ><.E><.F><>’
PARSE VAR x1 w1
w1 -> ’<><.A.B><. . ><.E><.F><>’
PARSE VAR x1 1 w1
w1 -> ’<><.A.B><. . ><.E><.F><>’
PARSE VAR x1 w1 .
w1 -> ’<.A.B>’
The leading and trailing SO and SI are unnecessary for word parsing and, thus, they are stripped off.
However, one pair is still needed for a valid mixed DBCS string to be returned.
PARSE VAR x1 . w2
w2 -> ’<. ><.E><.F><>’
Here the first blank delimited the word and the SO is added to the string to ensure the DBCS blank and
the valid mixed string.
PARSE VAR x1 w1 w2
w1 -> ’<.A.B>’
w2 -> ’<. ><.E><.F><>’
PARSE VAR x1 w1 w2 .
w1 -> ’<.A.B>’
w2 -> ’<.E><.F>’
The word delimiting allows for unnecessary SO and SI to be dropped.
x2 = ’abc<>def <.A.B><><.C.D>’
PARSE VAR x2 w1 ’’ w2
w1 -> ’abc<>def <.A.B><><.C.D>’
w2 -> ’’
PARSE VAR x2 w1 ’<>’ w2
w1 -> ’abc<>def <.A.B><><.C.D>’
w2 -> ’’
PARSE VAR x2 w1 ’<><>’ w2
w1 -> ’abc<>def <.A.B><><.C.D>’
w2 -> ’’
Note that for the last three examples '', <>, and <><> are each a null string (a string of length 0). When
parsing, the null string matches the end of string. For this reason, w1 is assigned the value of the entire
string and w2 is assigned the null string.
PUSH and QUEUE
The PUSH and QUEUE instructions add entries to the program stack. Since a stack entry is limited to 255
bytes, the expression must be truncated less than 256 bytes. If the truncation splits a DBCS string, REXX
will insure that the integrity of the SO-SI pairing will be kept under OPTIONS EXMODE.
SAY and TRACE
The SAY and TRACE instructions write data to the output stream. As was true for the PUSH and QUEUE
instructions, REXX will guarantee the SO-SI pairs are kept for any data that is separated to meet the
requirements of the output stream. The SAY and TRACE instructions display data on the user's terminal.
As was true for the PUSH and QUEUE instructions, REXX will guarantee the SO-SI pairs are kept for any
data that is separated to meet the requirements of the terminal line size. This is generally 130 bytes or
fewer if the DIAG-24 value returns a smaller value.
398 CICS TS for VSE/ESA: REXX Guide
When the data is split up in shorter lengths, again the DBCS data integrity is kept under OPTIONS
EXMODE. In EBCDIC, if the terminal line size is less than 4, the string is treated as SBCS data, because
4 is the minimum for mixed string data.
UPPER
Under OPTIONS EXMODE, the UPPER instruction translates only SBCS characters in contents of one or
more variables to uppercase, but it never translates DBCS characters. If the content of a variable is not
valid mixed string data, no uppercasing occurs.
DBCS Function Handling
Some built-in functions can handle DBCS. The functions that deal with word delimiting and length
determining conform with the following rules under OPTIONS EXMODE:
1. Counting characters—Logical character lengths are used when counting the length of a string (that
is, 1 byte for one SBCS logical character, 2 bytes for one DBCS logical character). In EBCDIC, SO
and SI are considered to be transparent, and are not counted, for every string operation.
2. Character extraction from a string—Characters are extracted from a string on a logical character
basis. In EBCDIC, leading SO and trailing SI are not considered as part of one DBCS character. For
instance, .A and .B are extracted from <.A.B>, and SO and SI are added to each DBCS character
when they are finally preserved as completed DBCS characters. When multiple characters are
consecutively extracted from a string, SO and SI that are between characters are also extracted. For
example, .A><.B is extracted from <.A><.B>, and when the string is finally used as a completed string,
the SO prefixes it and the SI suffixes it to give <.A><.B>.
Here are some EBCDIC examples:
S1 = ’abc<>def’
SUBSTR(S1,3,1) -> ’c’
SUBSTR(S1,4,1) -> ’d’
SUBSTR(S1,3,2) -> ’c<>d’
S2 = ’<><.A.B><>’
SUBSTR(S2,1,1) -> ’<.A>’
SUBSTR(S2,2,1) -> ’<.B>’
SUBSTR(S2,1,2) -> ’<.A.B>’
SUBSTR(S2,1,3,’x’) -> ’<.A.B><>x’
S3 = ’abc<><.A.B>’
SUBSTR(S3,3,1) -> ’c’
SUBSTR(S3,4,1) -> ’<.A>’
SUBSTR(S3,3,2) -> ’c<><.A>’
DELSTR(S3,3,1) -> ’ab<><.A.B>’
DELSTR(S3,4,1) -> ’abc<><.B>’
DELSTR(S3,3,2) -> ’ab<.B>’
3. Character concatenation—String concatenation can only be done with valid mixed strings. In
EBCDIC, adjacent SI and SO (or SO and SI) that are a result of string concatenation are removed.
Even during implicit concatenation as in the DELSTR function, unnecessary SO and SI are removed.
4. Character comparison—Valid mixed strings are used when comparing strings on a character basis. A
DBCS character is always considered greater than an SBCS one if they are compared. In all but the
strict comparisons, SBCS blanks, DBCS blanks, and leading and trailing contiguous SO and SI (or SI
and SO) in EBCDIC are removed. SBCS blanks may be added if the lengths are not identical.
In EBCDIC, contiguous SO and SI (or SI and SO) between nonblank characters are also removed for
comparison.
Note: The strict comparison operators do not cause syntax errors even if you specify mixed strings
that are not valid.
Appendix C. Double-Byte Character Set (DBCS) Support 399
In EBCDIC:
’<.A>’ = ’<.A. >’ -> 1 /* true */
’<><><.A>’ = ’<.A><><>’ -> 1 /* true */
’<> <.A>’ = ’<.A>’ -> 1 /* true */
’<.A><><.B>’ = ’<.A.B>’ -> 1 /* true */
’abc’ < ’ab<. >’ -> 0 /* false */
5. Word extraction from a string—“Word” means that characters in a string are delimited by an SBCS
or a DBCS blank.
In EBCDIC, leading and trailing contiguous SO and SI (or SI and SO) are also removed when words
are separated in a string, but contiguous SO and SI (or SI and SO) in a word are not removed or
separated for word operations. Leading and trailing contiguous SO and SI (or SI and SO) of a word
are not removed if they are among words that are extracted at the same time.
In EBCDIC:
W1 = ’<><. .A. . .B><.C. .D><>’
SUBWORD(W1,1,1) -> ’<.A>’
SUBWORD(W1,1,2) -> ’<.A. . .B><.C>’
SUBWORD(W1,3,1) -> ’<.D>’
SUBWORD(W1,3) -> ’<.D>’
W2 = ’<.A. .B><.C><> <.D>’
SUBWORD(W2,2,1) -> ’<.B><.C>’
SUBWORD(W2,2,2) -> ’<.B><.C><> <.D>’
Built-in Function Examples
Examples for built-in functions, those that support DBCS and follow the rules defined, are given in this
section. For full function descriptions and the syntax diagrams, refer to Chapter 14, “Functions,” on page
171.
ABBREV
In EBCDIC:
ABBREV(’<.A.B.C>’,’<.A.B>’) -> 1
ABBREV(’<.A.B.C>’,’<.A.C>’) -> 0
ABBREV(’<.A><.B.C>’,’<.A.B>’) -> 1
ABBREV(’aa<>bbccdd’,’aabbcc’) -> 1
Applying the character comparison and character extraction from a string rules.
COMPARE
In EBCDIC:
COMPARE(’<.A.B.C>’,’<.A.B><.C>’) -> 0
COMPARE(’<.A.B.C>’,’<.A.B.D>’) -> 3
COMPARE(’ab<>cde’,’abcdx’) -> 5
COMPARE(’<.A><>’,’<.A>’,’<. >’) -> 0
Applying the character concatenation for padding, character extraction from a string, and character
comparison rules.
COPIES
In EBCDIC:
COPIES(’<.A.B>’,2) -> ’<.A.B.A.B>’
COPIES(’<.A><.B>’,2) -> ’<.A><.B.A><.B>’
COPIES(’<.A.B><>’,2) -> ’<.A.B><.A.B><>’
Applying the character concatenation rule.
400 CICS TS for VSE/ESA: REXX Guide
DATATYPE
DATATYPE(’<.A.B>’) -> ’CHAR’
DATATYPE(’<.A.B>’,’D’) -> 1
DATATYPE(’<.A.B>’,’C’) -> 1
DATATYPE(’a<.A.B>b’,’D’) -> 0
DATATYPE(’a<.A.B>b’,’C’) -> 1
DATATYPE(’abcde’,’C’) -> 0
DATATYPE(’<.A.B’,’C’) -> 0
DATATYPE(’<.A.B>’,’S’) -> 1 /* if ETMODE is on */
Note: If string is not a valid mixed string and Cor Dis specified as type,0is returned.
FIND
FIND(’<.A. .B.C> abc’,’<.B.C> abc’) -> 2
FIND(’<.A. .B><.C> abc’,’<.B.C> abc’) -> 2
FIND(’<.A. . .B> abc’,’<.A> <.B>’) -> 1
Applying the word extraction from a string and character comparison rules.
INDEX, POS, and LASTPOS
INDEX(’<.A><.B><><.C.D.E>’,’<.D.E>’) -> 4
POS(’<.A>’,’<.A><.B><><.A.D.E>’) -> 1
LASTPOS(’<.A>’,’<.A><.B><><.A.D.E>’) -> 3
Applying the character extraction from a string and character comparison rules.
INSERT and OVERLAY
In EBCDIC:
INSERT(’a’,’b<><.A.B>’,1) -> ’ba<><.A.B>’
INSERT(’<.A.B>’,’<.C.D><>’,2) -> ’<.C.D.A.B><>’
INSERT(’<.A.B>’,’<.C.D><><.E>’,2) -> ’<.C.D.A.B><><.E>’
INSERT(’<.A.B>’,’<.C.D><>’,3,,’<.E>’) -> ’<.C.D><.E.A.B>’
OVERLAY(’<.A.B>’,’<.C.D><>’,2) -> ’<.C.A.B>’
OVERLAY(’<.A.B>’,’<.C.D><><.E>’,2) -> ’<.C.A.B>’
OVERLAY(’<.A.B>’,’<.C.D><><.E>’,3) -> ’<.C.D><><.A.B>’
OVERLAY(’<.A.B>’,’<.C.D><>’,4,,’<.E>’) -> ’<.C.D><.E.A.B>’
OVERLAY(’<.A>’,’<.C.D><.E>’,2) -> ’<.C.A><.E>’
Applying the character extraction from a string and character comparison rules.
JUSTIFY
JUSTIFY(’<><. .A. . .B><.C. .D>’,10,’p’)
-> ’<.A>ppp<.B><.C>ppp<.D>’
JUSTIFY(’<><. .A. . .B><.C. .D>’,11,’p’)
-> ’<.A>pppp<.B><.C>ppp<.D>’
JUSTIFY(’<><. .A. . .B><.C. .D>’,10,’<.P>’)
-> ’<.A.P.P.P.B><.C.P.P.P.D>’
JUSTIFY(’<><.X. .A. . .B><.C. .D>’,11,’<.P>’)
-> ’<.X.P.P.A.P.P.B><.C.P.P.D>’
Applying the character concatenation for padding and character extraction from a string rules.
LEFT, RIGHT, and CENTER
In EBCDIC:
LEFT(’<.A.B.C.D.E>’,4) -> ’<.A.B.C.D>’
LEFT(’a<>’,2) -> ’a<> ’
LEFT(’<.A>’,2,’*’) -> ’<.A>*’
RIGHT(’<.A.B.C.D.E>’,4) -> ’<.B.C.D.E>’
Appendix C. Double-Byte Character Set (DBCS) Support 401
RIGHT(’a<>’,2) -> ’a’
CENTER(’<.A.B>’,10,’<.E>’) -> ’<.E.E.E.E.A.B.E.E.E.E>’
CENTER(’<.A.B>’,11,’<.E>’) -> ’<.E.E.E.E.A.B.E.E.E.E.E>’
CENTER(’<.A.B>’,10,’e’) -> ’eeee<.A.B>eeee’
Applying the character concatenation for padding and character extraction from a string rules.
LENGTH
In EBCDIC:
LENGTH(’<.A.B><.C.D><>’) -> 4
Applying the counting characters rule.
REVERSE
In EBCDIC:
REVERSE(’<.A.B><.C.D><>’) -> ’<><.D.C><.B.A>’
Applying the character extraction from a string and character concatenation rules.
SPACE
In EBCDIC:
SPACE(’a<.A.B. .C.D>’,1) -> ’a<.A.B> <.C.D>’
SPACE(’a<.A><><. .C.D>’,1,’x’) -> ’a<.A>x<.C.D>’
SPACE(’a<.A><. .C.D>’,1,’<.E>’) -> ’a<.A.E.C.D>’
Applying the word extraction from a string and character concatenation rules.
STRIP
In EBCDIC:
STRIP(’<><.A><.B><.A><>’,,’<.A>’) -> ’<.B>’
Applying the character extraction from a string and character concatenation rules.
SUBSTR and DELSTR
In EBCDIC:
SUBSTR(’<><.A><><.B><.C.D>’,1,2) -> ’<.A><><.B>’
DELSTR(’<><.A><><.B><.C.D>’,1,2) -> ’<><.C.D>’
SUBSTR(’<.A><><.B><.C.D>’,2,2) -> ’<.B><.C>’
DELSTR(’<.A><><.B><.C.D>’,2,2) -> ’<.A><><.D>’
SUBSTR(’<.A.B><>’,1,2) -> ’<.A.B>’
SUBSTR(’<.A.B><>’,1) -> ’<.A.B><>’
Applying the character extraction from a string and character concatenation rules.
SUBWORD and DELWORD
In EBCDIC:
SUBWORD(’<><. .A. . .B><.C. .D>’,1,2) -> ’<.A. . .B><.C>’
DELWORD(’<><. .A. . .B><.C. .D>’,1,2) -> ’<><. .D>’
SUBWORD(’<><.A. . .B><.C. .D>’,1,2) -> ’<.A. . .B><.C>’
DELWORD(’<><.A. . .B><.C. .D>’,1,2) -> ’<><.D>’
SUBWORD(’<.A. .B><.C><> <.D>’,1,2) -> ’<.A. .B><.C>’
DELWORD(’<.A. .B><.C><> <.D>’,1,2) -> ’<.D>’
Applying the word extraction from a string and character concatenation rules.
SYMBOL
In EBCDIC:
402 CICS TS for VSE/ESA: REXX Guide
Drop A.3 ; <.A.B>=3 /* if ETMODE is on */
SYMBOL(’<.A.B>’) -> ’VAR’
SYMBOL(<.A.B>) -> ’LIT’ /* has tested "3" */
SYMBOL(’a.<.A.B>’) -> ’LIT’ /* has tested A.3 */
TRANSLATE
In EBCDIC:
TRANSLATE(’abcd’,’<.A.B.C>’,’abc’) -> ’<.A.B.C>d’
TRANSLATE(’abcd’,’<><.A.B.C>’,’abc’) -> ’<.A.B.C>d’
TRANSLATE(’abcd’,’<><.A.B.C>’,’ab<>c’) -> ’<.A.B.C>d’
TRANSLATE(’a<>bcd’,’<><.A.B.C>’,’ab<>c’) -> ’<.A.B.C>d’
TRANSLATE(’a<>xcd’,’<><.A.B.C>’,’ab<>c’) -> ’<.A>x<.C>d’
Applying the character extraction from a string, character comparison, and character concatenation rules.
VALUE
In EBCDIC:
Drop A3 ; <.A.B>=3 ; fred=’<.A.B>’
VALUE(’fred’) -> ’<.A.B>’ /* looks up FRED */
VALUE(fred) -> ’3’ /* looks up <.A.B> */
VALUE(’a’<.A.B>) -> ’A3’ /* if ETMODE is on */
VERIFY
In EBCDIC:
VERIFY(’<><><.A.B><><.X>’,’<.B.A.C.D.E>’) -> 3
Applying the character extraction from a string and character comparison rules.
WORD, WORDINDEX, and WORDLENGTH
In EBCDIC:
W = ’<><. .A. . .B><.C. .D>’
WORD(W,1) -> ’<.A>’
WORDINDEX(W,1) -> 2
WORDLENGTH(W,1) -> 1
Y = ’<><.A. . .B><.C. .D>’
WORD(Y,1) -> ’<.A>’
WORDINDEX(Y,1) -> 1
WORDLENGTH(Y,1) -> 1
Z = ’<.A .B><.C> <.D>’
WORD(Z,2) -> ’<.B><.C>’
WORDINDEX(Z,2) -> 3
WORDLENGTH(Z,2) -> 2
Applying the word extraction from a string and (for WORDINDEX and WORDLENGTH) counting
characters rules.
WORDS
In EBCDIC:
W = ’<><. .A. . .B><.C. .D>’
WORDS(W) -> 3
Applying the word extraction from a string rule.
Appendix C. Double-Byte Character Set (DBCS) Support 403
WORDPOS
In EBCDIC:
WORDPOS(’<.B.C> abc’,’<.A. .B.C> abc’) -> 2
WORDPOS(’<.A.B>’,’<.A.B. .A.B><. .B.C. .A.B>’,3) -> 4
Applying the word extraction from a string and character comparison rules.
DBCS Processing Functions
This section describes the functions that support DBCS mixed strings. These functions handle mixed
strings regardless of the OPTIONS mode.
Note: When used with DBCS functions, length is always measured in bytes (as opposed to
LENGTH(string), which is measured in characters).
Counting Option
In EBCDIC, when specified in the functions, the counting option can control whether the SO and SI are
considered present when determining the length. Yspecifies counting SO and SI within mixed strings. N
specifies not to count the SO and SI, and is the default.
Function Descriptions
The following are the DBCS functions and their descriptions.
DBADJUST
 DBADJUST(string )
,operation

In EBCDIC, adjusts all contiguous SI and SO (or SO and SI) characters in string based on the operation
specified. The following are valid operations. Only the capitalized and highlighted letter is needed; all
characters following it are ignored.
Blank changes contiguous characters to blanks (X'4040').
Remove
removes contiguous characters, and is the default.
Here are some EBCDIC examples:
DBADJUST(’<.A><.B>a<>b’,’B’) -> ’<.A. .B>a b’
DBADJUST(’<.A><.B>a<>b’,’R’) -> ’<.A.B>ab’
DBADJUST(’<><.A.B>’,’B’) -> ’<. .A.B>’
DBBRACKET
 DBBRACKET(string) 
In EBCDIC, adds SO and SI brackets to a DBCS-only string. If string is not a BCS-only string, a SYNTAX
error results. That is, the input string must be an even number of bytes in length and each byte must be a
valid DBCS value.
Here are some EBCDIC examples:
DBBRACKET(’.A.B’) -> ’<.A.B>’
DBBRACKET(’abc’) -> SYNTAX error
DBBRACKET(’<.A.B>’) -> SYNTAX error
404 CICS TS for VSE/ESA: REXX Guide
DBCENTER
 DBCENTER(string,length
,
pad ,option
) 
returns a string of length length with string centered in it, with pad characters added as necessary to make
up length. The default pad character is a blank. If 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.
The option controls the counting rule. Ycounts SO and SI within mixed strings as one each. Ndoes not
count the SO and SI and is the default.
Here are some EBCDIC examples:
DBCENTER(’<.A.B.C>’,4) -> ’ <.B> ’
DBCENTER(’<.A.B.C>’,3) -> ’ <.B>’
DBCENTER(’<.A.B.C>’,10,’x’) -> ’xx<.A.B.C>xx’
DBCENTER(’<.A.B.C>’,10,’x’,’Y’) -> ’x<.A.B.C>x’
DBCENTER(’<.A.B.C>’,4,’x’,’Y’) -> ’<.B>’
DBCENTER(’<.A.B.C>’,5,’x’,’Y’) -> ’x<.B>’
DBCENTER(’<.A.B.C>’,8,’<.P>’) -> ’ <.A.B.C> ’
DBCENTER(’<.A.B.C>’,9,’<.P>’) -> ’ <.A.B.C.P>’
DBCENTER(’<.A.B.C>’,10,’<.P>’) -> ’<.P.A.B.C.P>’
DBCENTER(’<.A.B.C>’,12,’<.P>’,’Y’) -> ’<.P.A.B.C.P>’
DBCJUSTIFY
 DBCJUSTIFY(string,length
,
pad ,option
) 
formats string by adding pad characters between nonblank characters to justify to both margins and length
of bytes length (length must be nonnegative). Rules for adjustments are the same as for the JUSTIFY
function. The default pad character is a blank.
The option controls the counting rule. Ycounts SO and SI within mixed strings as one each. Ndoes not
count the SO and SI and is the default.
Here are some examples:
DBCJUSTIFY(’<><AA BB><CC>’,20,,’Y’)
-> ’<AA> <BB> <CC>’
DBCJUSTIFY(’<>< AA BB>< CC>’,20,’<XX>’,’Y’)
-> ’<AAXXXXXXBBXXXXXXCC>’
DBCJUSTIFY(’<>< AA BB>< CC>’,21,’<XX>’,’Y’)
-> ’<AAXXXXXXBBXXXXXXCC> ’
DBCJUSTIFY(’<>< AA BB>< CC>’,11,’<XX>’,’Y’)
-> ’<AAXXXXBB> ’
DBCJUSTIFY(’<>< AA BB>< CC>’,11,’<XX>’,’N’)
-> ’<AAXXBBXXCC> ’
DBLEFT
 DBLEFT(string,length
,
pad ,option
) 
returns a string of length length containing the leftmost length characters of string. The string returned is
Appendix C. Double-Byte Character Set (DBCS) Support 405
padded with pad characters (or truncated) on the right as needed. The default pad character is a blank.
The option controls the counting rule. Ycounts SO and SI within mixed strings as one each. Ndoes not
count the SO and SI and is the default.
Here are some EBCDIC examples:
DBLEFT(’ab<.A.B>’,4) -> ’ab<.A>’
DBLEFT(’ab<.A.B>’,3) -> ’ab ’
DBLEFT(’ab<.A.B>’,4,’x’,’Y’) -> ’abxx’
DBLEFT(’ab<.A.B>’,3,’x’,’Y’) -> ’abx’
DBLEFT(’ab<.A.B>’,8,’<.P>’) -> ’ab<.A.B.P>’
DBLEFT(’ab<.A.B>’,9,’<.P>’) -> ’ab<.A.B.P> ’
DBLEFT(’ab<.A.B>’,8,’<.P>’,’Y’) -> ’ab<.A.B>’
DBLEFT(’ab<.A.B>’,9,’<.P>’,’Y’) -> ’ab<.A.B> ’
DBRIGHT
 DBRIGHT(string,length
,
pad ,option
) 
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 option controls the counting rule. Ycounts SO and SI within mixed strings as one each. Ndoes not
count the SO and SI and is the default.
Here are some EBCDIC examples:
DBRIGHT(’ab<.A.B>’,4) -> ’<.A.B>’
DBRIGHT(’ab<.A.B>’,3) -> ’ <.B>’
DBRIGHT(’ab<.A.B>’,5,’x’,’Y’) -> ’x<.B>’
DBRIGHT(’ab<.A.B>’,10,’x’,’Y’) -> ’xxab<.A.B>’
DBRIGHT(’ab<.A.B>’,8,’<.P>’) -> ’<.P>ab<.A.B>’
DBRIGHT(’ab<.A.B>’,9,’<.P>’) -> ’ <.P>ab<.A.B>’
DBRIGHT(’ab<.A.B>’,8,’<.P>’,’Y’) -> ’ab<.A.B>’
DBRIGHT(’ab<.A.B>’,11,’<.P>’,’Y’) -> ’ ab<.A.B>’
DBRIGHT(’ab<.A.B>’,12,’<.P>’,’Y’) -> ’<.P>ab<.A.B>’
DBRLEFT
 DBRLEFT(string,length
,option
) 
returns the remainder from the DBLEFT function of string.Iflength is greater than the length of string,
returns a null string.
The option controls the counting rule. Ycounts SO and SI within mixed strings as one each. Ndoes not
count the SO and SI and is the default.
Here are some EBCDIC examples:
DBRLEFT(’ab<.A.B>’,4) -> ’<.B>’
DBRLEFT(’ab<.A.B>’,3) -> ’<.A.B>’
DBRLEFT(’ab<.A.B>’,4,’Y’) -> ’<.A.B>’
DBRLEFT(’ab<.A.B>’,3,’Y’) -> ’<.A.B>’
DBRLEFT(’ab<.A.B>’,8) -> ’’
DBRLEFT(’ab<.A.B>’,9,’Y’) -> ’’
DBRRIGHT
406 CICS TS for VSE/ESA: REXX Guide
 DBRRIGHT(string,length
,option
) 
returns the remainder from the DBRIGHT function of string.Iflength is greater than the length of string,
returns a null string.
The option controls the counting rule. Ycounts SO and SI within mixed strings as one each. Ndoes not
count the SO and SI and is the default.
Here are some EBCDIC examples:
DBRRIGHT(’ab<.A.B>’,4) -> ’ab’
DBRRIGHT(’ab<.A.B>’,3) -> ’ab<.A>’
DBRRIGHT(’ab<.A.B>’,5) -> ’a’
DBRRIGHT(’ab<.A.B>’,4,’Y’) -> ’ab<.A>’
DBRRIGHT(’ab<.A.B>’,5,’Y’) -> ’ab<.A>’
DBRRIGHT(’ab<.A.B>’,8) -> ’’
DBRRIGHT(’ab<.A.B>’,8,’Y’) -> ’’
DBTODBCS
 DBTODBCS(string) 
converts all passed, valid SBCS characters (including the SBCS blank) within string to the corresponding
DBCS equivalents. Other single-byte codes and all DBCS characters are not changed. In EBCDIC, SO
and SI brackets are added and removed where appropriate.
Here are some EBCDIC examples:
DBTODBCS(’Rexx 1988’) -> ’<.R.e.x.x. .1.9.8.8>’
DBTODBCS(’<.A> <.B>’) -> ’<.A. .B>’
Note: In these examples, the .x is the DBCS character corresponding to an SBCS x.
DBTOSBCS
 DBTOSBCS(string) 
converts all passed, valid DBCS characters (including the DBCS blank) within string to the corresponding
SBCS equivalents. Other DBCS characters and all SBCS characters are not changed. In EBCDIC, SO and
SI brackets are removed where appropriate.
Here are some EBCDIC examples:
DBTOSBCS(’<.S.d>/<.2.-.1>’) -> ’Sd/2-1’
DBTOSBCS(’<.X. .Y>’) -> ’<.X> <.Y>’
Note: In these examples, the .d is the DBCS character corresponding to an SBCS d. But the .X and .Y
do not have corresponding SBCS characters and are not converted.
DBUNBRACKET
 DBUNBRACKET(string) 
In EBCDIC, removes the SO and SI brackets from a DBCS-only string enclosed by SO and SI brackets. If
the string is not bracketed, a SYNTAX error results.
Here are some EBCDIC examples:
DBUNBRACKET(’<.A.B>’) -> ’.A.B’
DBUNBRACKET(’ab<.A>’) -> SYNTAX error
Appendix C. Double-Byte Character Set (DBCS) Support 407
DBVALIDATE
 DBVALIDATE(string
,'C'
) 
returns 1if the string is a valid mixed string or SBCS string. Otherwise, returns 0. Mixed string validation
rules are:
1. Only valid DBCS character codes
2. DBCS string is an even number of bytes in length
3. EBCDIC only — Proper SO and SI pairing.
In EBCDIC, if Cis omitted, only the leftmost byte of each DBCS character is checked to see that it falls in
the valid range for the implementation it is being run on (that is, in EBCDIC, the leftmost byte range is
from X'41' to X'FE').
Here are some EBCDIC examples:
z=’abc<de’
DBVALIDATE(’ab<.A.B>’) -> 1
DBVALIDATE(z) -> 0
y=’C1C20E111213140F’X
DBVALIDATE(y) -> 1
DBVALIDATE(y,’C’) -> 0
DBWIDTH
 DBWIDTH(string
,option
) 
returns the length of string in bytes.
The option controls the counting rule. Ycounts SO and SI within mixed strings as one each. Ndoes not
count the SO and SI and is the default.
Here are some EBCDIC examples:
DBWIDTH(’ab<.A.B>’,’Y’) -> 8
DBWIDTH(’ab<.A.B>’,’N’) -> 6
408 CICS TS for VSE/ESA: REXX Guide
Appendix D. Reserved Keywords and Special Variables
You can use keywords as ordinary symbols in many situations where there is no ambiguity. The precise
rules are given here.
There are three special variables: RC, RESULT, and SIGL.
Reserved Keywords
The free syntax of REXX implies that some symbols are reserved for the language processor's use in
certain contexts.
Within particular instructions, some symbols may be reserved to separate the parts of the instruction.
These symbols are referred to as keywords. Examples of REXX keywords are the WHILE in a DO
instruction and the THEN (which acts as a clause terminator in this case) following an IF or WHEN clause.
Apart from these cases, only simple symbols that are the first token in a clause and that are not followed
by an =or :are checked to see if they are instruction keywords. You can use the symbols freely
elsewhere in clauses without their being taken as keywords.
It is not, however, recommended for users to run host commands or commands with the same name as
REXX keywords (QUEUE, for example). This can create problems for any programmer whose REXX
programs might be used for some time and in circumstances outside his or her control, and who wishes to
make the program absolutely watertight.
In this case, a REXX program may be written with (at least) the first words in command lines enclosed in
quotation marks.
Example:
’SCRNINFO’
This also has the advantage of being more efficient, and, with this style, you can use the SIGNAL ON
NOVALUE condition to check the integrity of an exec.
An alternative strategy is to precede such command strings with two adjacent quotation marks, which
concatenates the null string on to the front.
Example:
’’SCRNINFO
A third option is to enclose the entire expression (or the first symbol) in parentheses.
Example:
(SCRNINFO)
More important, the choice of strategy (if it is to be done at all) is a personal one by the programmer. The
REXX language does not impose it.
Special Variables
There are three special variables that the language processor can set automatically:
RC is set to the return code from any run host command (or subcommand). Following the SIGNAL
events, SYNTAX, ERROR, and FAILURE, RC is set to the code appropriate to the event: the
syntax error number (see appendix on error messages) or the command return code. RC is
unchanged following a NOVALUE or HALT event.
© Copyright IBM Corp. 1992, 2010 409
Note: Host commands run manually from debug mode do not cause the value of RC to change.
RESULT
is set by a RETURN instruction in a subroutine that has been called if the RETURN instruction
specifies an expression. If the RETURN instruction has no expression on it, RESULT is dropped
(becomes uninitialized.)
SIGL contains the line number of the clause currently executing when the last transfer of control to a
label took place. (A SIGNAL, a CALL, an internal function invocation, or a trapped error condition
could cause this.)
None of these variables has an initial value. You can alter them, just as with any other variable, and the
PROCEDURE and DROP instructions affect these variables in the usual way.
Certain other information is always available to a REXX program. This includes the name that the program
was called and the source of the program (which is available using the PARSE SOURCE instruction—see
page 153). PARSE SOURCE output consists of the string CICS followed by the call type, the name of the
exec in uppercase, the name of the file, and library member being run. These are followed by the name by
which the program was called and the initial (default) command environment.
In addition, PARSE VERSION (see page 154) makes available the version and date of the language
processor code that is running. The built-in functions TRACE and ADDRESS return the current trace
setting and environment name, respectively.
Finally, you can obtain the current settings of the NUMERIC function by using the DIGITS, FORM, and
FUZZ built-in functions.
Keywords and Variables
410 CICS TS for VSE/ESA: REXX Guide
Appendix E. Debug Aids
This appendix describes the interactive debugging of problems, interrupting execution, and controlling
tracing.
Interactive Debugging of Programs
The debug facility permits interactively controlled execution of a program.
Changing the TRACE action to one with a prefix ?(for example, TRACE ?A or the TRACE built-in function)
turns on interactive debug and indicates to the user that interactive debug is active. Further TRACE
instructions in the program are ignored, and the language processor pauses after nearly all instructions
that are traced at the console (see the following for the exceptions). When the language processor
pauses, indicated by a READ in the lower corner of the screen, three debug actions are available:
1. Entering a null line (with no characters, even blanks) makes the language processor continue
execution until the next pause for debug input. Repeatedly entering a null line, therefore, steps from
pause point to pause point. For TRACE ?A, for example, this is equivalent to single-stepping through the
program.
2. Entering an equal sign (=) with no blanks makes the language processor rerun the clause last traced.
For example: if an IF clause is about to take the wrong branch, you can change the value of the
variable(s) on which it depends, and then rerun it.
Once the clause has been rerun, the language processor pauses again.
3. Anything else entered is treated as a line of one or more clauses, and processed immediately (that
is, as though DO; line; END; had been inserted in the program). The same rules apply as in the
INTERPRET instruction (for example, DO-END constructs must be complete). If an instruction has a
syntax error in it, a standard message is displayed and you are prompted for input again. Similarly all
the other SIGNAL conditions are disabled while the string is processed to prevent unintentional transfer
of control.
During execution of the string, no tracing takes place, except that nonzero return codes from host
commands are displayed. Host commands are always run (that is, are not affected by the prefix !on
TRACE instructions), but the variable RC is not set.
Once the string has been processed, the language processor pauses again for further debug input
unless a TRACE instruction was entered. In this latter case, the language processor immediately alters
the tracing action (if necessary) and then continues executing until the next pause point (if any). To
alter the tracing action (from All to Results, for example) and then rerun the instruction, you must use
the built-in function TRACE (see page 195). For example, CALL TRACE I changes the trace action to I
and allows re-execution of the statement after which the pause was made. Interactive debug is turned
off, when it is in effect, if a TRACE instruction uses a prefix, or at any time when a TRACE O or TRACE
with no options is entered.
You can use the numeric form of the TRACE instruction to allow sections of the program to be run
without pause for debug input. TRACE n (that is, positive result) allows execution to continue, skipping
the next npauses (when interactive debug is or becomes active). TRACE -n (that is, negative result)
allows execution to continue without pause and with tracing inhibited for nclauses that would otherwise
be traced.
The trace action selected by a TRACE instruction is saved and restored across subroutine calls. This
means that if you are stepping through a program (say after using TRACE ?R to trace Results) and then
enter a subroutine in which you have no interest, you can enter TRACE O to turn tracing off. No further
instructions in the subroutine are traced, but on return to the caller, tracing is restored.
Similarly, if you are interested only in a subroutine, you can put a TRACE ?R instruction at its start. Having
traced the routine, the original status of tracing is restored and (if tracing was off on entry to the
subroutine) tracing (and interactive debug) is turned off until the next entry to the subroutine.
© Copyright IBM Corp. 1992, 2010 411
Since any instructions may be run in interactive debug, you have considerable control over execution.
Some examples:
Say expr /* displays the result of evaluating the */
/* expression. */
name=expr /* alters the value of a variable. */
Trace O /* (or Trace with no options) turns off */
/* interactive debug and all tracing. */
Trace ?A /* turns off interactive debug but continues */
/* tracing all clauses. */
Trace L /* makes the language processor pause at labels */
/* only. This is similar to the traditional */
/* "breakpoint" function, except that you */
/* do not have to know the exact name and */
/* spelling of the labels in the program. */
exit /* stops execution of the program. */
Do i=1 to 10; say stem.i; end
/* displays ten elements of the array stem. */
Note: While in interactive debug, pauses may occur because of PULL statements as well as because of
interactive debug. For programs containing PULL statements, it is important to be aware of the
reason for each pause. In programs, PULL statements are often paired with SAY statements. The
user should enter the data for the PULL at the pause after the trace line for the PULL (the pause
specifically for entering data for the PULL). The user should not enter the data at the pause after
the corresponding SAY statement (this is an interactive debug pause). Exceptions: Some clauses
cannot safely be re-run, and, therefore, the language processor does not pause after them, even if
they are traced. These are:
vAny repetitive DO clause, on the second or subsequent time around the loop.
vAll END clauses (not a useful place to pause in any case).
vAll THEN, ELSE, OTHERWISE, or null clauses.
vAll RETURN and EXIT clauses.
vAll SIGNAL and CALL clauses (the language processor pauses after the target label has been
traced).
vAny clause that raises a condition that CALL ON or SIGNAL ON traps (the pause takes place
after the target label for the CALL or SIGNAL has been traced).
vAny clause that causes a syntax error. (These may be trapped by SIGNAL ON SYNTAX, but
cannot be re-run.)
Interrupting Execution and Controlling Tracing
You can use standard CICS facilities to interrupt a REXX exec (the REXX transaction). If properly
authorized, you can issue the CEMT SET TASK PURGE command to halt an exec. Refer to the CICS
Transaction Server for VSE/ESA CICS Supplied Transactions for more information.
Debug Aids
412 CICS TS for VSE/ESA: REXX Guide
Appendix F. REXX/CICS Business Value Discussion
CICS Transaction Server for VSE/ESA REXX provides an ideal system to deliver superior, valuable, and
appropriate CICS-based business solutions in a more timely and cost-effective manner.
Business Solutions
The ability to deliver business solutions more quickly is an important advantage in today's competitive
marketplace.
vCICS Transaction Server for VSE/ESA REXX is a simple, uniform, self-contained development
environment
CICS Transaction Server for VSE/ESA REXX supports development directly under CICS and provides
much of what the average CICS developer needs in one manageable package.
REXX is a high-level language that is natural to use and frees the programmer from unnecessary detail.
REXX programs tend to be shorter and easier to follow than programs written in other languages. To
use REXX for CICS Transaction Server for VSE/ESA REXX a new programmer does not have to learn
JCL, COBOL or significant technical detail of CICS (such as the CICS translator).
vCICS Transaction Server for VSE/ESA REXX allows solutions to be delivered quickly
These programs enable gains in application productivity and may reduce delivery time. The REXX
language boosts application productivity because of its high level, simplicity, strong parsing,
"naturalness," and interpretive support. The interpreter provides a reduced development cycle and has
excellent source-level interactive debugging capability.
vCICS Transaction Server for VSE/ESA REXX makes incremental development a reality
Larger, more sophisticated development efforts are feasible and productivity improvements can be
achieved by using the powerful interactive source-level debugging capability and the fast development
cycle of the REXX interpreter. The interpreter, with its fast, natural development cycle and excellent
source-based interactive debugging, better enables the switch to an Incremental Development
Methodology (also known as Prototyping Development Methodology).
With this methodology, REXX can be used for quick and expressive prototyping. Because of the special
performance techniques used and the robustness of the language, REXX is also suitable for
professional application development.
CICS Transaction Server for VSE/ESA REXX provides an ideal environment where prototypes can be
developed quickly to test system feasibility and get user involvement. The prototypes can then be
"grown" into useful production systems.
Prototyping reduces the possibility of finding out late in the development cycle that the project is not
technically feasible or cannot deliver what the customers want. An additional benefit of incremental
development is that the code is tested more thoroughly during development and may result in much
higher quality.
vCICS Transaction Server for VSE/ESA REXX applications are manageable and easy to maintain
and support.
High-level, REXX-based applications are usually smaller than comparable applications in other
languages (in lines of code) and are easier to read and understand. The interactive source-level
debugging capability of the REXX interpreter simplifies problem determination and resolution, making
REXX-based applications less expensive to support and enhance.
CICS Transaction Server for VSE/ESA REXX organizes (breaks down) complex systems and makes
them more manageable. REXX provides a natural building block approach made up of execs,
application macros, and subcommands implemented transparently in a variety of languages. Closely
related is the built-in client/server computing support that encourages greater host involvement in the
enterprise-wide client/server distributed computing model. Another benefit of ESA/VSE is the facilities it
has for integrating multiple applications, products, and system facilities into one seamless package,
which can simplify systems development efforts.
© Copyright IBM Corp. 1992, 2010 413
vCICS Transaction Server for VSE/ESA REXX is useable by business people
Quite often, business people who best understand the business and their required solutions have ideas
on modifying or enhancing the applications they use. However, without extensive training and
experience with a programming language, they may be unable to implement the ideas. One of the
greatest strengths of REXX is its simplicity and “naturalness” on the one hand, and its powerful
capabilities on the other. CICS Transaction Server for VSE/ESA REXX makes it possible, in some
cases, for CICS application users to customize and even extend applications without expending scarce
programmer resources. This allows more effective tailoring of applications to individual business needs.
CICS Transaction Server for VSE/ESA REXX facilitates the use of a prototyping methodology. The
users of an application under development can participate very closely in the application development
process. The end result is that those who have the best understanding of the business and their own
needs can better ensure that the application solution delivered matches their needs. This close
involvement has the added benefit of addressing human factor needs (useability) earlier in the
application development cycle.
vCICS Transaction Server for VSE/ESA REXX facilitates systems management
One of the major uses of REXX is as a Procedures (Scripting) Language. CICS Transaction Server for
VSE/ESA REXX can be used to automate sequences of CICS system and application systems
management activities, providing greater productivity and reliability.
Since CICS Transaction Server for VSE/ESA REXX supports application development (and testing)
directly under CICS, systems management can be simplified.
Business Value Discussion
414 CICS TS for VSE/ESA: REXX Guide
vCICS Transaction Server for VSE/ESA REXX supports six languages
CICS Transaction Server for VSE/ESA REXX provides REXX messages in six languages, in addition to
U.S. English:
– Canadian French
– French
– German
– Japanese Kanji
– Spanish
– Simplified Chinese.
Only the REXX messages are translated. The text editor and file list utility are not translated.
The translated messages files are included on the product tape and are not separate features.
Product Positioning
The IBM CICS computing environment is one of the largest concentrations of customer production
applications and data in the world. There has been tremendous customer investment in CICS-based
mainframe systems, CICS-based application development, data collection for CICS-based systems, and
employee education relating to the use and support of CICS-based systems. CICS Transaction Server for
VSE/ESA REXX helps preserve and enhance the usefulness of this investment.
Not only does CICS Transaction Server for VSE/ESA REXX enhances the delivery of traditional
CICS-based production applications, it makes the CICS environment suitable for a broader range of
information processing activities. With CICS Transaction Server for VSE/ESA REXX, it is now practical to
also perform end-user computing, prototyping, and application development directly within the CICS
environment, either in separate or common regions.
Business Value Discussion
Appendix F. REXX/CICS Business Value Discussion 415
416 CICS TS for VSE/ESA: REXX Guide
Appendix G. System Definition/Customization/Administration
This appendix discusses the system definition, customization, and administration of REXX/CICS.
Authorized REXX/CICS Commands/Authorized Command Options
Several REXX/CICS commands, or command options, are identified as being authorized. An authorized
REXX/CICS command can only be executed if:
vThe user ID issuing the exec is an authorized REXX/CICS user. Authorized users are defined by the
AUTHUSER command.
vThe exec was loaded from a REXX/CICS authorized sublibrary. An authorized sublibrary is a VSE
Librarian sublibrary specified on a SETSYS AUTHCLIB or a SETSYS AUTHELIB command.
This rule applies regardless of whether or not the exec attempting the command was issued by an
authorized exec.
System Profile Exec
A system profile exec, named CICSTART, is issued before the first user exec is run after a CICS system
restart. Usually, the system profile exec contains system customization commands, authorized sublibrary
definitions, authorized user definitions, and authorized command definitions that must reside in an
authorized REXX/CICS sublibrary.
The CICSTART exec is loaded from the first occurrence of the member CICSTART.PROC in the LIBDEF
PROC search chain for the CICS partition.
Note: The sublibrary in which the member CICSTART.PROC is found is treated as the initial authorized
REXX/CICS sublibrary. This can then be changed using the SETSYS AUTHCLIB and SETSYS
AUTHELIB commands.
Authorized REXX/CICS VSE Librarian sublibraries
The VSE Librarian sublibraries specified on the SETSYS AUTHCLIB and SETSYS AUTHELIB commands
are considered REXX/CICS authorized sublibraries. If multiple sublibraries are specified, they are searched
in the order specified in the command.
The sublibrary in the LIBDEF PROC search chain for the CICS partition containing the member
CICSTART.PROC used to initialize REXX/CICS is treated as the initial authorized sublibrary. This can then
be changed by using the SETSYS AUTHCLIB and SETSYS AUTHELIB commands.
Notes:
1. Users can cause dynamic allocation of their own VSE Librarian sublibraries by using the REXX/CICS
PATH command.
2. Any user can run an exec from a sublibrary specified in the SETSYS AUTHELIB command and any
exec loaded from one of these sublibraries can use REXX/CICS authorized commands.
Defining Authorized Users
Users may be specified as authorized by the AUTHUSER command. It is recommended that all
AUTHUSER commands be placed in the CICSTART exec, or in an exec issued from within the CICSTART
exec.
© Copyright IBM Corp. 1992, 2010 417
Setting System Options
System options are specified by using the REXX/CICS SETSYS command. It is recommended that
system-wide SETSYS commands be placed in the CICSTART exec.
Defining and Initializing a REXX File System (RFS) File Pool
Use the FILEPOOL DEFINE command to define a RFS file pool. Use the FILEPOOL FORMAT command
to initialize the first file in each file pool.
Adding Files to a REXX File System (RFS) File Pool
Use the FILEPOOL ADD command to add a VSAM file to a REXX File System file pool.
RFS File Sharing Authorization
Use the RFS AUTH command to specify file sharing permission. Normally, you can allow sharing of
resources that you own. As an authorized REXX/CICS user you can specify permission for the sharing of
any RFS directories that you have created.
Creating a PLT Entry for CICSTART
The CICSTART exec can be issued immediately after CICS system initialization by creating a CICS
program load table (PLT) entry to invoke the CICREXD program. Otherwise, the first REXX/CICS user
after region startup will cause the CICSTART exec to be run.
Security exits
This section describes replaceable security exits CICSEXC1 and CICSECX2. IBM provides sample
assembler exits that you can customize or replace.
Note: These exits must reside in the same region as REXX/CICS (for example: the use of distributed
program link is not allowed).
CICSEXC1
CICSECX1 is a library member access security exit.
Parameters
The COMMAREA contains the following on input to the exit.
Parameter Number of Bytes Datatype Description
1 4 fullword Return code
2 8 character CICS sign on ID
3 4 character Function requested
4 44 character VSEMEM class resource ID
libname.sublibname.membername
5 4 fullword Length of the VSEMEM resource ID
6 3 character IMPORT access intent
7 7 character Library name
Return codes
0Function request allowed
System Definition/Customization/Administration
418 CICS TS for VSE/ESA: REXX Guide
4Not authorized
Function IDs
CNVT CONVTMAP request
EXPT EXPORT request
IMPT IMPORT request
IMPORT access intent
EXC Read and write, for example EDIT.
SHR Read only.
IMPT Read only.
CICSECX2
CICSECX2 is a REXX File System access security exit.
Parameters
The COMMAREA contains the following on input to the exit.
Parameter Number of Bytes Datatype Description
1 4 fullword Return code
2 8 character CICS sign on ID
3 1 character Function requested
4 3 Reserved for IBM use
5 4 fullword Address of fully qualified RFS file ID string
6 4 fullword Length of RFS file ID string
Return Codes
0Function request allowed
non-zero
Not authorized
Function IDs
AAlter
RRead
UUpdate
System Definition/Customization/Administration
Appendix G. System Definition/Customization/Administration 419
System Definition/Customization/Administration
420 CICS TS for VSE/ESA: REXX Guide
Appendix H. Security
REXX/CICS can be viewed as a more sophisticated version of the CICS-supplied Command Level
Interpreter Transaction (CECI). The REXX transaction (used to issue REXX execs), much like the CECI
transaction, can be controlled using CICS transaction security. The REXX transaction might be made
widely available, or might be limited to a few individuals, depending upon the nature of the CICS region it
is running in.
Note: The REXX transaction is not required to execute existing REXX execs, but is required if users or
programmers want the ability to create or modify REXX execs, and then test them.
REXX/CICS Supports Multiple Transaction Identifiers
REXX/CICS supports the ability to associate transaction identifiers (TRANIDs), other than REXX, with the
REXX/CICS support program. In this case, the name of the REXX exec that is issued is determined by a
previous DEFTRNID command. This gives you the ability to still use transaction security with REXX on an
exec by exec basis.
REXX/CICS File Security
Access at the RFS directory level is controlled with the RFS AUTH command and the RFS replaceable
security exit.
ESA/VSE Command Level Security
In some situations, current software practices limit the effectiveness of relying on CICS resource security
alone. For additional security control, REXX/CICS was designed with the concept of command level
security. Because most facilities under REXX/CICS are accessed as commands, command level security
can be used to control access to CICS (and other product or system) facilities. For example, VSAM file
access is accomplished through the READ, WRITE, and REWRITE commands.
REXX/command level security is controlled by the DEFSCMD and DEFCMD AUTH parameter and by the
provision of authorized REXX/CICS library support.
Command execution security controls the use of certain REXX/CICS commands, or command keywords.
In general, this is accomplished by the designation of certain commands (or command options) as
authorized. Such command designation is accomplished by the DEFCMD and DEFSCMD commands. For
authorized commands to execute properly, they must either be:
1. Executed from an exec loaded from a VSE Librarian sublibrary specified on a SETSYS AUTHCLIB or
SETSYS AUTHELIB command.
2. Executed by an authorized user. A user can be authorized by the AUTHUSER command.
REXX/CICS Authorized Command Support
Any REXX/CICS command can be identified as authorized by a REXX/CICS Systems Administrator.
Authorized commands can only be successfully executed in an exec that is issued by an authorized
REXX/CICS user or that was loaded from an authorized REXX/CICS sublibrary. Only authorized
REXX/CICS users have access to the commands and execs in the “authorized command” sublibraries
specified on the SETSYS AUTHCLIB command. All users have the ability to run execs in the “authorized
exec” sublibraries specified on the SETSYS AUTHELIB command. All users can run execs in sublibraries
specified in the LIBDEF PROC search chain for the CICS partition. Authorized users can be defined by
any existing authorized user or in an authorized exec. The REXX/CICS CICSTART exec that is called at
REXX/CICS initialization (at the first REXX/CICS transaction after a CICS restart) is automatically
© Copyright IBM Corp. 1992, 2010 421
authorized. This is the logical place to define authorized users and libraries. The sublibrary containing the
CICSTART exec is treated as the initial “authorized command” and “authorized exec” sublibrary.
Because access to REXX/CICS libraries can easily be controlled, this is the logical counterpart to
controlling access to CICS production program libraries. Any commands that a site feels are sensitive
(such as READ, WRITE, and DELETE) could be defined as authorized in the production region. This
would mean that only authorized users could create execs that issue authorized commands and decide
whether all users could invoke these execs that contain authorized commands or only other authorized
users.
Note: You can control the ability of REXX/CICS execs to access external APIs by redefining the CICS
START, LINK, and XCTL commands as REXX/CICS authorized commands.
Security Definitions
This section discusses the security definitions for REXX/CICS such as: general users, authorized users,
authorized commands, authorized exec, and system libraries.
REXX/CICS General Users
REXX/CICS users that are not defined as authorized by the AUTHUSER command cannot use
REXX/CICS authorized commands. However, these users can define, write, alter, and use user commands
(defined using the DEFCMD command) and execs. Users can also use (but not define, create, or alter)
REXX/CICS authorized execs that reside in the CICEXEC library.
REXX/CICS Authorized Users
Authorized users are defined by the AUTHUSER command, that are allowed to use authorized
REXX/CICS commands (commands defined using the DEFCMD or DEFSCMD command with the AUTH
option specified).
REXX/CICS Authorized Commands
Authorized commands are REXX/CICS commands that can only be used by authorized users or from
authorized execs. Authorized commands are defined using the DEFCMD or DEFSCMD command with the
AUTH option specified.
REXX/CICS Authorized Execs
Authorized execs are programs (execs) that were loaded from sublibraries that were specified on the
SETSYS AUTHCLIB or SETSYS AUTHELIB commands and are considered authorized. That is, these
programs are allowed to use authorized REXX/CICS commands. All REXX/CICS users have access to
execs loaded from the sublibraries specified on the SETSYS AUTHELIB command, but only authorized
users have access to commands and execs loaded from the sublibraries specified on the SETSYS
AUTHCLIB command.
REXX/CICS System Sublibraries
All authorized commands written in the REXX language must be loaded from a VSE Librarian sublibrary
specified on the SETSYS AUTHCLIB command. These may be both IBM and customer (or vendor)
supplied.
All authorized execs must be loaded from a VSE Librarian sublibrary specified on either the SETSYS
AUTHCLIB or SETSYS AUTHELIB commands. These may be both IBM and customer (or vendor)
supplied.
User execs that are not authorized but are being shared by all REXX/CICS users can be placed in a VSE
Librarian sublibrary specified in the LIBDEF PROC search chain for the CICS partition.
Security
422 CICS TS for VSE/ESA: REXX Guide
Notes:
1. The AUTH option of the DEFCMD or DEFSCMD is itself an authorized command option. That is,
AUTH may only be used if the user issuing it is an authorized user or if it was issued from an exec
loaded from an authorized sublibrary.
2. The EXECLOAD and EXECDROP commands are authorized. Therefore, only an authorized user or
exec can EXECLOAD an exec from an authorized sublibrary.
Security
Appendix H. Security 423
Security
424 CICS TS for VSE/ESA: REXX Guide
Appendix I. Performance Considerations
Because of the production nature of CICS, emphasis is placed on performance. Many design choices can
affect performance. These include:
vHow REXX environments are defined
vHow the REXX File System structure is implemented
vHow security interfaces are implemented
vHow much virtual storage is given to an exec at invocation.
REXX uses sophisticated techniques, such as look-aside tables and tree balancing, for good performance.
Although REXX execs are interpreted, most of the actual processing for the typical application is spent
executing the REXX commands that do most of the actual work. These commands can be (and usually
are) written in Assembler, or a compiled language, when performance is an important consideration.
Client/server support is a REXX feature that provides a substantial performance advantage. With this
facility, a server REXX exec can often be used instead of a nested REXX exec to provide application
function. The performance characteristics of such a server can be better managed. The advantage of a
server exec over a nested exec is that a server exec can be started and can process multiple client
requests before ending. This has a shorter path-length, provides better response time, and often uses less
system resource.
An EXEC CICS SUSPEND is automatically issued after every 1024 clauses executed in an exec to help
prevent a REXX/CICS exec from monopolizing processor resources.
Usually, for the majority of small- to medium-scale CICS applications, the productivity benefits of using
REXX far outweighs the performance penalty.
REXX/CICS execs may reside in either VSAM-based REXX File System files or in VSE Librarian
sublibraries.
© Copyright IBM Corp. 1992, 2010 425
426 CICS TS for VSE/ESA: REXX Guide
Appendix J. Basic Mapping Support Example
This appendix has a list of steps that you must follow so you can use the CICS basic mapping support
(BMS) within the REXX/CICS environment. The steps include:
1. BMS maps must be assembled and linked into a CICS library. This library must be in the LIBDEF in
the CICS region startup JCL.
2. If you are going to use the REXX/CICS CONVTMAP command to generate a file structure, the BMS
map must be assembled to produce the map DSECT.
3. BMS maps must be defined to CICS using Resource Definition Online (RDO).
4. If you want to read from or send data to the screen, you need to GETMAIN CICS storage for the
length of the map input/output areas. The storage must be initialized to nulls.
5. If a field within a file structure is represented by more than one label, then the last label to reference
that field in the structure must be used when referencing the field.
The example in this appendix is using BMS map PANELG. The following is the map definition.
TITLE ’PANEL GROUP FOR REXX/CICS ’ 00000010
PRINT ON,NOGEN 00000020
PANELG DFHMSD TYPE=MAP,LANG=ASM,MODE=INOUT,STORAGE=AUTO,SUFFIX= 00000030
TITLE ’TEST PANEL FOR REXX/CICS ’ 00000040
DPANEL1 DFHMDI SIZE=(24,80),CTRL=(FREEKB),MAPATTS=(COLOR,HILIGHT), *00000050
DSATTS=(COLOR,HILIGHT),COLUMN=1,LINE=1,DATA=FIELD, *00000060
TIOAPFX=YES,OBFMT=NO 00000070
DFHMDF POS=(1,1),LENGTH=1,ATTRB=(PROT,BRT) 00000080
DFHMDF POS=(5,27),LENGTH=22,INITIAL=’REXXCICS HEADER PANEL1’, *00000090
ATTRB=(PROT,NORM) 00000100
DFHMDF POS=(5,73),LENGTH=6,INITIAL=’PANEL1’,ATTRB=(PROT,NORM) 00000110
DFHMDF POS=(9,6),LENGTH=25, *00000120
INITIAL=’PLEASE ENTER YOUR USERID:’,ATTRB=(PROT,NORM) 00000130
* DUSERID 00000140
DUSERID DFHMDF POS=(9,32),LENGTH=8,ATTRB=(UNPROT,BRT,IC,FSET) 00000150
DFHMDF POS=(9,41),LENGTH=1,ATTRB=(PROT,NORM) 00000160
DFHMDF POS=(14,6),LENGTH=4,INITIAL=’MSG:’,ATTRB=(PROT,NORM) 00000170
* DMSG 00000180
DMSG DFHMDF POS=(14,11),LENGTH=29,ATTRB=(UNPROT,NORM,FSET) 00000190
DFHMDF POS=(14,41),LENGTH=1,ATTRB=(PROT,NORM) 00000200
DFHMSD TYPE=FINAL 00000210
END 00000220
© Copyright IBM Corp. 1992, 2010 427
The map DSECT follows.
* TEST PANEL FOR REXX/CICS 00000010
PANEL1S EQU * START OF DEFINITION 00000020
SPACE 00000030
DS CL12 TIOA PREFIX 00000040
DUSERIDL DS CL2 INPUT DATA FIELD LENGTH 00000050
DUSERIDF DS 0C DATA FIELD FLAG 00000060
DUSERIDA DS C DATA FIELD 3270 ATTRIBUTE 00000070
DUSERIDC DS C COLOR ATTRIBUTE 00000080
DUSERIDH DS C HIGHLIGHTING ATTRIBUTE 00000090
DUSERIDI DS 0CL8 INPUT DATA FIELD 00000100
DUSERIDO DS CL8 OUTPUT DATA FIELD 00000110
SPACE 00000120
DMSGL DS CL2 INPUT DATA FIELD LENGTH 00000130
DMSGF DS 0C DATA FIELD FLAG 00000140
DMSGA DS C DATA FIELD 3270 ATTRIBUTE 00000150
DMSGC DS C COLOR ATTRIBUTE 00000160
DMSGH DS C HIGHLIGHTING ATTRIBUTE 00000170
DMSGI DS 0CL29 INPUT DATA FIELD 00000180
DMSGO DS CL29 OUTPUT DATA FIELD 00000190
SPACE 00000200
PANEL1E EQU * 00000210
ORG PANEL1S ADDRESS START 00000220
* CALCULATE MAPLENGTH, ASSIGNING A VALUE OF ONE WHERE LENGTH=ZERO 00000230
PANEL1L EQU PANEL1E-PANEL1S 00000240
PANEL1I DS 0CL(PANEL1L+1-(PANEL1L/PANEL1L)) 00000250
PANEL1O DS 0CL(PANEL1L+1-(PANEL1L/PANEL1L)) 00000260
ORG 00000270
* * * END OF DEFINITION*** 00000280
SPACE 3 00000290
ORG 00000300
PANELGT EQU * * END OF MAP SET 00000310
* * * END OF MAP SET DEFINITION*** 00000320
SPACE 3 00000330
The CONVTMAP command is used to take the DSECT and create a file structure stored in the RFS. The
command is entered as follows:
’CONVTMAP USER.TEST(PANELG) POOL1:\USERS\USER1\PANELG.DATA’
The following is the file structure created by CONVTMAP.
00000 ***************************** TOP OF DATA *************************
00001 DUSERIDL 13 2 C
00002 DUSERIDF 15 1 C
00003 DUSERIDA 15 1 C
00004 DUSERIDC 16 1 C
00005 DUSERIDH 17 1 C
00006 DUSERIDI 18 8 C
00007 DUSERIDO 18 8 C
00008 DMSGL 26 2 C
00009 DMSGF 28 1 C
00010 DMSGA 28 1 C
00011 DMSGC 29 1 C
00012 DMSGH 30 1 C
00013 DMSGI 31 29 C
00014 DMSGO 31 29 C
00015 ***************************** BOTTOM OF DATA***********************
The following example is exec BMSMAP1. It creates a simple panel that asks for a user ID.
/* This EXEC uses CICS SEND and RECEIVE commands */
/* The panel has two fields USERID and a message */
/* field. The panel is initially displayed with */
/* a message - "USERID must be 8 characters" */
/* GETMAIN storage to be used for data mapping */
BMS Example
428 CICS TS for VSE/ESA: REXX Guide
/* and initialize */
’PSEUDO OFF’
ZEROES = ’00’x
’CICS GETMAIN SET(WORKPTR) LENGTH(90) INITIMG(ZEROES)’
VAR1 = ’USERID must be 8 characters’
/* Copy the REXX variable VAR1 to the GETMAINed storage */
’COPYR2S VAR1 WORKPTR 30’
/* Copy the storage area to REXX variable */
’COPYS2R WORKPTRX090’
’CICS SEND MAP(PANELG) FREEKB ERASE FROM(X)’
’CICS RECEIVE MAP(PANELG) INTO(Y)’
/* Copy Y into the GETMAINED storage area and then copy the data */
/* to REXX variables using the file structure generated */
/* previously by the CONVTMAP command */
’COPYR2S Y WORKPTR 0 90’
’COPYS2R WORKPTR * POOL1:\USERS\USER1\PANELG.DATA’
/* loop until the user enters a USERID exactly 8 characters in */
/* length */
do forever
MUSERID = STRIP(DUSERIDO)
if LENGTH(MUSERID) < 8 then
do
DMSGO = ’Please enter 8 char USERID’
’COPYR2S * WORKPTR POOL1:\USERS\USER1\PANELG.DATA’
’COPYS2R WORKPTRX090’
’CICS SEND MAP(PANELG) FREEKB ERASE FROM(X)’
’CICS RECEIVE MAP(PANELG) INTO(Z)’
’COPYR2S Z WORKPTR 0 90’
’COPYS2R WORKPTR * POOL1:\USERS\USER1\PANELG.DATA’
END
ELSE LEAVE
END
’SENDE’
say’’
say ’Hello’ DUSERIDO’, Welcome to REXX/CICS !!’
exit
The BMSMAP1 exec created the following panels.
REXX/CICS HEADER PANEL1 PANEL1
PLEASE ENTER YOUR USERID:
MSG: USERID must be 8 characters
BMS Example
Appendix J. Basic Mapping Support Example 429
REXX/CICS HEADER PANEL1 PANEL1
PLEASE ENTER YOUR USERID: TEST
MSG: Please enter 8 character USERID
BMS Example
430 CICS TS for VSE/ESA: REXX Guide
Appendix K. Post-Installation Configuration
This appendix has a list of the steps to configure the REXX support.
Create the RFS Filepools
The REXX Filing System uses two or more filepools to store data. These are implemented as sets of
VSAM clusters. There is a skeleton sample job called CICVSAM.J in PRD1.BASE to define two filepools
for REXX. You should change this job to reflect your own environment as, for example, the dataset names.
When you have completed the changes, run the job to define the filepools.
Install Resource Definitions
Definitions for Profile, Program, Transaction and File resources for REXX, are in group CICREXX, which is
in the supplied or upgraded CSD.
You may make some changes to the resource definitions, for example you may want to change the name
of one or more of the provided transactions, and you probably need to change the dataset names
specified in the four file definitions to conform to those used when creating the RFS filepools.
Create a new group by copying CICREXX, and then make the changes to the new group.
When you have completed any changes, use CEDA to INSTALL the new group and add it to the
appropriate GRPLISTs ready for the next cold start.
Update LSRPOOL Definitions
Because the RFS files have a maximum key length of 252, and the supplied VSAM definitions use a
control interval size of 18K, it is important to check that the LSRPOOL used for the RFS supports these
values.
If you fail to do this, you will get an OPEN error on the system console with the message:
4228I FILE RFSxxxx OPEN ERROR X’DC’ (220)
Rename supplied Procedures
Supply the following input to LIBR to copy and rename the supplied EXECs (PROCs). Replace user.sublib
with a suitable sublibrary (for example, PRD2.CONFIG) in the LIBDEF PROC or LIBDEF * search chain
for the CICS initialization JCL.
CONNECT S=PRD1.BASE : user.sublib
COPY CICAUSER.Z:=.PROC R=Y
COPY CICCD.Z:=.PROC R=Y
COPY CICCLD.Z:=.PROC R=Y
COPY CICDEFT.Z:=.PROC R=Y
COPY CICDIR.Z:=.PROC R=Y
COPY CICEDIT.Z:=.PROC R=Y
COPY CICEMAP.Z:=.PROC R=Y
COPY CICEPROF.Z:=.PROC R=Y
COPY CICESVR.Z:=.PROC R=Y
COPY CICEXIO.Z:=.PROC R=Y
COPY CICFLST.Z:=.PROC R=Y
COPY CICFPOOL.Z:=.PROC R=Y
COPY CICFPROF.Z:=.PROC R=Y
COPY CICFSVR.Z:=.PROC R=Y
COPY CICGVER.Z:=.PROC R=Y
COPY CICGVERD.Z:=.PROC R=Y
COPY CICHELP.Z:=.PROC R=Y
© Copyright IBM Corp. 1992, 2010 431
COPY CICHPREP.Z:=.PROC R=Y
COPY CICIVP1.Z:=.PROC R=Y
COPY CICIVP2.Z:=.PROC R=Y
COPY CICIVP3.Z:=.PROC R=Y
COPY CICLCLIB.Z:=.PROC R=Y
COPY CICLELIB.Z:=.PROC R=Y
COPY CICLISTC.Z:=.PROC R=Y
COPY CICLISTP.Z:=.PROC R=Y
COPY CICLISTT.Z:=.PROC R=Y
COPY CICOVSIB.Z:=.PROC R=Y
COPY CICPATH.Z:=.PROC R=Y
COPY CICPSAMP.Z:=.PROC R=Y
COPY CICRXTRY.Z:=.PROC R=Y
COPY CICSET.Z:=.PROC R=Y
COPY CICSETS.Z:=.PROC R=Y
COPY CICSPROF.Z:=.PROC R=Y
COPY CICSTART.Z:=.PROC R=Y
COPY CICTRMID.Z:=.PROC R=Y
COPY CICXPROF.Z:=.PROC R=Y
Update CICSTART.PROC
Edit CICSTART.PROC from your chosen sublibrary (for example PRD2.CONFIG) using DITTO or another
editor to update the list of authorized user ids. If you fail to do this, the filepool formatting function gives
the message:
Subcommand return code = -4
Either change the existing 'AUTHUSER RCUSER' line or add additional lines specifying the userid that will
log on to format the pools, for example 'AUTHUSER CICSUSER' if no security is active, or 'AUTHUSER
SYSA' if userid SYSA is used. Use single apostrophes to delimit the command.
Two filepools are defined in the CICSTART.PROC. Change them to match changes to the supplied
CICREXX group. You can add additional filepools at a later date:
’FILEPOOL DEFINE POOL1 RFSDIR1 RFSPOL1 (USER’
IF RC ¬= 0 THEN EXIT RC
’FILEPOOL DEFINE POOL2 RFSDIR2 RFSPOL2 (USER’
IF RC ¬= 0 THEN EXIT RC
Update CICS Initialization JCL
REXX must be able to access sublibrary-resident EXECs through the search chain of either a LIBDEF
PROC or a LIBDEF * statement. Either add a LIBDEF statement, or modify an existing one to include the
sublibrary that contains the PROCs copied in the earlier step. You may now add the sublibraries that
contain the user EXECs, for example,
// LIBDEF PROC,SEARCH=(PRD2.CONFIG)
If you fail to make your chosen sublibraries available to resolve requests for executing the
sublibrary-resident execs, any REXX transaction will give the message:
CICREX490E Error 48 running CICSTART EXEC: Failure in system service
If the DSNAME and CATNAME parameters are removed from the supplied CSD file definitions for the
RFS, appropriate DLBL statements are required in the initialization JCL.
PI Configuration
432 CICS TS for VSE/ESA: REXX Guide
Format the RFS Filepools
Ensure that all required configuration tasks have been performed, and if necessary re-start CICS. Sign on
with a userid defined as an authorized user in CICSTART.PROC. Enter REXX (which is the default
transaction id associated with the CICRXTRY exec). You should see the following line at the top of the
screen:
Enter a REXX command or EXIT to quit
and a READ in the lower right hand corner. The cursor is in the lower left hand corner. You have now
entered the supplied exec which allows the execution of REXX and REXX/CICS commands interactively.
Now prepare the filepools for use by entering a command for every filepool that is defined in CICSTART:
'FILEPOOL FORMAT poolname
where poolname is substituted by the filepool name you specified in the CICSTART exec (the defaults are
POOL1 and POOL2).
Note: We recommend you to use either single or double apostrophes to delimit the REXX command.
The interactive environment echoes each command at the next available line on the screen and displays
any requested output.
The FILEPOOL FORMAT command does not display any information to indicate that it has successfully
completed, but the word READ appears in the lower right hand corner of the screen.
To determine whether the FILEPOOL FORMAT command worked successfully, enter SAY RC (without
apostrophes). If a 0is displayed on the next available line, the FILEPOOL FORMAT command was
successful.
Attempting to re-format a filepool gives the message:
Subcommand return code = 1836
This is also the return code displayed by SAY RC.
Continue this process until all RFS filepools are formatted. You only format the filepool when a new filepool
is defined, or if you delete and redefine the clusters for an existing filepool.
If you fill the screen while formatting the filepools or interactively executing REXX or REXX/CICS
commands and instructions, a MORE indicator appears at the bottom right hand corner. To clear the
screen, press the ENTER key. You may press the CLEAR key any time you want to clear the screen of
data. Press the PF3 key to exit from the interactive environment, this simulates entering the EXIT
instruction. You may also enter the EXIT instruction yourself (without apostrophes).
The interactive environment also allows recalling previously entered commands, by pressing the
RETRIEVE key. The system has a default setting for this key of PF12. Pressing the RETRIEVE key
causes the previously entered line to be re-displayed at the input location. You may then modify this area
and execute the instruction again by pressing ENTER. Pressing the RETRIEVE key multiple times
continues to bring the next previously entered command to the input area.
Create the Help Files
To create the help files, rename some modules using the following as sample LIBR input. Choose an
appropriate sublibrary (for example PRD2.CONFIG) to contain the renamed members:
PI Configuration
Appendix K. Post-Installation Configuration 433
CONNECT S=PRD1.BASE : user.sublib
COPY CICR3270.Y : CICR3270.BOOK
COPY CICINDEX.N : CICINDEX.PANSRC
COPY CICSNDX.N : CICSNDX.PANSRC
COPY CICCHAP.N : CICCHAP.PANSRC
Start CICS with at least EDSALIM=25M. Approximately 10M of free EDSA is needed to execute this
procedure, therefore allow this much extra over your normal configuration. CEMT I DSAS displays the
current usage, and can increase EDSALIM as long as partition getvis storage is available. The following
example shows EDSALIM=30M, and the four extended DSAs currently using 7MB, therefore there is
23MB free EDSA available.
I DSAS
STATUS: RESULTS - OVERTYPE TO MODIFY
Sosstatus(Notsos)
Dsalimit( 06291456 )
Cdsasize(00524288)
Rdsasize(00524288)
Sdsasize(00262144)
Udsasize(00000000)
Edsalimit( 0031457280 )
Ecdsasize(0002097152)
Erdsasize(0007340032)
Esdsasize(0001048576)
Eudsasize(0001048576)
Start the REXX transaction, then enter EXEC CICHPREP (without apostrophes) to run the exec that
creates the HELP text.
In response to the following messages, enter user.sublib where this is the sublibrary you chose (for
example, PRD2.CONFIG):
Please enter the Librarian sublibrary containing the REXX/CICS LIST3270.
(example: LIB.SUBLIB )
user.sublib
Please enter the Librarian sublibrary containing the help panels.
(example: LIB.SUBLIB )
user.sublib
You should see the following messages:
Building INDEX and CHAPTER files. Please be patient.
INDEX file built.
Building Chapter files
Chapter files are built
Building Appendix files.
Appendix files are built
34 Files built, all done !!
Verify the Installation
To verify that the installation has been successful, an exec has been supplied.
Execute the REXX transactionX environment used to format the filepools, enter CALL CICIVP1. The exec
indicates what should occur. Remember to press ENTER when MORE appears on the lower right hand
corner of the screen.
PI Configuration
434 CICS TS for VSE/ESA: REXX Guide
Sample output:
Enter a REXX command or EXIT to quit
CALL CICIVP1
***------------------------------------------------------***
*** This is a test REXX program running under CICS/VSE ***
*** It was loaded from PROCLIB-user.sublib(CICIVP1)
***------------------------------------------------------***
What is your name?
<type name and press ENTER>
Welcome to REXX/CICS for CICS/VSE , xxxxx
Invoking nested exec CICIVP2 (which has tracing on)
11 *-* say ’You entered CICIVP2 exec’
>>> "You entered CICIVP2 exec"
You entered CICIVP2 exec
12 *-* call CICIVP3
You entered CICIVP3 exec which has tracing off
13 *-* exit
Back to CICIVP1 exec
This is fullscreen output to terminal xxxx
Now input some data and press ENTER or a PF key
<type data and press ENTER>
The AID key that was pressed = ENTER
The cursor was at (Row Col): 24 5
The data that was entered (Row Col Data): 24 1 xxxxx
<press ENTER>
Example of more than one screen
1000 assignment statements have been executed
2000 assignment statements have been executed
3000 assignment statements have been executed
4000 assignment statements have been executed
5000 assignment statements have been executed
6000 assignment statements have been executed
7000 assignment statements have been executed
8000 assignment statements have been executed
9000 assignment statements have been executed
10000 assignment statements have been executed
11000 assignment statements have been executed
12000 assignment statements have been executed
13000 assignment statements have been executed
14000 assignment statements have been executed
15000 assignment statements have been executed
16000 assignment statements have been executed
17000 assignment statements have been executed
18000 assignment statements have been executed
19000 assignment statements have been executed
20000 assignment statements have been executed
<press ENTER to clear the "MORE">
Today’s date is dd mmm yyyy
The time is hh.mm.ss
REXX/CICS CICIVP1 is now finished
Configure the REXX DB2 Interface
This step is only required if the REXX EXECSQL command environment is enabled for DB2 support. DB2
must be fully installed before this step can be performed.
PI Configuration
Appendix K. Post-Installation Configuration 435
A package for the CICSQL program is loaded into the DB2 database under the SQLDBA user. This is
supplied as member CICSQL.A.
If you fail to do this, REXX gives return codes such as -805 whenever an "ADDRESS EXECSQL
command" is issued.
Adapt the following JCL and run DB2 in single user mode, substituting the correct password for user
SQLDBA. The default is SQLDBAPW but this is normally changed as part of the DB2 installation process.
// JOB RELOAD CICSQL PACKAGE
// LIBDEF *,SEARCH=(PRD2.DB2710,PRD1.BASE)
// EXEC PROC=ARIS71DB *-- STARTER DATABASE IDENTIFICATION
// EXEC PROC=ARISDBSD *-- RUN DB2 IN SINGLE-USER MODE
CONNECT SQLDBA IDENTIFIED BY password;
RELOAD PROGRAM (SQLDBA.CICSQL) REPLACE KEEP INFILE(SYSIPT BLKSZ(80)
PDEV(DASD));
READ MEMBER CICSQL
/*
COMMIT WORK;
/*
/&
Issue GRANT EXECUTE ON SQLDBA.CICSQL, as required, to enable users to run the package.
PI Configuration
436 CICS TS for VSE/ESA: REXX Guide
Bibliography
CICS Transaction Server for VSE/ESA Release 1 library
Publication name by area Publication number
Evaluation and planning
CICS TS for VSE/ESA Enhancements Guide GC34-5763
CICS TS for VSE/ESA Release Guide GC33-1645
CICS TS for VSE/ESA Migration Guide GC33-1646
CICS TS for VSE/ESA Report Controller Planning Guide GC33-1941
General
Master index SC33-1648
CICS TS for VSE/ESA Trace Entries SX33-6108
CICS TS for VSE/ESA User's Handbook SX33-6101
CICS TS for VSE/ESA Glossary (softcopy only) GC33-1649
Administration
CICS TS for VSE/ESA System Definition Guide SC33-1651
CICS TS for VSE/ESA Customization Guide SC33-1652
CICS TS for VSE/ESA Resource Definition Guide SC33-1653
CICS TS for VSE/ESA Operations and Utilities Guide SC33-1654
CICS TS for VSE/ESA CICS-Supplied Transactions SC33-1655
Programming
CICS TS for VSE/ESA Application Programming Guide SC33-1657
CICS TS for VSE/ESA Application Programming Reference SC33-1658
CICS TS for VSE/ESA Sample Applications Guide SC33-1713
CICS TS for VSE/ESA Application Migration Aid Guide SC33-1943
CICS TS for VSE/ESA System Programming Reference SC33-1659
CICS TS for VSE/ESA Distributed Transaction Programming Guide SC33-1661
CICS TS for VSE/ESA Front End Programming Interface User's Guide SC33-1662
CICS TS for VSE/ESA REXX Guide SC34-5764
Diagnosis
CICS TS for VSE/ESA Problem Determination Guide GC33-1663
CICS TS for VSE/ESA Messages and Codes (softcopy only) GC34-5561
Diagnosis Reference LY33-6085
Data Areas LY33-6086
Supplementary Data Areas LY33-6087
Communication
CICS TS for VSE/ESA Intercommunication Guide SC33-1665
CICS TS for VSE/ESA Internet Guide SC34-5765
CICS Family: Interproduct Communication SC33-0824
CICS Family: Communicating from CICS on System/390 SC33-1697
Special topics
CICS TS for VSE/ESA Recovery and Restart Guide SC33-1666
CICS TS for VSE/ESA Performance Guide SC33-1667
CICS TS for VSE/ESA Shared Data Tables Guide SC33-1668
CICS TS for VSE/ESA Security Guide SC33-1942
CICS TS for VSE/ESA External Interfaces Guide SC33-1669
CICS TS for VSE/ESA XRF Guide SC33-1671
© Copyright IBM Corp. 1992, 2010 437
Publication name by area Publication number
CICS TS for VSE/ESA Report Controller User's Guide SC34-5688
CICS Clients
CICS Clients: Administration SC33-1792
CICS Universal Clients Version 3 for OS/2: Administration SC34-5450
CICS Universal Clients Version 3 for Windows: Administration SC34-5449
CICS Universal Clients Version 3 for AIX: Administration SC34-5348
CICS Universal Clients Version 3 for Solaris: Administration SC34-5451
CICS Family: OO programming in C++ for CICS Clients SC33-1923
CICS Family: OO programming in BASIC for CICS Clients SC33-1671
CICS Family: Client/Server Programming SC33-1435
CICS Transaction Gateway Version 3: Administration SC34-5448
Where to Find More Information
You can find more information about CICS TS for VSE/ESA and REXX in the following publications:
vThe CICS Transaction Server for VSE/ESA Application Programming Reference, SC33-1658, is helpful
to programmers using CICS TS for VSE/ESA as it contains information about the application
programming commands.
vThe CICS Transaction Server for VSE/ESA System Programming Reference, SC33-1659, is helpful to
programmers using CICS TS for VSE/ESA as it contains information about the system programming
commands.
vThe REXX Language, A Practical Approach to Programming, by M. F. Cowlishaw (IBM* Order number:
ZB35-5100 and available in book stores) offers general information about the REXX language.
vThe SAA* CPI Common Programming Interface REXX Level 2 Reference, SC24-5549, may be useful to
more experienced REXX users who may wish to code portable programs.
vCICS Transaction Server for VSE/ESA CICS-Supplied Transactions, SC33-1686, contains information
about CEMT and CEDA.
vMVS/ESA SPV4 Assembler Programming Reference, GC28-1642.
Books from VSE/ESA 2.5 base program libraries
VSE/ESA Version 2 Release 5
Publication name Publication number
Administration SC33-6705
Diagnosis Tools SC33-6614
Extended Addressability SC33-6621
Guide for Solving Problems SC33-6710
Guide to System Functions SC33-6711
Installation SC33-6704
Licensed Program Specification GC33-6700
Messages and Codes Volume 1 SC33-6796
Messages and Codes Volume 2 SC33-6798
Messages and Codes Volume 3 SC33-6799
Networking Support SC33-6708
Operation SC33-6706
Planning SC33-6703
Programming and Workstation Guide SC33-6709
System Control Statements SC33-6713
System Macro Reference SC33-6716
438 CICS TS for VSE/ESA: REXX Guide
Publication name Publication number
System Macro User’s Guide SC33-6715
System Upgrade and Service SC33-6702
System Utilities SC33-6717
TCP/IP User's Guide SC33-6601
Turbo Dispatcher Guide and Reference SC33-6797
Unattended Node Support SC33-6712
High-Level Assembler Language (HLASM)
Publication name Publication number
General Information GC26-8261
Installation and Customization Guide SC26-8263
Language Reference SC26-8265
Programmer’s Guide SC26-8264
Language Environment for VSE/ESA (LE/VSE)
Publication name Publication number
C Run-Time Library Reference SC33-6689
C Run-Time Programming Guide SC33-6688
Concepts Guide GC33-6680
Debug Tool for VSE/ESA Fact Sheet GC26-8925
Debug Tool for VSE/ESA Installation and Customization Guide SC26-8798
Debug Tool for VSE/ESA User’s Guide and Reference SC26-8797
Debugging Guide and Run-Time Messages SC33-6681
Diagnosis Guide SC26-8060
Fact Sheet GC33-6679
Installation and Customization Guide SC33-6682
LE/VSE Enhancements SC33-6778
Licensed Program Specification GC33-6683
Programming Guide SC33-6684
Programming Reference SC33-6685
Run-Time Migration Guide SC33-6687
Writing Interlanguage Communication Applications SC33-6686
VSE/ICCF
Publication name Publication number
Administration and Operations SC33-6738
User’s Guide SC33-6739
VSE/POWER
Publication name Publication number
Administration and Operation SC33-6733
Application Programming SC33-6736
Networking Guide SC33-6735
Remote Job Entry User’s Guide SC33-6734
Bibliography 439
VSE/VSAM
Publication name Publication number
Commands SC33-6731
User’s Guide and Application Programming SC33-6732
VTAM for VSE/ESA
Publication name Publication number
Customization LY43-0063
Diagnosis LY43-0065
Data Areas LY43-0104
Messages and Codes SC31-6493
Migration Guide GC31-8072
Network Implementation Guide SC31-6494
Operation SC31-6495
Overview GC31-8114
Programming SC31-6496
Programming for LU6.2 SC31-6497
Release Guide GC31-8090
Resource Definition Reference SC31-6498
Books from VSE/ESA 2.5 optional program libraries
C for VSE/ESA (C/VSE)
Publication name Publication number
C Run-Time Library Reference SC33-6689
C Run-Time Programming Guide SC33-6688
Diagnosis Guide GC09-2426
Installation and Customization Guide GC09-2422
Language Reference SC09-2425
Licensed Program Specification GC09-2421
Migration Guide SC09-2423
User’s Guide SC09-2424
COBOL for VSE/ESA (COBOL/VSE)
Publication name Publication number
Debug Tool for VSE/ESA Fact Sheet GC26-8925
Debug Tool for VSE/ESA Installation and Customization Guide SC26-8798
Debug Tool for VSE/ESA User’s Guide and Reference SC26-8797
Diagnosis Guide SC26-8528
General Information GC26-8068
Installation and Customization Guide SC26-8071
Language Reference SC26-8073
Licensed Program Specifications GC26-8069
Migration Guide GC26-8070
Migrating VSE Applications To Advanced COBOL GC26-8349
Programming Guide SC26-8072
440 CICS TS for VSE/ESA: REXX Guide
DB2 Server for VSE
Publication name Publication number
Application Programming SC09-2393
Database Administration GC09-2389
Installation GC09-2391
Interactive SQL Guide and Reference SC09-2410
Operation SC09-2401
Overview GC08-2386
System Administration GC09-2406
DL/I VSE
Publication name Publication number
Application and Database Design SH24-5022
Application Programming: CALL and RQDLI Interface SH12-5411
Application Programming: High-Level Programming Interface SH24-5009
Database Administration SH24-5011
Diagnostic Guide SH24-5002
General Information GH20-1246
Guide for New Users SH24-5001
Interactive Resource Definition and Utilities SH24-5029
Library Guide and Master Index GH24-5008
Licensed Program Specifications GH24-5031
Low-level Code and Continuity Check Feature SH20-9046
Library Guide and Master Index GH24-5008
Messages and Codes SH12-5414
Recovery and Restart Guide SH24-5030
Reference Summary: CALL Program Interface SX24-5103
Reference Summary: System Programming SX24-5104
Reference Summary: HLPI Interface SX24-5120
Release Guide SC33-6211
PL/I for VSE/ESA (PL/I VSE)
Publication name Publication number
Compile Time Messages and Codes SC26-8059
Debug Tool For VSE/ESA User’s Guide and Reference SC26-8797
Diagnosis Guide SC26-8058
Installation and Customization Guide SC26-8057
Language Reference SC26-8054
Licensed Program Specifications GC26-8055
Migration Guide SC26-8056
Programming Guide SC26-8053
Reference Summary SX26-3836
Screen Definition Facility II (SDF II)
Publication name Publication number
VSE Administrator's Guide SH12-6311
VSE General Introduction SH12-6315
VSE Primer for CICS/BMS Programs SH12-6313
Bibliography 441
Publication name Publication number
VSE Run-Time Services SH12-6312
442 CICS TS for VSE/ESA: REXX Guide
Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the
products, services, or features discussed in this document in other countries. Consult your local IBM
representative for information on the products and services currently available in your area. Any reference
to an IBM product, program, or service is not intended to state or imply that only that IBM product,
program, or service may be used. Any functionally equivalent product, program, or service that does not
infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510 Japan
The following paragraph does not apply in the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore this statement may not apply to you.
This publication could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication. IBM
may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this one)
and (ii) the mutual use of the information which has been exchanged, should contact IBM United Kingdom
Laboratories, MP151, Hursley Park, Winchester, Hampshire, England, SO21 2JN. Such information may
be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Programming License Agreement, or
any equivalent agreement between us.
© Copyright IBM Corp. 1992, 2010 443
444 CICS TS for VSE/ESA: REXX Guide
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be
trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at
Copyright and trademark information at www.ibm.com/legal/copytrade.shtml.
Other company, product, and service names may be trademarks or service marks of others.
© Copyright IBM Corp. 1992, 2010 445
446 CICS TS for VSE/ESA: REXX Guide
Index
Special characters
! prefix on TRACE option 168
? prefix on TRACE option 167
/ (division operator) 21, 116, 218
// (remainder operator) 21, 116, 221
/= (not equal operator) 117
/== (strictly not equal operator) 117
.DEFINE verb 296, 297
.PANEL verb 299, 300
* (multiplication operator) 21, 116, 218
*-* tracing flag 168
** (power operator) 22, 116, 220
\ (NOT operator) 24, 26, 118
\> (not greater than operator) 24, 117
\>> (strictly not greater than operator) 118
\< (not less than operator) 24, 117
\<< (strictly not less than operator) 118
\= (not equal operator) 24, 117
\== (strictly not equal operator) 24, 117
% (integer division operator) 21, 116, 221
> (greater than operator) 24, 117
>.> tracing flag 169
>> (strictly greater than operator) 117
>>> tracing flag 169
>>= (strictly greater than or equal operator) 118
>< (greater than or less than operator) 24, 117
>= (greater than or equal operator) 24, 117
>C> tracing flag 169
>F> tracing flag 169
>L> tracing flag 29, 169
>O> tracing flag 29, 169
>P> tracing flag 169
>V> tracing flag 29, 169
< (less than operator) 24, 117
<> (less than or greater than operator) 117
<< (strictly less than operator) 117
<<= (strictly less than or equal operator) 118
<= (less than or equal operator) 24, 117
| (inclusive OR operator) 26, 118
|| (concatenation operator) 27, 116
& (AND logical operator) 26, 118
&& (exclusive OR operator) 26, 118
+ (addition operator) 21, 116, 218
+++ tracing flag 168
= (equal sign) 24
== (strictly equal operator) 24, 116, 117, 218
¬(NOT operator) 24, 118
¬> (not greater than operator) 117
¬>> (strictly not greater than operator) 118
¬< (not less than operator) 117
¬<< (strictly not less than operator) 118
¬= (not equal operator) 117
¬== (strictly not equal operator) 117
A
abuttal 27, 116
action taken when a condition is not trapped 226
action taken when a condition is trapped 226
active loops 147
additional operator examples 221
ADDRESS instruction 83, 285
example 10
address setting 133, 137
advanced topics in parsing 211
algebraic precedence 118
alphabetic character word options in TRACE 166
alphanumeric checking with DATATYPE 180
AND, logical operator 118
ANDing character strings together 176
ARBCHAR command 234
ARG instruction 15, 65, 74
ARG option of PARSE instruction 152
ARGS command 234
arithmetic 217
arithmetic operator
type of 21
associative storage 122
assumption, XEDIT 11
AUTH command 259, 418
AUTHUSER command 320, 417, 421, 422
automatic server initiation (ASI) 291
B
backslash, use of 114, 118
BACKWARD command 235
Base option of DATE function 181
basic mapping support (BMS) 128, 326
basic operator examples 220
BASSM assembler instruction 282
bits checked using DATATYPE 180
blank line 10
blanks, treatment of 75
block prefix commands 233
BMS example 427
BMSMAP1 exec 428
book
purpose xix
reference xix
user's guide xix
BOTTOM command 235
bottom of program reached during execution 143
BSM assembler instruction 282
business solutions 413
BY phrase of DO instruction 138
C
C2S command 282, 291, 331
CALL instruction 49, 59
CANCEL command 236, 249
© Copyright IBM Corp. 1992, 2010 447
CASE command 236, 242
CATMOUSE EXEC 91
CD command 127, 231, 258, 321, 339
CEDA command 105, 323
CEMT command 105, 324
Century option of DATE function 182
CHANGE command 237
checking arguments with ARG function 176
CICEPROF macro 241
CICGETV routine 284
CICPARMS control block 283
CICREX program 418
CICS 82
return codes 394
CICS commands 81
CICSECX1 security exit 418
CICSECX2 security exit 419
CICSLINK option on DEFCMD command 283
CICSLOAD option on DEFCMD command 282
CICSPROF exec 105, 421
CICSTART exec 105, 417, 418
CICXPROF macro 241
CKDIR command 260, 275
CKFILE command 260
clause
null 10
REXX types 9
CLD command 274, 325
client exec example 292
client/server 425
CMDLINE command 237
code page 110
codes and messages 379, 387
coding style 96
collating sequence using XRANGE 199
collections of variables 197
combining string and positional patterns 212
comma 76
command execution security 259
command level interpreter transaction (CECI) 421
commands
EDIT 81
RFS 81
RLS 81
COMPARE function 178
components
of REXX 4
CON EXEC (exercise) 90
conceptual overview of parsing 213
Configure the REXX DB2 Interface 435
Configuring REXX support 431
constant 20
constant symbols 121
content
user's guide 3
content addressable storage 122
control variable 39, 139
controlled loops 139
CONVTMAP command 326
COPY command 261
copying a string using COPIES 179
COPYR2S command 327
COPYS2R command 329
correcting your program 95
Create the Help Files 433
Create the RFS Filepools 431
CTLCHAR command 238
CURLINE command 238
current directory 258, 274
current terminal line width 188
D
date and version of the language processor 154
DB2 Interface 285
DBCJUSTIFY function 405
DBCS
characters 395
description 395
function handling 399
handling 395
names, using 10
processing functions 404
strings 395
support 395
default
variable 19
DEFCMD command 127, 281, 291, 332, 421, 422
defining
panels 296
definition
directory ID 257
file pool 257
of a function 51
root directory 257
subdirectory 257
DEFSCMD command 281, 335, 422
DEFTRNID command 338
DELETE command 261, 275
derived names of variables 122
description
REXX language 3
variable 19
destination prefix commands 233
DIGITS option of NUMERIC instruction 150, 218
DIR command 10, 339
directory ID 257, 273
DISKR command 261
DISKW command 257, 262
DISPLAY command 239
DO FOREVER loop 40
DO Loop 46
DO...END instruction 39
DOWN command 239
DPATH command 258
E
EDIT command 231, 240, 340
EDITSVR 82
engineering notation 223
equal sign in pattern 77
448 CICS TS for VSE/ESA: REXX Guide
equality, testing of 117
error 379, 387
debugging 29
ERROR 225
ERROR condition of SIGNAL and CALL
instructions 228
error messages 12
ETMODE 151
European option of DATE function 182
evaluation of expressions 115
example 244
ADDRESS instruction 10
AUTH 260
AUTHUSER command 320
C2S command 331
CD command 321
CEDA command 323
CEMT command 324
CKDIR 260, 275
CLD command 325
CONVTMAP command 326
COPY 261
COPYR2S command 328
COPYS2R command 330
current directory 258
debug aids 412
DEFCMD command 333
DEFSCMD command 336
DELETE 261, 275
DIR command 339
DISKR 262
DISKW 262
EDIT command 340
EXEC command 338
EXECDROP command 342
EXPORT command 349
FILEPOOL command 351
FLST command 268, 352
fully qualified file ID 257
GETDIR 263
GETVERS command 353
IMPORT command 355
JOIN command 245
LEFT command 245
LINEADD command 245
LISTCLIB command 357
LISTCMD command 356
LISTELIB command 358
LISTPOOL command 359
longer REXX program 6
LPREFIX command 246
LPULL 276
LPUSH 276
LQUEUE 277
MACRO command 246, 269
MKDIR 263, 277
MSGLINE command 247
NULLS command 247
NUMBERS command 248
PATH command 361
PFKEY command 248, 269
example (continued)
PFKLINE command 249
PSEUDO command 362
QQUIT command 249
QUERY command 250
QUIT command 250
RDIR 264
READ 278
RESERVED command 251
RESET command 251
RIGHT command 252
S2C command 373
sample panel 310
SAVE command 252
SCRNINFO command 368
simple REXX program 5
SORT command 253
SPLIT command 253
STRIP command 254
SYNONYM command 254
TERMID command 374
TOP command 254
TRUNC command 255
UP command 255
using DBCS names 11
VARDROP 278
VARGET 278
VARPUT 279
WAITREAD command 375
WAITREQ command 376
exception conditions saved during subroutine calls 136
exclusive OR operator 26, 118
exclusive-ORing character strings together 177
EXEC command 241, 341
exec identifier 10
EXECDB2 command environment 285
EXECDROP command 342
EXECIO command 344
EXECLOAD command 105, 346
EXECMAP command 348
EXECSQL command environment 285
EXECUTE command 272
exercise
calculating arithmetic expressions 23
comparison expressions 25
logical expressions 27
operators 29
TRACE instruction 30
writing a function 68
EXIT instruction 48, 59
EXPORT command 349
EXPOSE option of PROCEDURE instruction 155
exposed variable 155
expression
arithmetic 21
comparison 23
concatenation 27
definition 19
definitions 21
tracing 29
expressions 20
Index 449
EXTERNAL option of PARSE instruction 152
F
FAILURE condition of SIGNAL and CALL
instructions 225, 228
failure, definition 125
feature
of REXX 3
FIFO (first-in/first-out) stacking 160
file access security 259
FILE command 241
file list utility (FLST) 264
file name, type, mode of program 153
file pool 257
root directory 257
file system
commands 259
file type extension 126
FILEPOOL command 350, 418
FIND command 242
FIND function 185
flowchart 37
FLST command 352
FLSTSVR 82
FOR phrase of DO instruction 138
FOREVER repetitor on DO instruction 138
FORM function 185
FORM option of NUMERIC instruction 150, 223
Format the RFS Filepools 433
FORWARD command 243
free format 6
REXX instruction 6
fully qualified file ID 231
function
comparison to a subroutine 70
definition 51
protecting a variable 62
functions 171, 201
FUZZ function 187
G
general concepts 109, 125, 131
GET command 243
GETDIR command 262
GETLIB command 243
GETVERS command 353
greater than operator 117
greater than or equal operator (>=) 117
greater than or less than operator (><) 117
group, DO 138
grouping instructions to run repetitively 138
guard digit 218
H
HALT condition of SIGNAL and CALL instructions 225,
228
Halt Interpretation (HI) immediate command 411
halt, trapping 225
HELLO EXEC 11
HELP command 354
host command environment 82
hours calculated from midnight 194
how to use this book 103
I
identifying users 196
implied semicolons 114
IMPORT command 355
imprecise numeric comparison 222
inclusive OR operator 26, 118
incremental development methodology 413
indefinite loops 139
indentation during tracing 168
indirect evaluation of data 145
individual prefix commands 232
inequality, testing of 117
infinite loops 138
Information Management System (IMS) 425
input
preventing translation to uppercase 16
INPUT command 244
inserting a string into another 187
Install Resource Definitions 431
instruction
PROCEDURE 62
SAY 5
Instrumentation Facility Interface (IFI) 285
interactive debug 166, 411
interpretive execution of data 145
interrupt instructions 48
ITERATE instruction 41
J
JOIN command 244
Julian option of DATE function 182
justification, text right, RIGHT function 191
justifying text with JUSTIFY function 187
L
language support 415
LEAVE instruction 41, 47
leaving your program 143
LEFT command 245
less than operator (<) 117
less than or equal operator (<=) 117
less than or greater than operator (<>) 117
LIFO (last-in/first-out) stacking 159
line length and width of terminal 188
LINEADD command 245
LINEIN option of PARSE instruction 152
LISTCLIB command 357
LISTCMD command 356
LISTELIB command 358
LISTPOOL command 359
LISTTRNID command 360
literal string 6, 111
450 CICS TS for VSE/ESA: REXX Guide
LPREFIX command 246
LPULL command 275
LPUSH command 276
LQUEUE command 276
M
MACRO command 246
mapping between commands 319
master terminal transaction (CEMT) 3
messages
interpreting 12
minutes calculated from midnight 194
mixed DBCS string 181
MKDIR command 257, 263, 273, 277
Month option of DATE function 182
MSGLINE command 246
multi-way call 136, 164
multiple strings 78, 211
N
naming
variable 19
nested exec 425
nesting of control structures 137
nibbles 112
NOETMODE 151
NOEXMODE 151
Normal option of DATE function 182
not equal operator 117
not greater than operator 117
not less than operator 117
NOT operator 114, 118
NOTYPING flag cleared before error messages 379
NULLS command 247
NUMBERS command 247
O
OfficeVision/VM 425
operator 23
arithmetic 21
concatenation 27
Ordered option of DATE function 182
ORing character strings together 177
overflow, arithmetic 224
overlaying a string onto another 189
P
packing a string with X2C 200
pad character, definition 174
page, code 110
panel
definition 296
generation 301
input/output 301
object generator 296
PANEL command 302
parentheses 81
PARSE ARG instruction 74
PARSE instruction 127
PARSE PULL instruction 73
PARSE UPPER ARG instruction 74
PARSE UPPER PULL instruction 74
PARSE UPPER VALUE 74
PARSE UPPER VAR 75
PARSE VALUE...WITH 74
PARSE VAR 74
parsing 78
description 203
into words 75
PARSE ARG 74
PARSE UPPER ARG 74
parsing case 212
parsing instructions 210
passing
arguments 16
information 60
PATH command 127, 258, 321, 361, 417
pattern in parsing 76
permanent command destination change 132
PFKEY command 248
PFKLINE command 248
placeholder 75
placeholder in parsing 15, 75
Post-Installation Configuration 431
powers of ten in numbers 113
precedence of operators 118
precision of arithmetic 218
predefined variables 285, 287
preface xix
presumed command destinations 132
PROCEDURE instruction 62, 64
program
configuration 5
description 5
error message 12
example 6
passing information to 14
receiving input 15
writing 6
program identifier 5, 109
program load table (PLT) 418
protecting variables 155
prototyping development methodology 413
PSEUDO command 362
pseudo random number function of RANDOM 190
PULL instruction 12, 14, 73, 127
PULL option of PARSE instruction 153
purpose
of this book xix
reference xix
user's guide xix
Q
QQUIT command 249, 250
QUERY command 249
querying TRACE setting 195
Index 451
QUIT command 250
quotation marks
around a literal string 6
in an instruction 6
R
random number function of RANDOM 190
RDIR command 263
READ command 277
recursive call 136
reference 103
relative numeric pattern in parsing 77
relative positional patterns 207
RENAME command 264
Rename supplied Procedures 431
reordering data with TRANSLATE function 195
repeating a string with COPIES 179
repetitive loops 39
reservation of keywords 409
RESERVED command 250, 265
RESET command 251
resetting command environment 319
resource definition online (RDO) 427
resource definition online transaction (CEDA) 3
restoring variables 142
return codes 387
RETURN instruction 49, 59
REXX
clauses 9
components 4
REXX instruction 6
formatting 6
PROCEDURE 62
PULL 14
syntax 6
REXX language
description 3
feature of 3
REXX program identifier 5, 10, 109
REXX programming
example 6
under CICS 3
writing 6
REXX programs
expressions 19
operators 19
variables 19
REXX/CICS 387
REXX/CICS Command Definition Facility 281, 285
REXX/CICS commands 319
REXX/CICS File System (RFS) 126, 257
REXX/CICS List System (RLS) 273
REXX/CICS Panel Facility 295
REXX/CICS Text Editor 126, 231
REXXCICS 82
RFS 83
RFS command 257, 363, 418
RIGHT command 251
RLS 83
root directory 257, 273
ROTATE EXEC 96
rules
syntax 6
running
REXX programs 5
S
S2C command 282, 291, 373
SAA 104
SAVE command 252
SAY instruction 5, 12, 127
SBCS strings 395
scientific notation 223
SCRNINFO command 368
searching a string for a phrase 185
seconds calculated from midnight 194
secure
file access 259
security 259, 274, 421
SELECT WHEN...OTHERWISE...END 37
selecting a default with ABBREV function 175
sequence, collating using XRANGE 199
set buffer address (SBA) 201
SET command 369
SETSYS command 371, 418
shift-in (SI) characters 395
Shift-in (SI) characters 400
shift-out (SO) characters 395
Shift-out (SO) characters 400
SIGNAL instruction 50
SIGNAL ON ERROR instruction 86
significant digits in arithmetic 218
SORT command 252
SOURCE option of PARSE instruction 153
spacing, formatting, SPACE function 192
special case 212
SPLIT command 253
SQL Communications Area (SQLCA) 288
SQL statements 81
Standard option of DATE function 182
statements
SQL 81
strict comparison 117
strictly equal operator 117
strictly greater than operator 117
strictly greater than or equal operator 118
strictly less than operator 117
strictly less than or equal operator 118
strictly not equal operator 117
strictly not greater than operator 118
strictly not less than operator 118
string 20
DBCS 395
string and positional patterns 212
string parsing 211
string pattern in parsing 76
STRIP command 253
structure and syntax 109
style, coding 96
subdirectory 257, 273
452 CICS TS for VSE/ESA: REXX Guide
subexpression 115
subkeyword 120
subroutine
comparison to a function 57, 70
description 57
protecting variable 62
writing 58
subsidiary list 142, 155
SUBSTR 193
substring 193
suggested readings xix
symbols and strings in DBCS 396
SYNONYM command 254
syntax 387
rules of REXX 6
SYNTAX condition of SIGNAL instruction 226, 228
SYSSBA command 201
system libraries 422
systems administrator 421
T
tail 122
template 75
parsing 75
templates containing positional patterns 206
temporary command destination change 132
temporary storage queue (TSQ) 344
ten, powers of 223
TERMID command 129, 374
terms and data 115
text editor 231
text spacing 192
tips, tracing 168
TO phrase of DO instruction 138
TOP command 254
trace
trace operation 29
Trace End (TE) immediate command 411
TRACE instruction 85, 127
Trace Start (TS) immediate command 411
traceback, on syntax error 169
tracing results 30
tracing tips 168
transaction identifier 231, 421
TRUNC command 254
truncating numbers 196
type of data checking with DATATYPE 180
typing in a program 11
U
unassigning variables 142
unconditionally leaving your program 143
underflow, arithmetic 224
uninitialized variable 121
UNTIL phrase of DO instruction 138
unusual change in flow of control 225
UP command 255
Update CICS Initialization JCL 432
Update CICSTART.PROC 432
Update LSRPOOL Definitions 431
Usa option of DATE function 182
user's guide 3, 99
USERS directory 257, 273
users, identifying 196
using a period as a placeholder 75
V
value of variable, getting with VALUE 196
VALUE option of PARSE instruction 153
VAR option of PARSE instruction 153
VARDROP command 278
VARGET command 278
variable
definition 19
description 19
names 19
type of value 20
value 20
variable string pattern in parsing 76
VARPUT command 279
verbs
DEFINE 296
PANEL 299
Verify the Installation 434
verifying contents of a string 197
VERSION option of PARSE instruction 154
W
WAITREAD command 375
WAITREQ command 282, 291, 376
warning, STORAGE function 201
Weekday option of DATE function 182
what this book is about xix
where to find more information 438
WHILE phrase of DO instruction 138
who this book is for xix
word from a string 198
WRITE command 273, 279
writing
REXX programs 5
X
XOR, logical 118
XORing character strings together 177
Y
you should know xix
Index 453
454 CICS TS for VSE/ESA: REXX Guide
Sending your comments to IBM
If you especially like or dislike anything about this book, please use one of the methods listed below to
send your comments to IBM.
Feel free to comment on what you regard as specific errors or omissions, and on the accuracy,
organization, subject matter, or completeness of this book.
Please limit your comments to the information in this book and the way in which the information is
presented.
To ask questions, make comments about the functions of IBM products or systems, or to request
additional publications, contact your IBM representative or your IBM authorized remarketer.
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.
You can send your comments to IBM in any of the following ways:
vBy mail, to this address:
IBM United Kingdom Limited
User Technologies Department (MP095)
Hursley Park
Winchester
Hampshire
SO21 2JN
United Kingdom
vBy fax:
– From outside the U.K., after your international access code use 44–1962–816151
– From within the U.K., use 01962–816151
vElectronically, use the appropriate network ID:
– IBMLink: HURSLEY(IDRCF)
– Internet: idrcf@hursley.ibm.com
Whichever you use, ensure that you include:
vThe publication title and order number
vThe topic to which your comment applies
vYour name and address/telephone number/fax number/network ID.
© Copyright IBM Corp. 1992, 2010 455
456 CICS TS for VSE/ESA: REXX Guide

SC34-5764-01
Spine information:
 CICS TS for VSE/ESA REXX Guide

Navigation menu