IBM SC34-5764-01 User Manual
CICS Transaction Server fo r VSE/ESA
REXX Guide
SC34-5764-01
CICS Transaction Server fo r 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.
Second edition (September 2000)
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, 2009.
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 ...............................17
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, 2009 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 ..............................54
String Manipulating Functions ...........................54
Miscellaneous Functions .............................55
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 ...............................122
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 ..............................127
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 .....................129
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) ...........................183
D2X (Decimal to Hexadecimal) ..........................184
ERRORTEXT ................................184
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) ...............................188
MIN (Minimum) ................................189
Contents vii
OVERLAY..................................189
POS (Position) ................................189
QUEUED ..................................190
RANDOM ..................................190
REVERSE .................................191
RIGHT ...................................191
SIGN ...................................191
SOURCELINE ................................191
SPACE...................................191
STORAGE .................................192
STRIP ...................................192
SUBSTR (Substring) ..............................192
SUBWORD .................................193
SYMBOL ..................................193
TIME ...................................193
TRACE...................................195
TRANSLATE.................................195
TRUNC (Truncate) ..............................195
USERID ..................................196
VALUE ...................................196
VERIFY ..................................197
WORD ...................................197
WORDINDEX ................................198
WORDLENGTH ...............................198
WORDPOS (Word Position) ...........................198
WORDS ..................................198
XRANGE (Hexadecimal Range)..........................198
X2B (Hexadecimal to Binary) ...........................199
X2C (Hexadecimal to Character) .........................199
X2D (Hexadecimal to Decimal) ..........................199
External Functions Provided in REXX/CICS ......................200
STORAGE .................................200
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 ..........................213
Details of Steps in Parsing ...........................213
Chapter 16. Numbers and Arithmetic ........................217
Introduction ..................................217
Definition ...................................218
Numbers ..................................218
Precision
Arithmetic Operators ..............................218
Arithmetic Operation Rules—Basic Operators.....................219
..................................218
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 .................................251
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
x CICS TS for VSE/ESA: REXX Guide
Security ...................................274
RLS commands ................................275
CKDIR ...................................275
DELETE ..................................275
LPULL ...................................275
LPUSH ...................................276
LQUEUE ..................................277
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
C2S.....................................331
Operands ..................................331
Return Codes ................................331
...................................330
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
....................................365
Note
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 ..................................390
LISTCLIB and LISTELIB .............................391
GETVERS ..................................391
COPYR2S ..................................391
COPYS2R ..................................391
Contents xv
LISTPOOL ..................................391
LISTTRNID ..................................392
C2S.....................................392
PSEUDO ...................................392
AUTHUSER ..................................392
SETSYS ...................................392
S2C.....................................392
TERMID ...................................392
WAITREAD ..................................392
WAITREQ...................................393
EXEC ....................................393
CEDA and CEMT ................................393
EXECIO ...................................393
CONVTMAP ..................................393
SCRNINFO ..................................393
CICS ....................................393
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 Exit ..................................418
CICSECX2 .................................418
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 .................................439
VTAM for VSE/ESA ..............................439
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 ..............................440
DL/I VSE ..................................441
PL/I for VSE/ESA (PL/I VSE)
...........................441
Contents xvii
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, 2009 xix
xx CICS TS for VSE/ESA: REXX Guide
Part 1. User's Guide
© Copyright IBM Corp. 1992, 2009 1
2 CICS 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, 2009 3
Introduction
Components of REXX
The various components of REXX make it a powerful tool for programmers. REXX is made up of:
v Clauses, 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.
v Built-in functions — These functions are built into the language processor and provide convenient
processing options.
v External functions — REXX/CICS provides these functions that interact with the system to do specific
tasks for REXX.
v Data stack functions — A data stack can store data for I/O and other types of processing.
4
CICS 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.
/* Sample REXX Program */
SAY 'Hello world!'
Figure 1. Example of a Simple Program
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:
© Copyright IBM Corp. 1992, 2009 5
Writing and Running a REXX Program
/**************************** 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
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.
6
CICS TS for VSE/ESA: REXX Guide
Writing and Running a REXX Program
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.'
Chapter 2. Writing and Running a REXX Program 7
Writing and Running a REXX Program
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.
/************************* 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
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.
8
CICS TS for VSE/ESA: REXX Guide
Loading...