REXXTOOLS V7 Basic Services

REXXTOOLS/MVS TM
Basic Services Manual

Version 7 Release 1
Open Software Technologies, Inc.

REXXTOOLS/MVS Version 7 Release 1 Modification Level 1
This document is an unpublished work fully protected under United States and
International copyright law. Permission is hereby granted to licensed users of
REXXTOOLS/MVS to make a limited number of copies of this document for distribution
and use within their organizations. No copies may be made for any other reason, nor may
this document or any part of it be reproduced or distributed for any other purpose without
the permission of Open Software Technologies, Inc.
IBM, MVS/ESA, MVS/XA, MVS/DFPR, NetView, CICS, DB2, MVS/SP, DFS/MVS,

VSE/ESA, VM/ESA, RACF, OS/390, z/OS, and CICS/ESA, are either trademarks or
registered trademarks of International Business Machines Corporation in the United
States, other countries, or both. Other company, product, or service names may be
trademarks or service marks of others.
© Copyright 2005 by Open Software Technologies, Inc. All rights reserved.
Open
Software
Technologies, Inc.
P.O. Box 162652

Altamonte Springs, FL
32716-2652
Phone: (407) 788-7173

Fax: (407) 788-8494
E-mail: support@mail.open-softech.com
Web: www.open-softech.com
REXXTOOLS/MVS Basic Services User’s Guide

Table of Contents
Introduction.................................................................................................................................... 1
Who This Document is For .............................................................................................................. 1
What REXXTOOLS/MVS Basic Services Is.................................................................................... 1
Why You Need REXXTOOLS/MVS................................................................................................. 2
Related Publications........................................................................................................................ 3
Trademarks...................................................................................................................................... 4
What’s New in Version 7 Release 1 ................................................................................................ 4
What's New in Version 6 Release 1 ................................................................................................ 5
What's New in Version 5 Release 1 ................................................................................................ 6
What's New in Version 4 Release 1 Mod 2 ..................................................................................... 8
What's New in Version 4 Release 1 .............................................................................................. 10
What's New in Version 2 Release 1 Mod 2 ................................................................................... 11
How to Use REXXTOOLS/MVS ................................................................................................... 15
Notational Conventions ................................................................................................................. 15
REXXTOOLS/MVS Environments................................................................................................. 16
Using REXXTOOLS/MVS Functions ............................................................................................. 16
Using the CALL Instruction ................................................................................................... 17
Using REXX Variables for Arguments .................................................................................. 17
Coding Option Strings........................................................................................................... 17
Using REXXTOOLS/MVS Host Commands.................................................................................. 18
Special REXXTOOLS/MVS Variables ........................................................................................... 19
Running REXX Programs.............................................................................................................. 20
Running REXX Programs Under TSO.................................................................................. 20
Running REXX Programs Under ISPF ................................................................................. 21
Running REXX Programs in the Background ....................................................................... 22
Running REXX Programs Under Automation Packages ...................................................... 23
Running REXX Programs Under HTTP Server .................................................................... 23
Running REXX Programs Under APPC/MVS....................................................................... 23
Technical Support.......................................................................................................................... 24
Common Problems and Resolutions .................................................................................... 24
QSAM Functions.......................................................................................................................... 27
Getting Started............................................................................................................................... 27
QSAM Basics................................................................................................................................. 27
Physical Sequential............................................................................................................... 27
Partitioned/Partitioned Extended .......................................................................................... 28
SYSIN/SYSOUT ................................................................................................................... 28
Record Formats ............................................................................................................................. 29
Programming For QSAM ............................................................................................................... 30
Allocating Data Sets ...................................................................................................................... 31
Opening and Closing Data Sets .................................................................................................... 31
OPEN Options ...................................................................................................................... 32
Reading, Writing, and Updating Records ...................................................................................... 32
Input Processing ................................................................................................................... 33
Output Processing ................................................................................................................ 33
Update Processing................................................................................................................ 34
QSAM Return Codes..................................................................................................................... 34
Service Descriptions...................................................................................................................... 35
CLOSE (QSAM).................................................................................................................... 35
GET (QSAM)......................................................................................................................... 36
OPEN (QSAM)...................................................................................................................... 37
PUT (QSAM)......................................................................................................................... 39
BPAM Functions .......................................................................................................................... 41
Getting Started............................................................................................................................... 41
BPAM Basics ................................................................................................................................. 41
Record Formats ............................................................................................................................. 42
Programming For BPAM ............................................................................................................... 43
Allocating Data Sets ...................................................................................................................... 44
Opening and Closing Data Sets .................................................................................................... 44
OPEN Options ...................................................................................................................... 45
Input Processing ................................................................................................................... 46
Output Processing ................................................................................................................ 46
Update Processing................................................................................................................ 47
Extend Processing ................................................................................................................ 48
Sharing PDSE Members ............................................................................................................... 48
Sharing PDS Members.................................................................................................................. 49
BPAM Return Codes ..................................................................................................................... 51
CLOSE (BPAM) .................................................................................................................... 52
FINDM (BPAM) ..................................................................................................................... 53
GET (BPAM) ......................................................................................................................... 57
OPEN (BPAM) ...................................................................................................................... 58
PUT (BPAM) ......................................................................................................................... 60
STOWM (BPAM)................................................................................................................... 62
VSAM Functions .......................................................................................................................... 67
Getting Started............................................................................................................................... 67
VSAM Basics ................................................................................................................................. 67
Programming For VSAM ............................................................................................................... 69
Allocating VSAM Files ................................................................................................................... 69
Opening and Closing VSAM Files ................................................................................................. 69
OPEN (ACB) Options............................................................................................................ 71
Request Parameter List (RPL) Options ................................................................................ 73
Sequential Processing .......................................................................................................... 76
Direct Processing.................................................................................................................. 77
Sharing VSAM Data sets............................................................................................................... 78
How VSAM I/O Works........................................................................................................... 78
VSAM Serialization Methods ................................................................................................ 79
Serialization Precedence ...................................................................................................... 81
Serialization Problems .......................................................................................................... 81
The "Dirty Read" Technique ................................................................................................. 81
VSAM Return Codes ..................................................................................................................... 82
CLOSE (VSAM) .................................................................................................................... 83
ENDREQ (VSAM) ................................................................................................................. 85
ERASE (VSAM) .................................................................................................................... 87
GET (VSAM) ......................................................................................................................... 88
OPEN (VSAM) ...................................................................................................................... 91
POINT (VSAM) ..................................................................................................................... 94
PUT (VSAM) ......................................................................................................................... 96
VERIFYV (VSAM) ................................................................................................................. 99
IDCAMS....................................................................................................................................... 101
Address IDCAMS......................................................................................................................... 101
IDCAMS Functions ...................................................................................................................... 103

IDCAMS Return Codes ............................................................................................................... 104
Service Descriptions.................................................................................................................... 105
ADDRESS IDCAMS............................................................................................................ 105
DSNDEL (Data Set Delete)................................................................................................. 108
LISTC (List Catalog) ........................................................................................................... 110
Data Set Information Functions ............................................................................................... 115
Introduction .................................................................................................................................. 115
Specifying Data Set Names......................................................................................................... 116
Using Pattern Matching ............................................................................................................... 117
Examples: ........................................................................................................................... 117
Parsing Returned Values............................................................................................................. 118
String Parsing ..................................................................................................................... 118
Stack and Stem Parsing ..................................................................................................... 119
Using the Period Placeholder ............................................................................................. 119
DSORG, Status, and Disposition................................................................................................. 120
DSORG ............................................................................................................................... 120
Status .................................................................................................................................. 120
Disposition .......................................................................................................................... 120
Required Reading and Examples................................................................................................ 121
Return Codes and Messages ...................................................................................................... 121
DDNINFO............................................................................................................................ 123
DSNINFO (Data Set Information) ....................................................................................... 126
LISTA (List Allocations)....................................................................................................... 131
LISTM.................................................................................................................................. 134
MVS Supervisor Services ......................................................................................................... 139
Environmental Issues .................................................................................................................. 139
Virtual Storage Management....................................................................................................... 139
Resource Control......................................................................................................................... 140
Security........................................................................................................................................ 140
Operator Communication ............................................................................................................ 141
Specifying Routing Codes................................................................................................... 142
Specifying Descriptor Codes .............................................................................................. 143
DEQ .................................................................................................................................... 144
DOM.................................................................................................................................... 146
ENQ .................................................................................................................................... 147
FREEMAIN ......................................................................................................................... 150
GETMAIN............................................................................................................................ 152
POST .................................................................................................................................. 154
RACROUTE........................................................................................................................ 155
WAIT ................................................................................................................................... 158
WTL (Write-To-Log) ............................................................................................................ 160
WTO (Write-To-Operator) ................................................................................................... 161
WTOR (Write-To-Operator-with-Reply) .............................................................................. 163
TSO Services.............................................................................................................................. 165
Writing and Reading Line Mode Messages................................................................................. 165
Using Full-Screen I/O .................................................................................................................. 165
SBA (Set Buffer Address) ................................................................................................... 166
TGET................................................................................................................................... 167
TPUT................................................................................................................................... 170
General REXX Extensions ........................................................................................................ 175
ADDRESS REXX................................................................................................................ 176
ADDRESS REXXTOOL ...................................................................................................... 177
D2F ..................................................................................................................................... 179
D2P ..................................................................................................................................... 180
D2PIC.................................................................................................................................. 182
Picture String Symbols:....................................................................................................... 183
Simple Insertion Editing: ..................................................................................................... 185
Decimal Point Editing:......................................................................................................... 185
Fixed Insertion Editing: ....................................................................................................... 185
Floating Insertion Editing: ................................................................................................... 186
Zero Suppression and Replacement Editing: ..................................................................... 187
F2D ..................................................................................................................................... 190
MATCH ............................................................................................................................... 191
OPTIONS Command .......................................................................................................... 193
P2D (Packed-to-Decimal) ................................................................................................... 194
PARSETOK (Parse Tokens)............................................................................................... 196
PIC2D (Picture-to-Decimal) ................................................................................................ 199
QWIKREF ........................................................................................................................... 200
RXFUNC ............................................................................................................................. 203
RXSUBCOM ....................................................................................................................... 207
RXTTERM (Terminate REXXTOOLS)................................................................................ 211
STEMDISP (Stem Display) ................................................................................................. 213
STEMSORT ........................................................................................................................ 215
STORAGEX ........................................................................................................................ 218
VERASE Command............................................................................................................ 221
VGET Command................................................................................................................. 223
VPUT Command................................................................................................................. 225
WORDSORT....................................................................................................................... 227
Dynamic Allocation ................................................................................................................... 229
Introduction .................................................................................................................................. 229
Differences from TSO/E Dynamic Allocation............................................................................... 230
High-Level Language Support..................................................................................................... 231
ALLOCATE Command........................................................................................................ 232
FREE Command................................................................................................................. 243
RXTDAIR (COBOL) Subroutine.......................................................................................... 246
The Interpretive Compiler ......................................................................................................... 251
Why Compile? ............................................................................................................................. 251
The Compilation Process ............................................................................................................ 252
Running Compiled Programs ...................................................................................................... 253
How a Compiled Program is Found.................................................................................... 253
How to Call a Compiled Program ....................................................................................... 254
Alternative Invocation Methods........................................................................................... 255
Compiler Options ......................................................................................................................... 258
Compiler Data sets ...................................................................................................................... 260
Linking Compiled REXX Programs.............................................................................................. 260
Using PUNCH Cards .......................................................................................................... 261
Syntax Checking.......................................................................................................................... 261
Compiler Listings ......................................................................................................................... 261
Controlling the Listing ......................................................................................................... 262
Optimizing Performance .............................................................................................................. 262
Function Packages ............................................................................................................. 263
Link Pack Area.................................................................................................................... 263
RXC TSO Command .......................................................................................................... 264

RXTCL Batch Procedure .................................................................................................... 265
CICS External Interface............................................................................................................. 267
REXCI Call Types........................................................................................................................ 267
Initialize_User ..................................................................................................................... 268
Allocate_Pipe ...................................................................................................................... 268
Open_Pipe .......................................................................................................................... 268
DPL_Request...................................................................................................................... 268
Close_Pipe.......................................................................................................................... 269
Deallocate_Pipe.................................................................................................................. 269
Running EXCI Execs ................................................................................................................... 269
REXX External Writer Facility................................................................................................... 271
Overview...................................................................................................................................... 271
Functions ..................................................................................................................................... 271
Structure of a Writer .................................................................................................................... 272
Security Issues ............................................................................................................................ 273
REXX MQSERIES Interface....................................................................................................... 275
Design Philosophy....................................................................................................................... 275
Functions ..................................................................................................................................... 275
A Word about Stems ................................................................................................................... 276
Putting Messages ........................................................................................................................ 276
Getting Messages........................................................................................................................ 276
Inquiring about Attributes............................................................................................................. 277
Setting Attributes ......................................................................................................................... 277
Appendix A: Working with Record Fields............................................................................... 279
Parsing Records With REXX ....................................................................................................... 279
PARSE VAR ....................................................................................................................... 280
PARSE VALUE ................................................................................................................... 280
Basic Parsing ...................................................................................................................... 281
Advanced Parsing Problems............................................................................................... 282
Building Records With REXX ...................................................................................................... 284
Advanced Record Building ................................................................................................. 284
A Simple Methodology for Sharing Record Definitions ............................................................... 285
Self-defining VSAM Files .................................................................................................... 286
Appendix B: REXX Development Tools .................................................................................. 287
CC (Concatenate Command) ...................................................................................................... 287
DCC (Deconcatenate Command)................................................................................................ 287
DDL (DDNAME List Command) .................................................................................................. 288
DDS (DDNAME Scan Command) ............................................................................................... 288
LLS (Link List Scan Command)................................................................................................... 288
OSENVIR (Display OS Environment).......................................................................................... 289
RF (Edit Macro) ........................................................................................................................... 289
RL (REXX Listing Program)......................................................................................................... 290
RXTDFUNC (Display Functions Command) ............................................................................... 290
RXTDHOST (Display Host Command Environments Command)............................................... 290
RXTDRXTE (Display REXXTOOLS Environment Command).................................................... 291
RXTLJPQ (List Job Pack Queue Command) .............................................................................. 291
RXTLLLE (List Load List Elements Command)........................................................................... 291
RXTTCBT (TCB Tree Command) ............................................................................................... 291
Appendix C: Messages ............................................................................................................. 293
General ........................................................................................................................................ 293
Batch Compiler (RXTCOMP)....................................................................................................... 293
Run-Time Module (RXTRXPRE) ................................................................................................. 294
RXC TSO Command ................................................................................................................... 295
STORAGEX Function (RXTSTORX)........................................................................................... 295
REXX Module Load (RXTCRRLD) .............................................................................................. 296
RXFUNC (RXTFUNC) ................................................................................................................. 296
EXECSQL Command .................................................................................................................. 296
QSAM, BPAM, and VSAM Interfaces.......................................................................................... 297
Static SQL.................................................................................................................................... 298
Dynamic SQL............................................................................................................................... 298
Dynamic Allocation ...................................................................................................................... 302
Internal......................................................................................................................................... 302
RXTWTR ..................................................................................................................................... 303
RXTAMT (APPC/MVS Transaction Program) ............................................................................. 303
Glossary ..................................................................................................................................... 305

Introduction
Who This Document is For
This document describes the function and use of REXXTOOLS/MVS Basic Services. Any
REXX programmer, whether a novice or experienced, can benefit from using
REXXTOOLS. However, at least some familiarity with the REXX programming language
is required. If you are very new to the REXX programming language, you may want to
read and try some of the exercises in TSO/E Version 2 REXX/MVS User's Guide, SC28-
1882 prior to using REXXTOOLS.
What REXXTOOLS/MVS Basic Services Is

REXXTOOLS/MVS Basic Services is a collection of programming interfaces that
augments the base functionality of REXX/MVS. REXXTOLS contains functions,
subroutines, and host command environments that provide:
• access to VSAM, sequential, and partitioned data sets.
• access to MVS/ESA and OS/390 operating system services.
• access to SMS and DFP information.
• general enhancements to REXX data conversion, string manipulation, array handling,

and global variables.
In addition, REXXTOOLS/MVS Basic Services includes a pseudo-compiler for converting

REXX programs into load modules. Compiled programs take up less space, execute
faster (in some cases), and are more secure from unauthorized browsing and editing.
Introduction 1
Why You Need REXXTOOLS/MVS
REXXTOOLS/MVS expands the range of system services available to the REXX
programmer, and provides extensions to REXX that make programming easier than ever.
Using REXXTOOLS/MVS you can construct sophisticated applications which previously
could only be written in assembler, PL/I, or COBOL.
REXX and REXXTOOLS/MVS can be used to perform many common programming

tasks quickly and easily. You can, for example, use REXXTOOLS to:
Create ISPF REXX and REXXTOOLS are fully integrated into ISPF.
Applications. REXXTOOLS lets you build applications to display and share
VSAM and DB2-hosted data in hours instead of weeks.
Create REXXTOOLS can be used in client/server environments such

Client/Server as APPC/MVS, IBM TCP/IP, and DB2's Distributed and
Applications. Remote Units of Work.
Create Web-based REXXTOOLS has been tested in several popular MVS web
Applications. servers, including IBM's HTTP Server.
Create Custom Many customers have found that REXXTOOLS can be used to
Utilities. augment and in some cases replace expensive IBM and ISV-
supplied utilities. In particular, DB2 report writing using the
REXXTOOLS dynamic SQL interface is in most cases easier,
and significantly outperforms equivalent IBM utilities.
Create System REXXTOOLS is used in conjunction with MVS automation

Automation packages to develop robust applications. Automated trouble
Applications. ticketing, exception logging, and data sharing applications
have been developed using REXXTOOLS.
Write Batch Using the REXX batch interface, IRXJCL, you can quickly
Reports. produce ad hoc and production reporting job streams. The
REXXTOOLS currency formatting routine, D2PIC, gives you
the same support for number formatting as is available in
COBOL.
Post Process Often the source to older report writing programs has been lost
Reports. or simply is too difficult to modify. Using REXX and
REXXTOOLS, you can quickly construct programs to read
report files and make the necessary modifications.
Convert data from REXXTOOLS contains many conversion functions and access
one format to methods that allow you to create custom conversion utilities.
another. For example, you can use REXXTOOLS to convert 2 byte
packed date fields to 4 byte packed fields, or to binary.
2 REXXTOOLS/MVS Basic Services User’s Guide

Related Publications
The REXXTOOLS/MVS publications are:
• REXXTOOLS/MVS General Information

• REXXTOOLS/MVS Installation Guide
• REXXTOOLS/MVS Basic Services User's Guide
• REXXTOOLS/MVS DB2/SQL Services User's Guide
REXXTOOLS/MVS documentation is available in a variety of formats, electronic and

hardcopy. Consult your distributor or Open Software Technologies for more information.
For information related to the REXX language (the REXX/MVS implementation), refer to
the following IBM publications:
Publication Title Order Number

TSO/E Version 2 REXX/MVS User's Guide SC28-1882
TSO/E Version 2 REXX/MVS Reference SC28-1883
REXXTOOLS/MVS Basic Services provides numerous interfaces to MVS system

services. Unless you are an experienced MVS programmer you may need to do more
reading on the function and usage of these services. The following IBM manuals provide
information related to the system services which REXXTOOLS/MVS uses:

MVS/DFP Macro Instructions for Data Sets SC26-4747
MVS/DFP Using Data Sets SC26-4749
MVS/DFP System Programming Reference SC26-4567
DFSMS/MVS Macro Instructions for Data Sets SC26-4913
DFSMS/MVS Using Data Sets SC26-4922
DFSMS/MVS DFSMSdfp Advanced Services SC26-4921
MVS/ESA Assembler Programming Guide GC28-1644
MVS/ESA Assembler Programming Reference GC28-1642
MVS/ESA Authorized Assembler Programming Guide GC28-1645
MVS/ESA Batch Local Shared Resource Subsystem GC28-1672
TSO/E Version 2 Programming Services SC28-1875
Introduction 3
The REXXTOOLS/MVS DB2/SQL Services provide access to DB2/MVS relational
databases. Unless you are an experienced SQL programmer you may need to do more
reading on the function and usage of SQL statements. The following IBM manuals
provide DB2-related information:

DB2 Application Programming and SQL Guide SC26-4889
DB2 Messages and Codes SC26-4892
DB2 SQL Reference SC26-4890
DB2 Command and Utility Reference SC26-4891
Trademarks
REXXTOOLS/MVS is a registered trademark of Open Software Technologies, Inc.
The following names are trademarks of International Business Machines in the United
States, other countries, or both:
IBM, MVS/ESA, MVS/XA, MVS/DFP, DATABASE 2, DB2, QMF, SAA, VTAM, NetView,
System/370, System/390, z/OS, CICS, RACF, VSE/ESA, VM/ESA, OS/390
MVS/Quick-Ref is a trademark of Chicago-Soft, Ltd.
The following names are trademarks of Computer Associates:
ACF2, TOP Secret, OPS/MVS
AutoOperator is a trademark of Boole and Babbage.
AF-Operator is a trademark of Candle Corporation.
TCPaccess is a trademark of Interlink Computer Sciences, Inc.
What’s New in Version 7 Release 1

Release Date: July 2005
Basic Services:
A new facility, “REXX MQSERIES Interface,” is introduced (see the file “RXMQOV.htm”
located in \OST\RXT\V070101\HTML). It consists of a single REXX function RXMQ (see
the file “RXMQ.htm” located in \OST\RXT\V070101\HTML). The function has many sub-
functions for getting data into and out of Websphere MQ.
The Interpretive compiler now supports a NONAMES option for hiding all names within
the object module.
The RXSUBCOM function has had all authorization checking removed to allow for
peaceful coexistence with IBM's RXSUBCOM.

What's New in Version 6 Release 1
Release Date: June 2002
Basic Services:
CICS External Interface: A new function, REXCI, is provided for accessing CICS
transactions. The CICS transactions must be written to the Distributed Program Link
(DPL) specification. REXCI uses IBM's EXCI "call" interface.
External Writer Facility: A new batch program, RXTWTR, is provided for developing
external writers in REXX. RXTWTR uses IBM's SYSOUT Application Programming
Interface (SAPI) to select and process JES spool data sets. Many selection parameters
are available as are many data items concerning selected data sets. The writer program
has the option of reading the data sets and changing their disposition and other
characteristics.
VSAM: The VSAM interface has been improved to support extended addressing data
sets. The interface automatically detects when an extended addressing data set is being
used. The interface will accept and return RBA values larger than 4G as needed.
QSAM: The QSAM interface has been improved to support data sets with spanned
records. Records up to 32756 bytes can be read and written.
REXX Compiler: The interpretive compiler accepts a new keyword, PREFIX. The prefix
keyword can be used to specify either the RXTRXPRE (the default) or RXTRXPRC prefix
modules. This simplifies link-edits when using RXTRXPRC.
RXTEXEC and RXTJCL: RXTEXEC and RXTJCL are included for compatibility, but their
use is deprecated. You no longer can use either of these facilities to skip the basic
installation steps. Documentation for RXTEXEC and RXTJCL has been removed.
Dynamic and Static SQL Services:
A new REXX function, DB2CMD, has been added. This function permits authorized users
to execute DB2 commands. Command output is returned to the program.
Architectural Improvements
The following improvements have been made:
1. The REXXTOOLS load library is no longer shipped. 2 jobs, RXTALLOC and

RXTLINK, are supplied to create the load library. This makes it possible to block the
load library in a way that conforms to local standards.
2. The restriction of 20 authcodes per copy of REXXTOOLS has been removed. It is

now possible to create one copy of REXXTOOLS that you can distribute to all of your
authorized CPUs. A new RXTAUTH job is supplied.
3. Installing default parameters has now been made easier. A new job, RXTPARMS, is
supplied for setting these parameters.
Introduction 5
Release Date: March 1997
Basic Services:
QSAM: Queued Sequential Access Method support has been added.

Implemented as REXX functions, this interface permits access to
physical sequential data sets and members of partitioned data sets. All
record formats, except spanned, are supported.
BPAM: Basic Partitioned Access Method support has been added. Implemented
as REXX functions, this interface permits access to partitioned data sets
(PDS and PDSE). The interface permits multiple members to be read,
written, or updated with a single OPEN/CLOSE sequence. Directory
entries can be created, updated, read, and deleted. You can also create,
update, and delete member aliases. A directory entry's user field may be
created and updated in raw binary format or in ISPF statistics format. All
record formats, except spanned, are supported. The interface presents a
logical record interface to the user.
Data Set Information: New functions are provided for retrieving data set information.
Catalog, VTOC, SMS, allocation (ddname), space allocation and utilization, and PDS
directory information are provided by this collection of functions. The new functions are:
DSNINFO retrieves 37 data items for cataloged and uncataloged data sets.
Included in this information are volume serial number, unit type, DCB
parameters, space allocation and utilization, and SMS classes.
DDNINFO retrieves 16 data items for allocated data sets, including DSNAME,
volume serial number, unit type, DCB parameters, status and
dispositions.
LISTA lists current allocation information, including DSNAMEs, DSORGs,

status, and dispositions. DDNAME patterns may be specified to limit the
DDNAMEs listed.
LISTM lists PDS/PDSE directory information. Reports TTR, alias, and user field
information (in raw or ISPF stats formats). Member patterns may be used
to limit the members listed.
The data set information functions can be used in any address space (TSO is not
required).
IDCAMS: A new host command environment is supplied as well as 2 IDCAMS-based

functions. The IDCAMS host command environment allows IDCAMS commands to be
embedded in REXX programs. IDCAMS messages are returned in special stem
variables. The IDCAMS functions simplify common tasks. These are:
LISTC lists catalog information. Based on the LISTC command, this function
returns one record of information for each data set in fixed column
format.
DSNDEL deletes and scratches data sets. Based on the DELETE command, this
function also supports data set patterns for multiple data set deletions.

Neither the IDCAMS host command environment nor the IDCAMS functions require TSO
services.
REXX Compiler: The REXX compiler, RXTCOMP, no longer requires TSO services. The
RXTCL procedure has been updated to reflect this change. In addition, the compiler will
now derive a CSECT name using the member name or next-to-last sequential data set
qualifier. Because of this, the NAME parameter is no longer required (but is still
accepted).
MVS Services: Improvements have been made to the following functions:
RACROUTE A new argument has been added to suppress "ICH" messages. These
messages are issued whenever an authorization check fails.
ENQ More accurate reporting of return and reason codes.
DEQ More accurate reporting of return and reason codes.
General REXX Extensions: A new pattern matching function, MATCH, has been added.
This function supports matching using wildcard characters.
Static SQL: The following improvements have been made:
1. A static SQL program's data area can now be as large as 12K bytes.
2. Null output variables are now REXX dropped (unassigned) as in Dynamic DB2/SQL
Services.
3. High-level assembler support has been added.
4. The static SQL preprocessor (RXTHPC) no longer requires TSO services. Skeletons
and exec have been updated to reflect this change.
Architectural Improvements: The following improvements have been made:
1. All storage is now allocated from a single subpool. The subpool number can be
customized for special environments.
2. The product ESTAE exit has been improved to better report ABEND reason codes.
3. Temporary authorization codes: A single message is issued -- once for each task
using REXXTOOLS -- that displays the number of days remaining until expiration.
The messages begin appearing 10 days prior to the expiration date.
Documentation:
REXXTOOLS documentation has been reorganized into 4 publications:
1. REXXTOOLS/MVS General Information

2. REXXTOOLS/MVS Installation Guide
3. REXXTOOLS/MVS Basic Services User's Guide
4. REXXTOOLS/MVS DB2/SQL Services User's Guide
Introduction 7
What's New in Version 4 Release 1 Mod 2
Release Date: August 1995
Basic Services:
VSAM: The following improvements have been made:
1. Support for Variable-length Relative record Data Sets (VRDS) is included in this
release. Code paths have been shortened and other internal improvements have
been made, resulting in a 55% reduction in the number of service units consumed
during sequential processing of VSAM data sets.
2. New RPL options have been added to control the creation of $RXT variables. The
NOV option specifies that $RXT variables are not to be created. The VAR option (the
default) specifies that $RXT variables are to be created.
3. New ACB options DDN and DSN have been added to give the user explicit control
over the way subtask sharing of VSAM control blocks and buffers is to be conducted.
The default, DDN, is consistent with previous releases of REXXTOOLS.
4. The OPEN function will now tolerate multiple OPENs for the same ddname. The
CLOSE function will tolerate multiple CLOSEs for the same ddname. In both cases, a
return code value of 0 and a reason code value of 1 are returned.
5. The VSAM samples have been completely rewritten to better demonstrate how
records can be parsed and formatted using REXX and REXXTOOLS facilities, and to
demonstrate the use of VSAM in multi-user and batch environments.
Dynamic Allocation: The following improvements have been made:
1. A new dynamic allocation interface for compiled languages is provided. The module,
RXTDAIR, is used to allocate and free data sets from within COBOL, PL/I, and
assembler language programs.
2. The ALLOCATE command now supports BLKSIZE(0). This permits SMS

determination of the appropriate block size.
General REXX Extensions: Several new functions have been added:
RXTTERM gives the REXX programmer explicit control over the termination of the
REXXTOOLS environment. While the use of this function is not generally
recommended, it may be necessary in specialized address spaces
where automatic environment clean-up is not available.
D2F converts REXX decimal numbers to binary floating point numbers.
F2D converts binary floating point numbers to REXX decimal numbers.
D2PIC converts REXX decimal numbers to COBOL-style numeric picture

strings. Full support for floating currency symbols, and other types of
editing is available.
PIC2D converts numbers containing currency symbols and other editing

characters to REXX decimal numbers.

The following functions have been modified:
STEMSORT has been modified to support full-length ascending and descending sorts
with blank padding.
D2P and P2D have a new optional argument that allows the user to specify a value to
be returned in the event of a syntax error. This argument makes
programming for null or invalid data much simpler.
Dynamic SQL: The following improvements have been made:
1. New keywords have been added to the OPTIONS statement to permit the dynamic
modification of DB2 subsystem and plan name defaults. These changes, which
remain in effect for the life of the current task, remove the need for an explicit
DSNALI OPEN call.
2. A new function, RXTDBSQL, has been added. This function provides a stand-alone
function call interface to the dynamic SQL feature. RXTDBSQL may be invoked
under alternative REXX interpreters, provided that these interpreters use the same
calling conventions as REXX/MVS (e.g., OPS/REXX).
3. New DB2 samples have been added to the sample library, which demonstrate the
use of REXXTOOLS in ISPF applications.
4. New samples have been added which demonstrate the use of REXXTOOLS in
TCP/IP-based client/server applications. TCPLNT is an OS/2-based REXX client
program that sends SQL requests to TCPSERV, an MVS/REXX server program.
TCPSERV uses the REXXTOOLS dynamic SQL interface to execute the requests
and format replies. TCPSERVJ provides JCL for running TCPSERV.
5. Documentation for the "compatibility" interface has been moved to an appendix.
Static SQL: The following improvements have been made:
1. The RXTI Defaults panel has been changed to permit the specification of the DB2
load library.
2. The Preprocess panel has been changed to permit the explicit specification of the
output EXEC and ASM member names.
Architectural Improvements: As a result of customer feedback, two changes have been

made to make installation easier than ever:
1. Authorization codes have been greatly simplified yet expanded. Now only one
authorization code (temporary or permanent) is required per CPU. Each authorization
code indicates what features are licensed for a particular CPU. And, a single copy of
REXXTOOLS/MVS can be authorized for use on up to 20 CPUs.
In addition, to reduce the chance of transcription errors, authorization codes have

been shortened from 32 to 24 printable hexadecimal digits.
2. Two new programs have been added that permit the use of REXXTOOLS from TSO,
ISPF, and batch without permanent installation of the REXXTOOLS load library:
Introduction 9
RXTEXEC a TSO command for running REXX programs that use REXXTOOLS
facilities. RXTEXEC can be used from TSO READY mode, and from
within ISPF. It does not require a STEPLIB or ISPLLIB installation of the
product.
RXTJCL a program for running batch REXX programs.
These programs also permit authorization codes to be dynamically specified (i.e., use of
AMASPZAP is no longer mandatory).

Release Date: July 1994
Basic Services:
VSAM: The following improvements have been made:
1. Support for Batch Local Shared Resource (BLSR) subsystem is included in this
release. Using BLSR, programs that randomly access VSAM data sets can gain
significant performance improvements.
2. Support for TYPE=T (temporary) CLOSEs of VSAM data sets has been added. A
TYPE=T CLOSE flushes buffers and updates catalog information without
disconnecting the program from the data set.
Dynamic Allocation: ALLOCATE and FREE commands have been added to the
REXXTOOL host command environment. These commands, which are modeled after the
TSO/E commands of the same names, allow batch and APPC/MVS execs to dynamically
allocate and free data sets without using the computationally expensive TSO Terminal
Monitor Program (IKJEFT01).
REXX Compiler: New support for inter-language communication has been added to the
interpretive compiler. Using an alternative prefix module, RXTRXPRC, compiled execs
can now pass data back to their callers. Programs written in COBOL II, PL/I or assembler
can use this facility.
Dynamic SQL: The following improvements have been included in this release:
1. The algorithm for PREPARE avoidance has been slightly modified to gain an
additional 10 to 15 percent reduction in time spent in DB2 processing.
2. All return codes have messages associated with them. By default, messages will
appear if a non-zero return code is produced. Message printing can be turned off or
on using the NOMSGS or MSGS keywords of the OPTIONS command (also new
with this release).
3. Complete support for DB2 3.1 parallelism and Remote Unit of Work has been added.
The new statements that support these features are RELEASE, SET CONNECTION,
and SET CURRENT DEGREE.
4. A new sample exec, SP2RX, has been added. SP2RX converts SPUFI-style SQL
statements into a format suitable for inclusion in REXX programs. This utility makes it
easier to port SPUFI-tested SQL statements to your REXX programs.

Static SQL: The following improvements have been included in this release:
1. The Static SQL feature now supports multi-row SELECT statements, making it easier
to transition programs from dynamic to static SQL. The user may selectively choose,
on a program-wide basis, whether SELECTs are to be interpreted as a single-row or
multi-row.
2. The RXTI interactive application has been improved to provide greater flexibility when
preprocessing REXX programs. Options have been provided that permit the user to
customize bind processing and to specify whether the preprocessed exec is to be
compiled.
What's New in Version 2 Release 1 Mod 2

Release Date: March 1994
Basic Services:
General REXX Extensions: The following improvements have been made:
1. A new host command environment (ADDRESS REXXTOOL) and three new host
commands have been added to permit the sharing of data between REXX source
programs. The new host commands are:
VPUT A host command for placing a value in a global variable.
VGET A host command for retrieving a value from a global variable.
VERASE A host command for deleting a global variable.
2. The D2P function has been improved to accept precision and scale arguments.
Precision and scale may be used instead of byte length to determine the size of the
packed number.
Dynamic SQL: A new dynamic SQL implementation has been added. The new interface
permits programs to be coded that will run in both the dynamic and static SQL
environments The new dynamic SQL interface supports DB2 Version 2 Release 3
features such as CONNECT, and contains numerous performance enhancements,
including PREPARE statement avoidance.
The new dynamic SQL interface does not replace the previously released dynamic SQL
interface. The older interface will continue to be supported.
Static SQL: A new static SQL implementation has been provided. The static SQL
interface consists of a REXX precompiler (similar to IBM's DSNHPC program) and a run-
time environment. The precompiler produces a modified REXX source program -- which
can be compiled using the REXXTOOLS interpretive compiler -- and a Data Base
Request Module (DBRM) that can be used to produce a static plan. The run-time
environment provides REXX variable management and conversion services.
Introduction 11
Release Date: February 1993
Basic Services:
VSAM: Improvements have been made to the VSAM functions which permit REXX
programs to open an unlimited number of VSAM files. File (ddname) sharing among
external REXX programs has also been greatly simplified. In particular, programs no
longer are required to pass the $RXTFITB variable in order to share ddnames.
General REXX Extensions: The following functions have been added:
RXFUNC a function for dynamically maintaining (add, update, delete, query) REXX
function packages. RXFUNC also pre-loads the load module associated
with a function to enhance performance.
RXSUBCOM a function for dynamically maintaining host command environments. As

with RXFUNC, RXSUBCOM pre-loads the load module associated with a
function to enhance performance.
STORAGEX a function for retrieving and modifying virtual storage using the indirect
addressing notation of the TSO TEST command.
REXX Compiler: The REXXTOOLS interpretive compiler has been improved to handle
special-purpose parameter lists. Previously, a parameter list that was not recognized as
one of the explicitly supported types was reported as an error. With Version 2 Release 1
of the compiler, unrecognized parameter lists cause a printable representation of the
address contained in general purpose register 1 to be passed on to the ARG() function.
Dynamic SQL: A new and separately priced component for accessing DB2 has been
added. Using the Dynamic SQL feature, REXX programs can perform queries (SELECT),
create rows (INSERT), modify rows (UPDATE), and remove rows (DELETE). The
interface supports a multi-row SELECT that permits access to an entire result set without
the need to code a "fetch loop," as one would do in PL/I or COBOL. Alternatively, a
REXX programmer can choose to explicitly code a fetch loop if the application's logic
requires it.
The new Dynamic SQL support includes:
1. A new host command environment "Address SQL".
2. New functions:
DB2INFO a function for extracting information related to DB2 default values, and
the subsystem names of installed DB2 subsystems.
DSNALI a function for invoking the services of the DB2 Call Attachment Facility
(CAF).
3. New samples have been added to the sample library which demonstrate the use of
dynamic SQL.

Architectural Improvements: The following internal improvements have been made to
the product:
1. REXXTOOLS no longer requires you to modify your REXX parameters modules.

Specifically, the requirement for the REXX host command environment has been
removed as has the requirement for the exec termination exit, RXTEXECT.
2. The product's function package has been renamed from RXTFLOC to the standard
IRXFLOC name which is found in all IBM-supplied parameters modules. The source
CSECT for the IRXFLOC module is provided so that you can add your own REXX
functions.

Release Date: February 1992
Basic Services:
General REXX Extensions: The following functions have been added:
PARSETOK a function for parsing strings into tokens where the position and
frequency of token delimiters is unpredictable.
QWIKREF an interface to Chicago-Soft's MVS/Quick-Ref database. You must be an

MVS/Quick-Ref customer to use this function.
WORDSORT a function for sorting the blank-delimited words in a string. The words
may be of any number or size, and can be sorted in either ascending or
descending collating sequence.
REXX Compiler: A new program, RXTCOMP, has been added for batch compiling
REXX programs into OS object modules. The compiler has the following interfaces:
RXC a TSO command for invoking the compiler.
RXTCL A JCL procedure for invoking the compiler and the system linkage-editor
from batch jobs.
Introduction 13
How to Use REXXTOOLS/MVS
The following sections describe how to code REXXTOOLS host commands and
functions, and how to call programs that use these facilities.
If you are new to REXX, there are two IBM manuals with which you will want to become
familiar. These are:
• The TSO/E Version 2 REXX/MVS User's Guide, SC28-1882. This manual provides
an excellent tutorial on the REXX language as it is implemented under MVS. If you
have never used REXX, this is the book you should start with.
• The TSO/E Version 2 REXX/MVS Reference, SC28-1883. This manual is a

comprehensive reference for the REXX language. This book is the definitive source
for information on REXX language statements, built-in functions, and IBM-supplied
host commands. However, it does not contain any tutorial information.
Notational Conventions
Throughout this manual the following notational conventions are used:
Uppercase Uppercase text shows items that must be coded exactly as shown. For
example:
OPEN(
Lowercase Lowercase text is used to indicate values which the user must supply.
Example:
Ddname
Brackets [ ] are used around optional items. For example, the following item may
or may not be coded:
[,password]
Important Note: Optional arguments for REXX functions are positional.

That is, if you decide to skip over an optional item, you must use a place
holding comma. For example, in the following function call, the first and
third arguments are coded; the second argument, which is optional, is
skipped:
FUNC('ABC', , 'DEF')
Had we wanted to omit both the second and third arguments we would
simply have coded:
FUNC('ABC')
How to Use REXXTOOLS/MVS 15

Braces { } are used around items where one (and only one) of the listed choices
may be coded. Example:
{A|B|C}
OR | is used to separate choices in a list of items. Only one of the items in

the list may be coded (see previous example).
Ellipses ... are used whenever an item (or group of items) may be repeated.
Example:
[,'(option,...)']
Underscore Underscored items are used to indicate default values (i.e., the value that
will take effect if you do not code an item). Example:
{A|B|C}
All other punctuation shown in syntax diagrams (quotation marks, parentheses, etc.)
must be coded exactly as shown.
REXXTOOLS/MVS Environments
REXXTOOLS/MVS has been verified to operate in the following environments:
• Interactive TSO
• TSO Batch
• REXX Batch (includes APPC/MVS)
• NetView and many other MVS automation products.
• IBM's HTTP Server.
Using REXXTOOLS/MVS Functions

All syntax diagrams in this manual show the invocation of REXXTOOLS/MVS functions
using the REXX function call syntax:
FUNC(arg1, arg2, arg3,...)
You may safely call all REXXTOOLS/MVS functions using this method since they all
return values.

Using the CALL Instruction
You may invoke any REXXTOOLS/MVS function using the REXX CALL instruction as is
shown below:
CALL FUNC arg1, arg2, arg3,...
Functions that are CALLed, return their values in the RESULT special variable.
Quick Tip: Remember when you are converting a function call into a CALL to remove the
parentheses from around the arguments. If you forget to do this, REXX will pass all your
arguments as one string.
Using REXX Variables for Arguments
Throughout this manual, many examples depict arguments to REXXTOOLS/MVS

functions as numeric or character literals. However, as with all REXX functions, you may
use REXX variables or even complex expressions to supply argument values. REXX
always performs expression evaluation and variable substitution before invoking a
function.
Example:
ddname = 'INDD'
options = '(IN,OUT,ADR)'
call open 'vsam' , ddname, options
In this example, the values for DDNAME and OPTIONS will replace the variable names
before the OPEN function executes.
Coding Option Strings
Option strings are single character string arguments that contain one or more processing
options. Unless stated otherwise, when only one option is to be passed, the option may
appear by itself with no other punctuation. If several options are to be specified, they
must be enclosed within parentheses and separated by commas (not blanks).
Examples:
1. Single option:
'KEY'
2. Multiple options:
'(KEY,SEQ,UPD)'
3. This is OK too:
'(KEY)'
Note: Option strings must not contain leading, trailing, or imbedded blanks.

Using REXXTOOLS/MVS Host Commands
REXXTOOLS/MVS supplies the following host command environments:
REXXTOOL supports commands for dynamic allocation, global variables, and

REXXTOOLS configuration.
IDCAMS for issuing IDCAMS commands
SQL for executing DB2/SQL statements (Dynamic DB2/SQL Services only).
The specific documentation for the commands associated with these host command
environments is found this manual and other REXXTOOLS/MVS publications. The
following bullets describe the general rules for using host commands:
• A host command is any REXX expression that is not one of the REXX language
instructions. For example, all of the following expressions will be recognized by
REXX as host commands:
/* a literal host command */

"vput (var1, var2) shared"
/* a concatenation expression with variables */

"allocate fi("||myfile||") da("||mydsn||") shr reu"
/* a function call expression that returns the

host command to be executed */
makecmd()
Host commands composed of REXX expressions are completely evaluated by the

REXX interpreter (or compiler) prior to execution. Thus, all that a host command
environment ever receives is a character string containing the command to be
executed.
• Host commands are always directed to the current host command environment.
When a REXX program starts, a default host command environment is in effect until
you use the REXX ADDRESS instruction to switch to another one.
The format of the ADDRESS instruction is:
ADDRESS host-command-environment-name
For example to switch to the REXXTOOL host command environment, you would
code:
address rexxtool
If you are unsure about which environment is in effect, you can use the REXX
ADDRESS function to find out what it is. For example:
CurEnvir = address()

Programming Tip: It is a good practice to use the ADDRESS instruction liberally.
You should put an ADDRESS instruction fairly close to any sequence of host
commands. This provides for good documentation (after all, some host command
environments have very similar commands), and it can eliminate one of the most
common REXX programming errors: sending a host command to the wrong host
command environment.
• A single host command can be directed to a specific host command environment

without changing the current host command environment. To do this you code the
host command immediately after the ADDRESS instruction. For example:
address sql "select * from dsn8310.emp"
• All host commands set the RC variable. As with any service call, you should always
check the RC value (and other relevant variables that may be set by the host
command) to ensure that the operation was successful. For example:
address tso
"listd mydataset m"
if rc <> 0 then do
say "An error has occurred. RC='rc
exit 8
end
• If you need to interrupt a long-running host command under TSO, use the
following procedure:
1. Press the attention key (sometimes this is PA2). This will cause the REXX
attention handler to get control. The attention handler clears the screen and
issues the following prompt:
ENTER HI TO END, A NULL LINE TO CONTINUE, OR AN IMMEDIATE

COMMAND+ -
2. Enter the HE (Halt Execution) command. This will terminate the host command,
and the REXX program that invoked it, by detaching the TSO subtask.
Special REXXTOOLS/MVS Variables

Many REXXTOOLS/MVS functions and host commands return information in specially
named REXX variables. The "Returned Information" section of each service lists and
describes these variables. In general, service return codes are returned in the RC
variable. Reason code information is returned (when applicable) in the REASON variable.
Some REXXTOOLS services may create additional variables. Consult the service's
description for more information concerning the variables it creates.
Note: Functions invoked with the REXX CALL instruction will always return a value in the
RESULT variable.
Unless stated otherwise, all REXXTOOLS-generated variables contain data that has
been converted to the REXX printable format. That is, numbers and addresses of various

types are converted to REXX printable decimal numbers or printable hexadecimal strings.
However, some data is returned unchanged (e.g., the keys of KSDSs).
WARNING: Modification of some REXXTOOLS generated variables could result in

catastrophic program failures. In general, you should never use these variables as the
target of any type of assignment (assignment statements, PARSE instructions, EXECIO
commands, etc.), unless the documentation specifically indicates that it is safe to do so.
Running REXX Programs

The following sections review most of the methods you can use to run REXX programs.
For more information on the standard methods, refer to the TSO/E and ISPF
documentation.
Important: REXXTOOLS runs in most REXX/MVS environments. However, OST

recommends that you do not run REXXTOOLS under CICS, IMS, or IPCS.
Running REXX Programs Under TSO
The TSO Terminal Monitor Program (TMP) executes TSO commands, CLISTs and
REXX programs (also called "execs"). There are two ways you can invoke REXX
programs under the TMP:
• The first method is called explicit execution. To explicitly execute a REXX program
you use the TSO EXEC command. The EXEC command has the following format:
{EXEC | EX} dsn 'parameters' EXEC
For example, if you want to run an exec that is in the MYEXEC member of your
'TSOUSER.EXEC' partitioned data set, you would enter the following command:
exec 'tsouser.exec(myexec)' 'This is a parm string' exec
• The second method is called implicit execution. To implicitly execute a REXX exec,
you simply enter its name. For example, to run MYEXEC implicitly you would enter:
myexec these words are parameters
While this second method is certainly the easier of the two, it does require a little set-
up work. First, you must have allocated your exec library to either the SYSPROC or
SYSEXEC data set concatenation (your systems programmer can tell you which one
to use - or you can allocate the data sets to both. It doesn't hurt anything). Second,
you must have coded on the first line of your REXX program, a comment that
contains the word "REXX". For example:
/* Myexec - My first REXX program */

say 'Hello World!'
A related method, called the extended implicit form, will cause the TMP to search
strictly for a REXX program, possibly leading to faster invocation. To use this method,
you append a percent (%) sign to the front of the command. For example:
%myexec

Running REXX Programs Under ISPF
There are several ways to run REXX programs under ISPF:
• From any command line in ISPF you can use the TSO command to either explicitly or
implicitly (refer to the previous section) run a REXX exec. For example:
COMMAND ===> tso %myexec
or
COMMAND ===> tso ex 'tsouser.exec(myexec)' exec
• From option 6 of ISPF you can execute an exec just like you would from TSO
READY. For example:
===> %myexec
or
===> ex 'tsouser.exec(myexec)' exec
• If you want to run your program from a menu, you can code a reference to it in the
)PROC section of the panel definition. For example:
&zsel = TRANS( TRUNC(&zcmd,'.')

1,'CMD(%myexec)'
' ',' '
X,'EXIT'
*,'?')
• If you want to execute your program from another program (either written in REXX or
one of the compiled languages), and you want ISPF to be "aware" of your
application, use the ISPF SELECT service. For example, from REXX code:
address ispexec "select cmd(myexec)"
Note: If you only want to invoke one REXX program from another, you can use the
standard REXX CALL instruction, or code a function reference.
• To start ISPF and run a REXX program, use the ISPSTART command as follows:
ispstart cmd(myexec)
• If your application satisfies the requirements for an ISPF edit macro (refer to IBM's
documentation for the details), you can invoke the REXX program from the editor's
command line:
COMMAND ===> myexec
Alternatively, you can associate the macro with a Program Function (PF) key, using
the ISPF KEYS command.

• If you want to run a compiled exec under ISPF, you must use the LANG(CREX)
parameter on the SELECT command. This rule applies to programs that have been
compiled with the REXXTOOLS interpretive compiler as well as programs compiled
with REXX/370.
Running REXX Programs in the Background
REXX programs can be run as steps in batch jobs. There are two methods for doing this.
If your REXX program utilizes TSO services, such as TSO

commands (like ALLOCATE) or TSO-specific functions (like
LISTDSI), you must run your program under batch TSO. The
JCL required for batch TSO looks like this:
//STEP1 EXEC PGM=IKJEFT01,PARM='myexec parm1 parm2'
//STEPLIB DD DISP=SHR,DSN=REXXTOOL.LOAD
//SYSEXEC DD DISP=SHR,DSN=TSOUSER.EXEC
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
Input for PULL instructions goes here.
Use DD DUMMY if you don't need this.
/*
• If your program does not use TSO services, you are much better off running under
the batch interpreter interface, IRXJCL. Programs typically run much faster under the
batch REXX interpreter because they avoid all of the overhead associated with TSO.
The JCL for the batch interpreter is as follows:
//STEP1 EXEC PGM=IRXJCL,PARM='myexec parm1 parm2'

//SYSTSIN DD *
Input for PULL instructions goes here.
Use DD DUMMY if you don't need this.
/*
Other examples of batch REXX JCL can be found in the REXXTOOLS sample library
(REXXTOOL.SAMPLIB). See especially SAMPLIB member BATREXXJ.
Notes:
1. You do not need the STEPLIB card shown in the examples above if the
REXXTOOLS load library has been installed in a system data set (i.e., link list or
LPA).
2. If the only TSO service your program uses is dynamic allocation (the ALLOCATE and
FREE commands), you can substitute REXXTOOLS dynamic allocation and still use
IRXJCL. See the chapter "Dynamic Allocation" for more information on this subject.

Running REXX Programs Under Automation Packages
REXX programs that use REXXTOOLS facilities can, in general, be run wherever any
REXX program can be run. However, the installation of REXX programs varies greatly
from environment to environment. For example, NetView requires that REXX programs
be placed in the DSICLD data set concatenation. You must consult the user
documentation for each product to determine what steps are necessary.
Running REXX Programs Under HTTP Server
REXXTOOLS-enabled CGI scripts (CGI stands for Common Gateway Interface), can be
run under IBM's HTTP Server. If the REXXTOOLS has been installed in system wide
libraries (i.e., the link list or LPA), there are no special steps to follow. Simply code
references to REXXTOOLS functions and host commands in your scripts.
If, however, REXXTOOLS has not been installed on a system-wide basis, you will need
to add the REXXTOOLS load library to a STEPLIB allocation for the started task. Having
done that, you will then need to stop and restart the server.
Notes:
1. Follow IBM's documentation concerning the placement of REXX CGI scripts

(typically, they are placed in the cgi-bin directory).
2. An example CGI script that uses REXXTOOLS DB2/SQL Services is contained in the
RXTCGI member of the sample library.
Running REXX Programs Under APPC/MVS
APPC/MVS is a facility for writing server applications. APPC server applications -- often
called transactions -- can be written in most high level languages, including REXX. APPC
transactions are defined in a TP profile data set. The transaction definitions consist
mainly of JCL statements. REXX transactions that require TSO services must use batch
TSO JCL (see "Running REXX Programs in the Background" above). REXX transactions
that do not require TSO services can use either batch REXX JCL (PGM=IRXJCL) or
batch TSO JCL.
REXXTOOLS supplies another invocation method for REXX transactions that do not
require TSO services. The module that implements this method is called RXTAMT. REXX
transactions run under RXTAMT are "multi-trans" transactions, and remain in their APPC
initiators between invocations, resulting in faster execution.
You use RXTAMT in exactly the same manner as you use IRXJCL. For example, to run a
REXX program named EMPUPD as a multi-trans transaction you would create the
following TP profile:
//JOBNAME JOB
//STEP EXEC PGM=RXTAMT,PARM='empupd parm1 parm2'
//SYSTSPRT DD DSN=TSOUSER.EMPUPD.SYSTSPRT,DISP=SHR
//SYSTSIN DD DUMMY

A REXXTOOLS environment is available to programs run under RXTAMT only if the
product is installed in a system library or you have include a STEPLIB containing the
REXXTOOLS load library. Even then, only the REXXTOOLS functions will be
immediately available. If you want to use the REXXTOOL or SQL host command
environments, you must use the RXSUBCOM function to add them.
Notes:
1. Writing and configuring APPC/MVS transactions is a complicated topic beyond the

scope of this manual. To find out more about writing APPC/MVS transactions, refer to
MVS/ESA Programming: Writing Transaction Programs for APPC/MVS, GC28-1471.
Some REXX-related APPC information can be found in TSO/E Version 2 REXX/MVS
Reference, SC28-1883, in the "REXX General Concepts" chapter.
2. Sample APPC server and client programs are provided in the REXXTOOLS sample
library. The relevant sample library members are SQLSERV, SQLSERVJ, and
SQLCLNT. These programs demonstrate the use of the REXXTOOLS dynamic SQL
interface under APPC/MVS.
Technical Support
Due to the mission-critical nature of our customer's applications, Open Software
Technologies provides technical support for REXXTOOLS/MVS on a 24X7 basis. If you
have a problem that requires immediate resolution, please contact OST or your local
distributor by phone. Our U.S. phone number is:
(407) 788-7173
Our Fax number is:
(407) 788-8494
For technical questions, the best way to reach us is by electronic mail. Our email address
for technical support is:
support@mail.open-softech.com
We are always happy to hear from our customers, and encourage you to contact us with
ideas and suggestions, as well as technical questions.
Common Problems and Resolutions
Most REXXTOOLS technical support incidents arise from difficulties in one of two areas:
• Product installation.
• REXX usage.
Installation Problems
The most common installation problem is failure to install the REXXTOOLS function
package. Its primary symptom is REXX message IRX0043I (Routine not found). If this

happens to you, try the following:
1. First determine what function packages REXX is using by running the RXTDFUNC
exec in the environment where you are experiencing the problem. To execute
RXTDFUNC under TSO, enter the following command from the READY prompt:
ex 'rexxtool.exec(rxtdfunc)' exec
The REXXTOOLS function package is named IRXFLOC. Compare RXTDFUNC's

listing of IRXFLOC with the source of IRXFLOC in REXXTOOL.SAMPLIB. If it doesn't
match, IRXFLOC is being loaded from another source.
2. REXX issues an undirected LOAD for IRXFLOC during REXX environment

initialization. Make sure that no other copy of IRXFLOC appears earlier in the LOAD
search sequence (job pack, tasklib, steplib, link pack, LPA). The DDS (ddname scan)
and LLS (link list scan) execs can be helpful in finding occurrences of IRXFLOC.
Refer to "Appendix B: REXX Development Tools" on page 287 for more information.
3. IRXFLOC is a reentrant module. If a non-REXXTOOLS IRXFLOC has been loaded

into the job pack area, the REXXTOOLS copy will not be loaded. This can happen if
the first REXX environment in an address space does not load the REXXTOOLS
IRXFLOC. The RXTLJPQ exec can be used to determine the current contents of the
job pack area.
On some occasions, the symptom for this problem is a S0C4 or other abend. This
can happen when the REXXTOOLS function package is invisible to the system, but
another function package having identical names is present. It can also happen when
stand-alone load modules having names identical to REXXTOOLS functions are
found by the system. In both cases, incompatible parameter list formats may cause
an abend.
REXX Problems
The REXX questions we receive encompass all aspects of the language. However, a
common thread is that many programmers simply don't know what is happening in their
programs. The REXX interpreter provides two very helpful facilities for illuminating the
operation of REXX programs: the TRACE and SAY instructions.
The TRACE instruction. Sometimes a trace of your program's execution is all that is
required to solve a problem. To use REXX tracing, simply insert a TRACE instruction in
front of the code in question. There are many TRACE formats, and an entire chapter
("Debug Aids") of the REXX/MVS Reference is devoted to it. The most commonly used
forms are:
TRACE R traces the results of each statement.
TRACE I traces all intermediate values. Use this form to verify that arguments to
functions are correct.
TRACE ?R starts interactive tracing. The interpreter pauses after each statement. At
the pause, you can use the SAY instruction to display the contents of
variables.

The SAY instruction. Another common problem is not knowing what values variables
contain. The easiest way to determine what value a variable contains is to display it with
the SAY instruction. Insert SAYs around statements of which you are unsure. If the data
in question is (or could be) binary, use the C2X function to print out a hex dump of the
variable's value. For example:
say c2x(BinVar)
C2X will always convert the data to printable hexadecimal characters, no matter what its
type may be.

QSAM Functions
The REXXTOOLS/MVS QSAM interface gives REXX programmers access to sequential
files and partitioned data set members using the Queued Sequential Access Method
(QSAM). It provides several capabilities not provided by the REXX/MVS EXECIO
command:
• You can read, write and update all record formats except spanned. The EXECIO
command specifically does not support "U" format data sets.
• You can read PDS/PDSE directories. The EXECIO command will not read these
directories.
• Because it is implemented with functions, the REXXTOOLS QSAM interface can be

used with PARSE VALUE and REXX concatenation to decompose and compose
records as they are being read and written. EXECIO, because it is implemented as a
host command, cannot be combined with REXX instructions.
Getting Started
The best way to learn REXXTOOLS QSAM programming (or any kind of programming for
that matter) is to read, execute, and modify existing programs. To get you off to a fast
start, Open Software has provided several QSAM programs in the sample library. All of
the QSAM samples begin with "QSAM" followed by a number. Each program contains
commentary explaining the techniques demonstrated.
Before reading this chapter, you should take a few moments to locate these programs,
examine and run them.
Note: You must run the QSAM01 exec first. This program creates sequential files that
are used by other QSAM sample execs.
QSAM Basics
Using QSAM you can access three types of data sets. These are described in the
sections that follow.
Physical Sequential
Defined using DSORG=PS, physical sequential data sets are used for storing data in the
order in which it was written. There are no keys, and an individual record can be
accessed only by reading past the records that precede it. The records in a physical
sequential data set can be fixed or variable length, and they may be blocked or
unblocked.
A physical sequential data set's records can be updated in place, and can be extended
(records added to the end), if the data set is allocated DISP=MOD.
Physical sequential data sets may reside on direct access devices or on tape.
QSAM Functions 27
Partitioned/Partitioned Extended
A partitioned data set (DSORG=PO) is similar to a physical sequential data set, however,
the data is partitioned into discrete segments called members. A portion of a PDS's
space is reserved for a directory containing information that is used by the operating
system to locate a member's storage4. A member's location is recorded in TTR format,
where "TT" is 2 bytes identifying the track and "R" is a single byte identifying the block.
When a member is added to a PDS, an entry for the member is inserted into the
directory. Entries in the directory are ordered by member name in ascending sequence.
Only one user at a time can add a member to a PDS.
A member's records can be updated in place. However, the only way to extend a
member is to completely rewrite it (i.e., DISP=MOD will not cause records to be added to
the end of a member as it does with sequential files).
When a member is deleted from a partitioned data set, its entry is removed from the
directory. However, the space previously occupied by the member's records cannot be
reused until the data set is "compressed" by a utility such as IEBCOPY.
PDSE data sets, from a usage standpoint, are identical to partitioned data sets but with
additional capabilities. Most importantly, PDSEs permit multiple users to write to a data
set simultaneously (though each user must be writing a different member). PDSEs also
reuse storage that is freed by member deletions, and thus, do not require periodic
compression.
When using QSAM to read a partitioned data set member, you must allocate the data set
including the name of the member. If you allocate a PDS without specifying a member
name, you will read the data set's directory. Thus, to read all of the members in a data set
using QSAM, you must allocate, open, read, close, and free each member individually (a
computationally expensive proposition). Because this is a common operation,
REXXTOOLS provides another method for processing PDSes, the BPAM interface (see
"BPAM Functions").
Partitioned and partitioned extended data sets can reside only on DASD. In addition,
PDSEs must be managed by DFSMS.
SYSIN/SYSOUT
The Job Entry Subsystem (JES) provides 2 types of data set that can be read or written
using QSAM. A SYSIN data set is created when instream data is specified. For example:
//DDIN DD *
This is a sysin record
This is too
This is the last one
/*
SYSIN data sets have a logical record length of 80 bytes. The data set is terminated with
a "/*" or another JCL statement. SYSIN data sets cannot be written. They can be read
only.

SYSOUT data sets are created by specification of the SYSOUT keyword on either a DD
or ALLOCATE statement. For example:
//DDOUT DD SYSOUT=*,RECFM=VB,LRECL=133
SYSOUT data sets can be written only.
Note: It may be necessary to specify DCB characteristics for SYSIN, SYSOUT, and
temporary data sets in order to open them using the REXXTOOLS QSAM interface.
Record Formats
The records in sequential, partitioned, and SYSIN/SYSOUT data sets can take several
forms:
• The records can all be same length or they can be varying lengths.
• The records can be grouped into blocks. The system uses the blocks when
performing physical input/output operations to improve performance. If the records
are not blocked, each physical record contains exactly one logical record.
• If desired, printer control characters can be placed in the first byte of each record.
The REXXTOOLS QSAM functions support the following formats (RECFMs):
F FA FB FBA
FBM FBS FBSA FBSM
FM FS FSA FSM
V VA VB VBA
VBM VBS VBSA VBSM
VM VS VSA VSM
U UA UM
The individual letters of RECFM indicate the following:
F Fixed length records.
V Variable length records.
U Undefined length records. From a logical record perspective, U format is similar

to variable length records, but the records cannot be blocked.
QSAM Functions 29
B Blocked records.
S For fixed length records, the S stands for standard blocks (i.e., all blocks except
the last must be the same length). For variable length records, the S stands for
spanned records.
Note: The QSAM interface permits access to spanned records no larger that
32756 bytes.
A ANSI printer control characters are in the first byte of each record.
M Machine printer control characters are in the first byte of each record.
For information regarding the selection of an appropriate data set organization and record
format refer to the IBM publication Using Data Sets for your system's level of DFP or
DFSMS.
Programming For QSAM

The basic flow of a program that processes a data set using QSAM is as follows:
1. Allocate the file. A Data Definition Name (DDNAME) is associated with the data set
you wish to process. Use a status of NEW, OLD, or MOD if you are writing or
updating a data set. Use a status of SHR if you are reading a data set. A status of
MOD lets you to add new records to the end of a sequential data set (but not a PDS
member).
2. Open the file for processing using the OPEN function. The access method makes a
logical connection between your program and the data set to be accessed. If you are
reading the file use the INPUT option on OPEN. If you are writing the file, use the
OUTPUT option. If you are updating records, use the UPDATE option.
3. Read a record from the file using GET or write a record to the file using PUT. When
reading, the GET function returns the record's contents. You can assign the record to
a REXX variable (or variables if you use PARSE VALUE). If the data set is blocked,
the access method handles deblocking. Your program processes logical records only
(not physical records). A return code of 8 indicates that there are no more records to
be read. When writing records, the PUT function accepts the record to be written as
an argument. PUT handles any blocking that may be required, and writes physical
blocks to the file as required.
4. If you are reading records, determine what processing applies to the record (if any)
and perform the processing. If the data set was opened for update, the record can be
replaced. Record deletion is not possible. To delete a record, the entire data set (or
PDS member) must be rewritten. For information regarding the processing of record
fields, please see "Working with Record Fields."
5. If appropriate, return to step 3 to process other records.
6. Close the file using the CLOSE function. Any pending physical writes are completed,
and the logical connection between the program and the data set is terminated.
7. Free the file. The DDNAME is disassociated with the data set.

Allocating Data Sets
If the program is to be run in the batch environment, the JCL Data Definition (DD)
statement may be used to allocate the data set. If dynamic allocation is required in the
batch environment, the REXXTOOLS ALLOCATE and FREE commands can be used. If
the program is running under TSO (either batch or interactive), either the TSO or the
REXXTOOLS ALLOCATE and FREE commands can be used.
Note: To process a PDS/PDSE member, you must specify the member name on the
allocation. If you allocate just the PDS data set name, your program will read the
directory.
Opening and Closing Data Sets

To associate your program with the data set you want to process, you use the OPEN
function. The CLOSE function performs the opposite action by disassociating your
program with the data set.
REXXTOOLS/MVS maintains information about open QSAM files in a data structure

associated with the task under which the OPEN function was executed. The information
is maintained by ddname. Files remain registered with REXXTOOLS and open until they
are explicitly closed, or until the task that opened them terminates.
All REXX programs under a MVS task share the same REXXTOOLS QSAM data
structures. Thus if program A calls program B (REXX CALL or function call), any ddname
that is opened by either program A or program B is known to the other. File sharing also
extends to directly subtasked REXX programs and, under ISPF, to sibling tasks (i.e.,
programs connected via ISPEXEC SELECT). As a consequence, if Program A attaches
program B, the files opened by program A are known by program B. However, files
opened by program B will not be known to A when control is returned. This is because
task termination will close all files opened by program B.
Notes:
1. If you have installed the exec termination exit (which is not recommended), files will
be closed whenever the exec that opened them terminates.
2. A PDS supports only one writer at a time. If you need to support multiple
simultaneous writers, you must use a PDSE.
QSAM Functions 31
OPEN Options
When opening a data set using QSAM, you may specify the type of access you want and
Data Control Block (DCB) parameters.
Type of Access
The REXXTOOLS QSAM interface supports 3 access options:
INPUT indicates that you will be reading records from the data set. Data sets
that are open for input can be accessed with the GET function only. The
data set can be allocated with a status of OLD or SHR (preferred).
VERY IMPORTANT: It is possible to open a newly allocated data set for

input. The operation of QSAM in this case is undefined. You may
successfully read what appears to be valid data, or (and this is more
likely) your program may encounter errors and possibly abnormally
terminate.
OUTPUT indicates that you will writing records to the data set. Data sets that are
open for output can be accessed with the PUT function only. The data
set should be allocated DISP=OLD.
UPDATE indicates that you will be reading the data set, and that you may (or may
not) be re-writing some or all records. A record must be read before it
can be re-written. When open for update, a data set can be accessed
with the GET and PUT functions. The data set should be allocated
DISP=OLD.
DCB Parameters
Record format (RECFM), logical record length (LRECL), block size (BLKSIZE), and
number of buffers (BUFNO) can be specified on OPEN. However, with rare exception,
you are much better off letting the operating system derive these values for you. For new
data sets, the information can be derived from allocation information that is kept in
memory. For existing data sets, the information is taken from the Volume Table of
Contents (VTOC).
Reading, Writing, and Updating Records

The REXXTOOLS/MVS QSAM functions for access to records are:
GET The GET function is used to retrieve records sequentially. GET returns a logical
record as its value (or a null string if an error was encountered).
PUT The PUT function is used to sequentially write or re-write records. PUT accepts a
record as one of its arguments. If the PUT follows a GET where the file has been
opened for update, the record that was retrieved by the GET will be replaced. In
all other cases, PUT is interpreted as a request to add a new record.
If the data set is allocated with a status of NEW, records will be added to the data
set starting at the beginning of the data set's space (or the first available space in
the case of a PDS or PDSE member). If the data set is allocated with a status of

OLD, the records will replace existing records, if any. If a sequential data set is
allocated with a status of MOD, records will be appended to the end of the data
set. A status of MOD will not cause additional records to be appended to the
end of a PDS or PDSE member.
Input Processing
Using the INPUT option of OPEN, you can read, sequentially, some or all of a data set's
records. In the following example, a PDS member is read:
/* REXX */
address rexxtool
"alloc fi(indd) da(user.data(timecard)) shr"
if open('qsam','indd','input') <> 0 then do
say 'OPEN failed with RC='rc 'REASON='reason
exit 8
end
timerec = get('indd')
do while rc = 0
parse var timerec lname +10 fname +10 timein +8 timeout
+8
end
call close 'indd'
"free fi(indd)"
Output Processing
Using the OUTPUT option of OPEN, you can create a data set, or add records to the end
of a data set. In the following example, a sequential data set is created:
/* REXX */
address rexxtool
"alloc fi(outdd) da(data.out) new sp(1 1) track",
"dsorg(ps) recfm(f b) lrecl(80) unit(sysda)"
call open 'qsam', 'outdd', 'output'
parse pull record
do while record <> ''
call put 'outdd', record
parse pull record
end
call close 'outdd'
"free fi(outdd)"
QSAM Functions 33
Update Processing
Using the UPDATE option of OPEN, you can replace some or all of a data set's records.
The interface ensures that replacement records are the same size as the original record.
If the replacement record is smaller than the original, the record is padded on the right
with blanks. If it is larger than the original record, the replacement record is truncated on
the right. No error indication is given in either case.
In the following example, a sequential data set's records are updated. A 2-byte packed
decimal date field in YY format is converted to a 2-byte binary date that contains the
century.
/* REXX */
if open('qsam','iodd','update') <> 0 then do
exit 8
end
record = get('iodd')
do while rc = 0
parse var record firstpart +25 date +2 lastpart
date = d2c(p2d(date)+1900,2)
if put('iodd',firstpart||date||lastpart) <> 0 then do
say 'PUT failed with RC='rc 'REASON='reason
exit rc
end
end
if close('iodd') <> 0 then
say 'CLOSE failed with RC='rc 'REASON='reason
exit
Note: For this example, the IODD ddname is assumed to be allocated in the JCL prior to
execution. P2D is a REXXTOOLS function for converting packed decimal data to REXX
decimal.
QSAM Return Codes

Upon completion, all REXXTOOLS/MVS QSAM functions provide a return code and a
reason code. The return code is placed in the standard RC variable, while the reason
code is placed in a special variable named REASON.
In addition, except for the GET function which returns a record, all QSAM functions return
the return code as their value. For example, the following code will display the return
code 2 times, once as OPEN's returned value, and once as the value of the RC variable
say "RC="open('qsam','indd','input') "RC="rc

"REASON="reason
Unless otherwise noted, the values for RC and REASON are taken directly from the
underlying QSAM macro return and reason codes. In all cases, a return code of zero
indicates success.
In the case of GET and PUT, the underlying QSAM macros do not produce return codes.
The REXXTOOLS GET function returns RC=8 when end-of-file is reached. All other non-

zero GET and PUT return codes are ABEND codes and are accompanied by an "IEC"
message.
Very Important: The complete list of QSAM return and reason codes can be found in the
IBM publication Macro Instructions for Data Sets for your system's level of DFP or
DFSMS. ABEND codes and "IEC" messages are documented in one or more MVS
messages and code publications.
Note: The return and reason codes (including ABEND codes) produced by the QSAM
functions are all decimal (not hexadecimal) values.
Service Descriptions
The sections that follow describe the syntax and operation of the QSAM-related
functions.
CLOSE (QSAM)
Syntax:
CLOSE(ddname)
Arguments:
ddname is the 1 to 8 character name that identifies the data set you want to
process. The data set associated with the ddname needs to have been
previously opened (using the OPEN function) by the program that is
closing it. If you attempt to close a ddname that has not been opened (or
has already been closed) the request is ignored and no error indication is
given.
Module Name:
RXTCLOSE
Environments:
All REXX/MVS environments.
Service Description:
CLOSE completes I/O operations, updates VTOC information, and disconnects your
program from the data set.
Returned Information:
The CLOSE function returns the QSAM CLOSE macro return code. If you CALL the
CLOSE function, the returned value is contained in the RESULT special variable.
After completion of a CLOSE function call, several special REXX variables are populated
with useful information. You should treat these variables as "read only" and make no
attempt to modify any of them. The variables are:
QSAM Functions 35
RC Contains the QSAM CLOSE return code. An RC of zero means the
operation was completed successfully.
REASON Contains the QSAM CLOSE reason code. If the file was already closed
or has never been opened, a value of 1 is returned in REASON.
Examples:
1. Close a data set:
if close('indd') = 0 then say 'Data set closed.'
2. Close a data set using CALL:
call close 'outdd'

if rc <> 0 then do
exit 8
end
GET (QSAM)
Syntax:
GET(ddname)
Arguments:
process. This name needs to have been previously associated with the
data set, either via the ALLOCATE command or JCL DD statement, and
opened via the OPEN function.
Module Name:
RXTGET
Environments:
The GET function is used to retrieve records from sequential data sets (permanent and
temporary), SYSIN data sets, and PDS members. Before you can use the GET function
you must first allocate and open (using the OPEN function) the data set associated with
the ddname argument. If you do not, an error will occur. Each invocation of GET
retrieves the next record (or an end-of-file indication if there are no more records).
GET also is used to update records. If you wish to update records, you must OPEN the
ddname using the 'UPDATE' option. After you have read a record using GET, the next
PUT will re-write the record to the file.

The GET function, if successful, returns the record requested. If the GET request fails, a
null string (zero length) is returned. If the GET function is CALLed, the REXX special
variable, RESULT, will contain the returned record.
After completion of a GET function call, the RC and REASON variables will contain return
code information. You should treat these variables as "read only" and make no attempt to
modify any of them. The variables are:
RC Contains the QSAM GET return code. An RC of zero means the

operation was completed successfully. A return code of 8 indicates that
no more records are available (end-of-file).
REASON Contains the QSAM GET reason code.
Examples:
1. Sequentially retrieve records from a data set:
record = get('indd')
do while rc = 0
parse var record 22 ssn +11 lname +10 fname +10
say left(fname,10) left(lname,10) left(ssn,11)
end
2. Count the records of a RECFM=FB data set. We can use the fact that a zero-length
record is impossible to simplify our logic:
i=0; do while get('indd')<>''; i=i+1; end
OPEN (QSAM)
Syntax:
OPEN('QSAM',ddname[,option])
Arguments:
'QSAM' indicates that the QSAM access method is to be used to open the file.
This argument must be coded as shown.
data set, either via the ALLOCATE command or JCL DD statement. If
you try to open a ddname that is already open, the request is ignored
and no error indication is given.
Note: The names 'VSAM', 'QSAM', and 'BPAM' are reserved. Do not use
these strings for ddnames.
QSAM Functions 37
option one of the following values may be used:
'INPUT' indicates that records will be read, only. This is the default.
'OUTPUT' indicates that records will be written, only.
'UPDATE' indicates that records will be read, and that some or all records
may be re-written.
Module Name:
RXTOPEN
Environments:
OPEN is used to "connect" your program to a data set. You must open a data set before
you can get (using the GET function) records from the data set, or put (using the PUT
function) records into the data set. All data sets should be closed (using the CLOSE
function) when you are finished using them.
Note: The REXXTOOLS/MVS QSAM interface is in no way connected with the REXX
EXECIO command.
The OPEN function returns the QSAM OPEN macro return code. If you CALL the OPEN
function, the returned value is contained in the RESULT special variable.
After completion of an OPEN function call, the RC and REASON variables will contain
return code information. Several other variables are also produced. You should treat
these variables as "read only" and make no attempt to modify any of them. The variables
are:
RC Contains the QSAM OPEN return code. An RC of zero means the

REASON Contains the QSAM OPEN reason code.
$RXTRECFM Indicates the record format of the data set.
$RXTLRECL Specifies the maximum record length of records in the opened data set.
$RXTBLKSI Specifies the maximum length of a block for the data set.
$RXTBUFNO Specifies the number of BLKSIZE-sized buffers that will be used in

performing input/output operations.
Examples:
1. Allocate and open a sequential file for read access:

"alloc fi(indd) da(user.data) shr reu"
if open('qsam','indd') <> 0 then say 'Open failed.'
Note that no option is specified because 'INPUT' is the default.
2. Allocate and open a PDS member for update access:
"alloc fi(iodd) da(mypds.data(stuff)) shr reu"

call open 'qsam', 'iodd', 'update'
if rc <> 0 then say 'Open failed. REASON='reason
PUT (QSAM)
Syntax:
PUT(ddname,recin)
Arguments:
recin contains the record to be written or updated. For varying length record
formats, the interface will record the actual record length up to the
maximum LRECL. Records that exceed the maximum length are
truncated on the right.
For fixed length record formats, the record will be padded with blanks or truncated on the
right to make it fit the fixed record size.
When updating records -- both varying length and fixed length -- the interface will force
the replacement record to the exact size of the original record, padding or truncating as
necessary.
Module Name:
RXTPUT
Environments:
The PUT function is used to write or update records of sequential data sets (permanent
and temporary), SYSOUT data sets, and PDS members. Before you can call the PUT
function you must first allocate and open the data set associated with the ddname
argument. If you do not, an error will occur. When open for output, PUT writes records
sequentially (i.e., you cannot skip record slots).
QSAM Functions 39
If you are using PUT to update a record, you must first retrieve the record using the GET
function. When updating a file, you do not need to update every record.
The PUT function returns the QSAM PUT macro return code. If you CALL the PUT
After completion of a PUT function call, the RC and REASON variables will contain return
RC Contains the QSAM PUT return code. An RC of zero means the

REASON Contains the QSAM PUT reason code.
Examples:
1. Sequentially retrieve and update all of a data set's records:
do while rc = 0
parse var record firstpart 10 salary 15 lastpart
newsal = p2d(salary,2) * 1.1
newrec = firstpart || d2p(newsal,5) || lastpart
call put 'iodd', newrec
if rc = 0 then record = get('iodd')
end
2. Add records to the end of a sequential data set:
"alloc fi(moddd) da(user.data) mod"

call open 'qsam', 'moddd', 'output'
say 'Enter a new record:'; parse pull record
call put 'moddd', record
end

BPAM Functions
BPAM, which stands for Basic Partitioned Access Method, is used to process Partitioned
Data Sets (PDS). Partitioned Data Set Extended (PDSE) data sets may also be accessed
with BPAM. Unlike QSAM, BPAM permits multiple PDS members to be processed with
just one OPEN/CLOSE sequence. Because of this, and because BPAM has functions for
managing PDS/PDSE directories, it is often the preferred method for processing
partitioned data sets.
Getting Started
The best way to learn REXXTOOLS BPAM programming is to read, execute, and modify
existing programs. To get you off to a fast start, Open Software has provided several
BPAM programs in the sample library. All of the BPAM samples begin with "BPAM"
followed by a number. Each program contains commentary explaining the techniques
demonstrated.
Before reading this chapter, you should take a few moments to locate these programs,
examine and run them.
Notes:
1. You must run the BPAM01 exec first. This program creates partitioned data sets that
are used by other BPAM sample execs.
2. There are other examples of BPAM programming in the sample and exec libraries:
o REXXTOOL.SAMPLIB(PDSCLEAR) is a utility for clearing (deleting) all

members from a PDS or PDSE.
o REXXTOOL.EXEC(RXTRXPP) is a pre-processor for the REXX compiler. It uses

the BPAM interface to include the source of REXX subroutines and functions into
the body of a main REXX program.
BPAM Basics
Using BPAM you can access a partitioned data set (PDS) or a partitioned data set
extended (PDSE). A partitioned data set is similar to a physical sequential data set,
however, the data is partitioned into discrete segments called members. A portion of a
PDS's space is reserved for a directory containing information that is used by the
operating system to locate a member's storage. A member's location is recorded in TTR
format, where "TT" is 2 bytes identifying the track and "R" is a single byte identifying the
block.
When a member is added to a PDS, an entry for the member is inserted into the
directory. Entries in the directory are ordered by member name in ascending sequence.
Only one user at a time can add a member to a PDS.
A member's records can be updated in place. However, the only way to extend a
member is to completely rewrite it (i.e., DISP=MOD will not cause records to be added to
BPAM Functions 41
the end of a member as it does with sequential files). The same holds true for selective
deletion of records: you must re-write the member while excluding those records that you
no longer want.
When a member is deleted from a partitioned data set, its entry is removed from the
directory. However, the space previously occupied by the member's records cannot be
reused until the data set is "compressed" by a utility such as IEBCOPY.
PDSE data sets, from a usage standpoint, are identical to partitioned data sets, but with
additional capabilities. Most importantly, PDSEs permit multiple users to write to a data
set simultaneously (though each user must be writing a different member). PDSEs also
reuse storage that is freed by member deletions, and thus, do not require periodic
compression.
When using BPAM to read a partitioned data set member or members, you must allocate
the data set without specifying a member name. A special function, FINDM, is used to
position to a member prior to reading it. When creating a new member, the STOWM
function is used to create a directory entry after all of the member's records have been
written.
Partitioned and partitioned extended data sets can reside only on DASD. In addition,
PDSEs must be managed by DFSMS.
Record Formats
The records in partitioned data sets can take several forms:
• The records can all be same length or they can be varying lengths.
• The records can be grouped into blocks. The system uses the blocks when
performing physical input/output operations to improve performance. If the records
are not blocked, each physical record contains exactly one logical record.
• If desired, printer control characters can be placed in the first byte of each record.
The REXXTOOLS BPAM functions support the following formats (RECFMs):
F FA FB FBA FBM FM
V VA VB VBA VBM VM
U UA UM
The individual letters of RECFM indicate the following:
F Fixed length records.
V Variable length records.

U Undefined length records. From a logical record perspective, U format is similar
to variable length records, but the records cannot be blocked.
B Blocked records.
A ANSI printer control characters are in the first byte of each record.
M Machine printer control characters are in the first byte of each record.
For information regarding the selection of an appropriate data set organization and record
format refer to the IBM publication Using Data Sets for your system's level of DFP or
DFSMS.
Note: PDS and PDSE data sets cannot be defined with RECFM=FS or RECFM=FBS
(spanned records).
Programming For BPAM

The basic flow of a program that processes a data set using BPAM is as follows:
1. Allocate the file. A Data Definition Name (DDNAME) is associated with the data set you
wish to process. Do not specify a member name for the data set. Use a status of NEW or
OLD if you are creating or updating members. Use a status of SHR if you are reading
members.
Note: You can concatenate multiple partitioned data sets to a single ddname for reading
only. When searching for a member using FINDM, the first occurrence of the member
name in the concatenation of partitioned data sets is the one that will be located.
logical connection between your program and the data set to be accessed. If you are
reading the file use the INPUT option on OPEN. If you are writing the file, use the
OUTPUT option. If you are updating records in place, use the UPDATE option.
3. If you are reading or updating a member, use the FINDM function to position to the
member, and optionally, to retrieve the member's directory entry. If you want to process
all of the members in a PDS, use the REXXTOOLS LISTM function to obtain a list of
member names.
4. Read a record from the file using GET or write a record to the file using PUT. When
reading, the GET function returns the record's contents. You can assign the record to a
REXX variable (or variables if you use PARSE VALUE). If the data set is blocked, the
access method handles deblocking. Your program processes logical records only (not
physical records). A return code of 8 indicates that there are no more records to be read.
When writing records, the PUT function accepts the record to be written as an argument.
PUT handles any blocking that may be required, and writes physical blocks to the file as
required.
5. If you are reading records, determine what processing applies to the record (if any) and
perform the processing. If the data set was opened for update, the record can be
replaced. Record deletion is not possible. To delete a record, or to add new records, the
entire PDS member must be rewritten. For information regarding the processing of record
fields, please see "Working with Record Fields".
BPAM Functions 43
7. If you are writing or re-writing a member, use the STOWM function to update the
directory with the member name and its location (the operating system determines the
location). You also may use STOWM to store user information in the directory entry. If
any physical writes are pending when you issue STOWM, these are completed prior to
updating the directory.
8. If appropriate, return to step 3 to process other members.
9. Close the file using the CLOSE function. Any pending physical writes are completed, and
the logical connection between the program and the data set is terminated.
Allocating Data Sets

If the program is to be run in the batch environment, the JCL Data Definition (DD)
statement may be used to allocate the data set. If dynamic allocation is required in the
batch environment, the REXXTOOLS ALLOCATE and FREE commands can be used. If
the program is running under TSO (either batch or interactive), either the TSO or the
REXXTOOLS ALLOCATE and FREE commands can be used.
Opening and Closing Data Sets

To associate your program with the data set you want to process, you use the OPEN
function. The CLOSE function performs the opposite action by disassociating your
program with the data set.
REXXTOOLS/MVS maintains information about open BPAM files in a data structure

All REXX programs under a MVS task share the same REXXTOOLS BPAM data
task termination` will close all files opened by program B.
Notes:
1. If you have installed the exec termination exit (which is not recommended), files will
be closed whenever the exec that opened them terminates.
2. A PDS supports only one writer at a time. If you need to support multiple
simultaneous writers, you must use a PDSE.

OPEN Options
When opening a data set using BPAM, you may specify two types of options which affect
processing. These are:
Type of Access
The REXXTOOLS BPAM interface supports 3 access options:
INPUT indicates that you will be reading records from the data set. Data sets
that are open for input can be accessed with the FINDM and GET
functions only. The data set can be allocated with a status of OLD or
SHR (preferred).
OUTPUT indicates that you will writing records to the data set. Data sets that are
open for output can be accessed with the PUT and STOWM functions
only. The data set should be allocated DISP=OLD.
UPDATE indicates that you will be reading the data set, and that you may be re-
writing none, some, or all records. A record must be read before it can be
re-written. When open for update, a data set can be accessed with the
FINDM, GET, PUT, and STOWM functions. The data set should be
allocated DISP=OLD.
DCB Parameters
Record format (RECFM), logical record length (LRECL), block size (BLKSIZE), and
number of buffers (BUFNO) can be specified on OPEN. However, with rare exception,
you are much better off letting the operating system derive these values for you. For new
data sets, the information can be derived from allocation information that is kept in
memory. For existing data sets, the information is taken from the Volume Table of
Contents (VTOC).

The REXXTOOLS/MVS BPAM functions for access to records and directory entries are:
FINDM The FINDM function is used to locate a member's position on DASD for
reading or updating records. Optionally, the member's directory entry
user field may be retrieved.
GET The GET function is used to retrieve records sequentially. GET returns a
logical record as its value (or a null string if an error was encountered).
PUT The PUT function is used to sequentially write or re-write records. PUT
accepts a record as one of its arguments. If the PUT follows a GET
where the file has been opened for update, the record that was retrieved
by the GET will be replaced. In all other cases, PUT is interpreted as a
request to add a new record.
STOWM The STOWM function is used to add, replace, or remove a member's

directory entry. STOWM also can be used to add, replace, or remove a
member alias. Optionally, the member's directory entry user field can be
created or updated.
BPAM Functions 45
Input Processing
Using the INPUT option of OPEN, you can read some or all of a member's records. In the
following example, a PDS member is read:
/* REXX */
address rexxtool
"alloc fi(indd) da(user.data) shr"
if open('bpam','indd','input') <> 0 then do
exit 8
end
if findm('indd','timecard') <> 0 then do
say 'TIMECARD member not found.'
exit 8
end
do while rc = 0
parse var timerec lname +10 fname +10 timein +8 timeout
+8
end
call close 'indd'
"free fi(indd)"
Output Processing
Using the OUTPUT option of OPEN, you can create one or more members. In the
following example, multiple members may be created:
/* REXX */
address tso
"alloc fi(outdd) da(user.data) new sp(1 1) track",
"dsorg(po) recfm(v b) lrecl(255) dir(10) unit(sysda)"
call open 'bpam', 'outdd', 'output'
say 'Enter member name or ENTER to quit.'; parse pull
member
do while member <> ''
say 'Enter records. Terminate with a null line.'
parse pull record
parse pull record
end
call stowm 'outdd', member
say 'Enter member name or ENTER to quit.'; parse pull
member
end
call close 'outdd'
"free fi(outdd)"

Update Processing
Using the UPDATE option of OPEN, you can replace some or all of a member's records.
You may not, however, add new records or remove existing records. The interface
ensures that replacement records are the same size as the original record. If the
replacement record is smaller than the original, the record is padded on the right with
blanks. If it is larger than the original record, the replacement record is truncated on the
right. No error indication is given in either case.
In the following example, all of a PDS's members are updated. A 2-byte packed decimal
date field in YY format is converted to a 2-byte binary date that contains the century.
/* REXX */
dsn = "'crude.royalty.data'"
parse value listm(dsn) with rc mc mlist
address rexxtool "alloc fi(iodd) da("dsn") old"
call open 'bpam', 'iodd', 'update'
do i = 1 to mc
parse var mlist member mlist
call findm 'iodd', member
parse value get('iodd') with type +1 1 record
do while rc = 0
if type = 7 then do
parse var record first +25 date +2 last
call put 'iodd', first||d2c(p2d(date)+1900,2)||last
end
parse value get('iodd') with type +1 1 record
end
end
call close 'iodd'
address rexxtool "free fi(iodd)"
exit
Notes:
1. LISTM is a REXXTOOLS function for retrieving member names. P2D is a

REXXTOOLS function for converting packed decimal data to REXX decimal.
2. For more information on record parsing refer to "Appendix A: Working with Record
Fields" on page 279.
BPAM Functions 47
Extend Processing
Unlike sequential files, partitioned data sets can not be extended using DISP=MOD. To
add records to a member (or remove records), you must completely re-write the member
and use STOWM to update the directory, as the following example demonstrates:
/* REXX */
/* First, allocate and open the file 2 times,

once for input and once for output */
"alloc fi(indd) da(user.pds) shr reu"
"alloc fi(outdd) da(user.pds) old reu"
call open 'bpam', 'indd', 'input'
/* Next, copy the existing records */

call findm 'indd', 'member1'
do while rc = 0
end
/* Now, add some new records */

do i = 1 to 10
call put 'outdd', 'New record' i
end
/* Last, replace the directory entry */

call stowm 'outdd', 'member1', 'r'
call close 'indd'
call close 'outdd'
"free fi(indd outdd)"
exit
Note: Using this method you can add records anywhere in the member, not just on the
end. You can also omit records on the copy step, thereby deleting them.
Sharing PDSE Members

A PDSE permits multiple tasks to write to and read from the data set at the same time. To
use PDSE sharing, ensure that all accessors allocate the PDSE using DISP=SHR (If a
component of your application requires exclusive use of the entire data set, you can use
DISP=OLD to lock-out other users).
A "connection" to a member is established whenever you use the FINDM function. The
length of the connection is determined as follows:
1. If the M function is used, the FINDM function executes a FIND by name. This
establishes a connection that lasts until a subsequent FINDM (for the same ddname)
is executed or the data set is closed.

2. If the T function is used, the FINDM function executes a FIND by TTR. The
connection established lasts until the data set is closed.
3. If the S or U functions are used, the FINDM function executes a BLDL for the
member, followed by a FIND by name. Because the BLDL is issued without the
NOCONNECT option, a connection is established that lasts until the data set is
closed.
Once a program has connected to a member, a temporary version of that member is

created and remains in existence until the connection is severed, even though
another user may re-write or delete the member.
For a detailed description of PDSE member sharing refer to the Using Data Sets
publication for your system's level of DFP or SMS.
Sharing PDS Members

If your application requires many users to access a partitioned data set concurrently, you
should use a PDSE instead of a PDS. As discussed in the previous section, PDSEs
provide built-in support for sharing members. If for some reason your application cannot
use a PDSE, it is possible to share PDS members, although a little more programming is
required.
One way of protecting a PDS while maintaining a relatively high degree of concurrency is
to use the REXXTOOLS ENQ and DEQ functions to implement an access protocol. A
simple, but effective, protocol follows:
1. All parties agree to allocate the PDS using DISP=SHR. Certain tasks that require
exclusive control of the data set (for example, data set compression jobs or 3rd shift
batch update jobs) must use DISP=OLD. Any task that uses DISP=OLD does not
need to follow the rest of the protocol.
2. Prior to reading a member, a shared enqueue on the data set (not just the member)
must be obtained. Any queue name (qname) can be chosen, but all parties must use
this name when obtaining the enqueue. The rname should be the data set name
without a member name. When the member has been read, the enqueue is released.
Ideally, the ENQ should precede the FINDM for the member, and the DEQ should
follow the last GET.
Note: If you are using the REXXTOOLS LISTM function to read the directory, its
operation also must be shielded with a shared enqueue.
3. Prior to writing a member, an exclusive enqueue on the data set must be obtained.
When the member has been written, the enqueue is released. Again, the qnames
and rnames must be used consistently by all parties. The ENQ should precede the
first PUT (or the first GET if the member is being updated) and the DEQ should follow
the call to STOWM, if applicable.
4. In all cases, the reading and writing of members should proceed expeditiously to
ensure a high degree of concurrency.
Note that whenever an application has the capacity to change a PDS directory (i.e.,
the application contains STOWM function calls) or opens a PDS for output, an
BPAM Functions 49
enqueue for the entire data set must cover every input/output operation. If a data set-
wide enqueue is not obtained for all I/O operations, multiple tasks can write to the
data set's free space or to the directory at the same time, irreparably damaging
your data. In addition, program abends can occur when a task attempts to read a
directory while it is being written to by another task.
If your application is structured so that new members are not created and existing
members are not extended (that is, the PDS is pre-formatted, and the only type of write
operation performed is an update-in-place), you can increase concurrency by narrowing
the scope of your enqueues to include specific member names. However, if your
application uses STOWM to update the user field of directory entries, you still must use
data set-wide enqueues.
If your application requires a "browsing" function, where information from one or more
members is displayed to a user for the purpose of subsequent update, the protocol must
be modified slightly in order to maintain a high degree of concurrency while protecting the
data set:
1. As before, all parties use DISP=SHR.
2. As before, all read operations are bracketed with a shared enqueue.
3. As before, all write operations are bracketed with an exclusive enqueue.
4. No enqueue is held while the data is being browsed. This prevents, for example,
other users from being locked-out while a user who is browsing is away from his
terminal.
5. Prior to applying modifications to browsed data, the application obtains an exclusive

enqueue and re-reads the data. A comparison is made of the re-read data and an un-
modified copy of the data as it was originally read. If the comparison indicates that
the data has not been modified by another user during the period in which it was
browsed, the changes are applied, and the exclusive enqueue is released. Otherwise
-- if the comparison indicates that another user has modified the data -- the enqueue
is released and the re-read data is displayed, along with a notification that the user's
changes were not applied.
Again, the scope of the enqueues used depends, entirely, on whether or not the directory
can be updated by the application. If the directory can be updated by the application, data
set-wide enqueues must be used. If not, member-specific enqueues can be used.

BPAM Return Codes
Upon completion, all REXXTOOLS/MVS BPAM functions provide a return code and a
In addition, except for the GET function which returns a record, all BPAM functions return
code 2 times, once as OPEN's returned value, and once as the value of the RC variable
say "RC="open('bpam','indd','input') "RC="rc

"REASON="reason
underlying BPAM macro return and reason codes. In all cases, a return code of zero
indicates success.
In the case of GET and PUT, the underlying BPAM macros (READ, WRITE, and CHECK)
do not produce return codes. The REXXTOOLS GET function returns RC=8 when end-
of-file is reached. All other non-zero GET and PUT return codes are either ABEND codes
(which are accompanied by an "IEC" message) or synchronous error exit codes (which
are accompanied by a "RXT" message).
Very Important: The complete list of BPAM return and reason codes can be found in the
IBM publication Macro Instructions for Data Sets for your system's level of DFP or
DFSMS. ABEND codes and "IEC" messages are documented in one or more MVS
messages and code publications.
Note: The return and reason codes (including ABEND codes) produced by the BPAM
BPAM Functions 51
The sections that follow describe the syntax and operation of the BPAM-related functions.
CLOSE (BPAM)
Syntax:
CLOSE(ddname)
Arguments:
given.
Module Name:
RXTCLOSE
Environments:
CLOSE completes I/O operations, updates VTOC information, and disconnects your
program from the data set.
The CLOSE function returns the BPAM CLOSE macro return code. If you CALL the
RC Contains the BPAM CLOSE return code. An RC of zero means the operation
was completed successfully.
REASON
Contains the BPAM CLOSE reason code. If the file was already closed or has
never been opened, a value of 1 is returned in REASON.

Examples:
2. Close a data set using CALL:
call close 'outdd'

if rc <> 0 then do
exit 8
end
FINDM (BPAM)
Syntax:
FINDM(ddname,{member|ttr}[,option])
Arguments:
member is the 1 to 8 character name that identifies the member you want to
process. The system searches the PDS directory for this name to
determine the member's address.
The second argument is treated as a member name for all values of

option except 'T'.
ttr is the 6 byte printable hexadecimal address (in TTR format) of the
member you want to process. The system does not search for the
member. It uses the TTR value to directly position to the member. A
member's TTR can be obtained from the FINDM, STOWM, and LISTM
functions.
Note: This argument must be exactly 6 bytes long. The TTRs produced
by LISTM, FINDM, and STOWM are in the proper format.
option indicates the type of the second argument (member or ttr), and
determines the type of processing required. The valid options are:
'M' indicates member name find only. The system establishes position so
that subsequent GETs read records from the member. No directory
information is returned. This is the default.
'T' indicates positioning by TTR. The second argument must be a valid TTR
address for a member. The system establishes position so that
BPAM Functions 53
subsequent GETs read records from the member. No directory
information is returned.
'U' indicates member name positioning (see 'M' above) and in addition, the
system retrieves directory information for the member. The directory
entry's user field is returned, unformatted.
'S' indicates member name positioning (see 'M' above) and in addition, the
system retrieves directory information for the member. If the directory
entry's user field contains syntactically valid ISPF statistics, FINDM
formats and returns this information.
Module Name:
RXTFINDM
Environments:
FINDM is used to position for reading a PDS/PDSE member. Optionally, FINDM will
retrieve the member's directory information. If the file has been opened for update, and
one or more PUTs to a member have been executed, FINDM will complete pending write
operations, prior to finding the next member.
FINDM can be used only if the file has been opened for input or update. It is an error to
use FINDM with a file that is open for output. You must close and re-open the file for
input or update.
Note: FINDM establishes a connection to a PDSE member.
The FINDM function returns a string containing different values, depending on the value
of option and the success of the operation.
• If a non-zero return code is encountered, only the return code is returned, regardless
of the option. The return code is taken directly from the FIND or BLDL macros.
• If the return code is zero and option 'M' or 'T' is used, only the return code is returned.
• If the return code is zero and option 'U' is used, the following information is returned:
rc the return code.
ttr the address of the member in TTR format (TT=Track; R=Record). This
value can be used in subsequent FINDM calls to reposition to the
member (provided the member's position does not change!).
k the concatenation number of the data set containing the member. The
first (or only) data set in a concatenation of data sets has a "K" value of
zero.

z the "where found" indicator. The following values are possible:
0 Private library
1 Link library
2 Job, task, or step library
3-255 Job, task, or step library of parent task n, where n = z-2
c the alias indicator. If '0' the directory entry is not an alias. If '1' the
directory entry is an alias.
userfield
the user field of the directory entry. This field can be 0 to 62 bytes long.
The data may contain any values, including blanks.
• If the return code is zero and option 'S' is used, the following information is returned:
rc the return code.
ttr the address of the member in TTR format (TT=Track; R=Record). This
value can be used in subsequent FINDM calls to reposition to the
member (provided the member's position does not change!).
k the concatenation number of the data set containing the member. The
first (or only) data set in a concatenation of data sets has a "K" value of
zero.
z the "where found" indicator. The following values are possible:
0 Private library
1 Link library
2 Job, task, or step library
3-255 Job, task, or step library of parent task n, where n = z-2
c the alias indicator. If '0' the directory entry is not an alias. If '1' the
directory entry is an alias.
vv ISPF version number. Valid range: 00- 99.
mm ISPF modification level. Valid range 00-99.
cdate ISPF creation date in CCYY.DDD format (Julian date with 4-digit year).
mdate ISPF modification date in CCYY.DDD format (Julian date with 4-digit
year).
mtime ISPF modification time in HH:MM:SS format.
cl ISPF current lines.
il ISPF initial lines.
ml ISPF modified lines.
BPAM Functions 55
muserid
ISPF last modification user ID.
Very Important: The ISPF statistics are taken from the member's directory entry. The
system does not verify that the values are accurate. If the interface does not find
syntactically valid ISPF statistics, items vv through muserid will be null. No other error
indication is given.
If you CALL the FINDM function, the returned value is contained in the RESULT special
variable.
After completion of a FINDM function call, several special REXX variables are populated
RC Contains the FIND or BLDL return code. An RC of zero means the

REASON
Contains the FIND or BLDL reason code.
Examples:
1. Position to a member:
if findm('indd','payroll') = 0 then do
/* read the member */
end
2. Position to a member using its TTR:
if findm('indd','0003A9','t') = 0 then do
end
3. Position to a member and retrieve its directory entry in "user" format:
parse value findm('indd','payroll','u') with,

rc ttr k z c usrfld
if rc = 0 then do
end
4. Position to a member and retrieve its directory entry in ISPF format:
parse value findm('indd','payroll','s') with,

rc ttr k z c vv mm cdate mdate mtime cl il ml uid
if rc = 0 then do
end

GET (BPAM)
Syntax:
GET(ddname)
Arguments:
Module Name:
RXTGET
Environments:
The GET function is used to retrieve records from PDS/PDSE members. Before you can
use the GET function you must first allocate and open (using the OPEN function) the data
set associated with the ddname argument. In addition, the FINDM function must be used
to position to the member. GET is used to retrieve records sequentially (i.e., you can't
skip records - but you can read past them).
GET also is used to update records. If you wish to update records, you must OPEN the
ddname using the 'UPDATE' option. After you have read a record using GET, the next
PUT will re-write the record to the file.
You may use GET only if the file has been opened for input or update. If the file is open
for output, you must close and re-open it for input or update.
RC Contains the BPAM GET return code. An RC of zero means the operation was
completed successfully. A return code of 8 indicates that no more records are
available (end-of-file).
REASON
Contains the BPAM GET reason code.
BPAM Functions 57
Example:
1. Sequentially retrieve records from a PDS member (EMPLOYEE) starting with the first
record:
"alloc fi(indd) da(user.pds) shr reu"

call open 'bpam', 'indd', 'input'
call findm 'indd', 'employee'
do while rc = 0
parse var record 22 ssn +11 lname +10 fname +10
say left(fname,10) left(lname,10) left(ssn,11)
end
call close 'indd'
OPEN (BPAM)
Syntax:
OPEN('BPAM',ddname[,option])
Arguments:
'BPAM' indicates that the BPAM access method is to be used to open the file.
data set, either via the ALLOCATE command or JCL DD statement. If
you try to open a ddname that is already open, the request is ignored
and no error indication is given.
Note: The names 'VSAM', 'QSAM', and 'BPAM' are reserved. Do not use these strings
for ddnames.
option the following values may be used:
'INPUT' indicates that records will be read, only. This the default.
'OUTPUT' indicates that records will be written, only.
'UPDATE' indicates that records will be read, and that some or all records
may be re-written.
Module Name:
RXTOPEN
Environments:

you can perform any other operations (FINDM, GET, PUT, STOWM). All data sets should
be closed (using the CLOSE function) when you are finished using them.
Note: The REXXTOOLS/MVS BPAM interface is in no way connected with the REXX
EXECIO command.
The OPEN function returns the BPAM OPEN macro return code. If you CALL the OPEN
function, the returned value is contained in the RESULT special variable. After
completion of an OPEN function call, the RC and REASON variables will contain return
code information. Several other variables are also produced. You should treat these
variables as "read only" and make no attempt to modify any of them. The variables are:
RC Contains the BPAM OPEN return code. An RC of zero means the

REASON Contains the BPAM OPEN reason code.
$RXTRECFM Indicates the record format of the data set.
$RXTLRECL Indicates the maximum record length of records in the opened data set.
$RXTBLKSI Indicates the maximum length of a block for the data set.
$RXTBUFNO Indicates the number of BLKSIZE-sized buffers that will be used in

performing input/output operations.
Examples:
1. Allocate and open a PDS for read access:
"alloc fi(indd) da(mypds.data) shr reu"

if open('bpam','indd') <> 0 then say 'Open failed.'
Note the following:
1. No option is specified because 'INPUT' is the default.
2. A member name is not specified on the ALLOC. Prior to reading a member, the
FINDM function must be used.
BPAM Functions 59
PUT (BPAM)
Syntax:
PUT(ddname,recin)
Arguments:
recin contains the record to be written or updated. For varying length record
formats, the interface will record the actual record length up to the
maximum LRECL. Records that exceed the maximum length are
truncated on the right.
For fixed length record formats, the record will be padded with blanks or truncated on the
right to make it fit the fixed record size.
When updating records -- both varying length and fixed length - the interface will force the
replacement record to the exact size of the original record, padding or truncating as
necessary.
Module Name:
RXTPUT
Environments:
The PUT function is used to write or update records of PDS/PDSE members. Before you
can call the PUT function you must first allocate and open the data set associated with
the ddname argument. If you are creating a new member, the last PUT must be followed
by a STOWM function to create the directory entry.
function. All other PUT requests are treated as write requests.
You may use PUT only if the file has been opened for output or update. If the file is open
for input, you must close and re-open it for output or update.

The PUT function returns the BPAM PUT macro return code. If you CALL the PUT
After completion of a PUT function call, the RC and REASON variables will contain return
RC Contains the BPAM PUT return code. An RC of zero means the

REASON
Contains the BPAM PUT reason code.
Examples:
1. Sequentially retrieve and update all of a member's records:
"alloc fi(iodd) da(mypds.data) old"

call findm 'iodd', 'payroll'
do while rc = 0
end
2. Create a new member:
"alloc fi(outdd) da(mypds.data) old"

end
call stowm 'outdd', 'mem01'
call close 'outdd'
BPAM Functions 61
STOWM (BPAM)
Syntax:
STOWM(ddname[,member][,function][,{newname|ttr}]
[,{userfield|vv}][,mm][,cdate][,mdate]
[,mtime][,cl][,il][,ml][,muserid])
Arguments:
member is the 1 to 8 character name that identifies the member the directory
entry of which you want to create or update.
The member argument is required for all values of function except 'I.'
function determines the type of processing required. The valid values are:
'A' adds a directory entry. The entry can be a primary entry or an alias (see
ttr below). This is the default.
'C' changes a directory entry (see newname below).
'D' deletes a directory entry. This deletes the member. When deleting a
primary entry for a member of a PDSE, all aliases are also deleted.
'I' initializes a PDSE directory (deletes all members). This function cannot
be used with a PDS.
'R' replaces a directory entry. The entry can be a primary entry or an alias
(see ttr below).
For PDSE data sets, any user that is connected to a member can still
access their version until the connection is broken. That is, directory
modifications by one user are invisible to other connected users until
they disconnnect from the member and reconnect. See the Using Data
Sets publication for your level of DFP or DFSMS for more information.
newname is the 1 to 8 character new member name. This argument is used with
the 'C' (change) function only.
ttr is the 6 byte printable hexadecimal address (in TTR format) of the
member for which you want to create (or replace) an alias. A member's
TTR can be obtained from the FINDM, STOWM, and LISTM functions.
Note: This argument must be exactly 6 bytes long. The TTRs produced
by LISTM, STOWM, and FINDM are in the proper format.

userfield is 0 to 62 bytes of user-specified data. Any values may be used. The
interface always forces this argument to be an even number of bytes. If
you pass an odd number of bytes, a byte of binary zeros will be
appended to the right. Also, if you pass more than the maximum number
of bytes, the argument is truncated on the right. No error indication is
given.
Note: If any arguments follow this argument, it is not interpreted as the

user field. It will be interpreted as the ISPF version number (see next
description).
vv is the ISPF version number. Valid range: 0-99.
mm is the ISPF modification number. Valid range: 0-99.
cdate is the ISPF creation date. The only valid format is CCYY.DDD (e.g., 1997.050).
Any syntactically valid date is accepted. See the examples below.
mdate is the ISPF modification date. The only valid format is CCYY.DDD (e.g.,
1997.050). Any syntactically valid date is accepted. See the examples below.
mtime is the ISPF modification time. The only valid format is HH:MM:SS. Any
syntactically valid time is accepted. See the examples below.
cl is the ISPF current lines value. Valid range: 0-65535. The system does not verify
that this value reflects the number of lines in the member.
il is the ISPF initial lines value. Valid range: 0-65535. The system does not verify
that this value is correct.
ml is the ISPF modified lines value. Valid range: 0-65535. The system does not
verify that this value is correct.
muserid
is the ISPF modification user ID. Any printable string 1-7 characters in length is
acceptable.
Module Name:
RXTSTOWM
Environments:
The STOWM function is used to maintain the directory of a PDS or PDSE data set.
Directory entries (both primary and aliases) can be added, renamed, replaced, and
deleted. A special function is provided for clearing the directories of PDSE data sets.
When it follows one or more PUT function calls, STOWM will complete all pending write
operations for the member. If the data set is open for output, STOWM will write an end-
BPAM Functions 63
of-file marker after the records of the member. If open for update, write operations are
completed, but no end-of-file marker is written.
You may use STOWM only if the file is open for output or update. If the file is open for
input, close and re-open it for output or update.
Notes:
1. STOWM will, in some cases, disconnect a user from a PDSE member version.
2. The 'I' function deletes all members of a PDSE. Be sure that you really want to do
this before using 'I'.
The STOWM function returns a string of information the format of which depends on the
value of function:
• If the 'A' or 'R' is specified, the return code and the system-derived TTR address of
the member are returned in the string (blank-delimited, return code first).
• For all other functions, only the return code is returned in the string.
If you CALL the STOWM function, the returned value is contained in the RESULT special
variable.
After completion of a STOWM function call, the RC and REASON variables will contain
return code information:
RC Contains the BPAM STOW return code. An RC of zero means the operation was
completed successfully. If you use the 'R' function and the member does not
exist, a return code of 8 is returned, but the directory entry is added.
REASON
Contains the BPAM STOW reason code.
Examples:
1. Create a new member (with one record). The 'A' function is assumed:

call put 'outdd', 'this is a record'
call stowm 'outdd', 'earl'
call close 'outdd'
2. Create an alias for a member:

parse value findm('iodd','earl','u') with rc ttr .
call stowm 'iodd', 'cathi', 'a', ttr
call close 'iodd'

3. Rename a member:

call stowm 'iodd', 'earl', 'c', 'josh'
call close 'iodd'
4. Replace a member's directory entry (the code translates all colons in the user field to
periods):

parse value findm('iodd','josh','u') with,
rc ttr k z c usrfld
usrfld = translate(usrfld, '.', ':')
call stowm 'iodd', 'josh', 'r', , usrfld
call close 'iodd'
5. Delete a member (or alias):

call stowm 'outdd', 'josh', 'd'
call close 'outdd'
6. Create a (empty) new member with ISPF statistics. This example shows how to
create date and time strings in the proper format. Note how the date and time
references are clustered on a single REXX clause. REXX guarantees that all
date/time references on a clause are consistent.

parse value date('s')||date('j')||time() with,
year +4 . +6 day +3 ctime
cdate = year'.'day
call stowm 'outdd', 'earl', 'a', , 1, 1, cdate,,
cdate, ctime, 0, 0, 0, userid()
call close 'outdd'
7. Delete all members of a PDSE:

call stowm 'outdd', , 'i'
call close 'outdd'
BPAM Functions 65
VSAM Functions
REXXTOOLS/MVS provides a collection of REXX functions for working with VSAM data
sets. The functions are closely modeled after the macro interface to VSAM. If you are
already familiar with programming for VSAM in assembler, you will have no trouble using
the REXXTOOLS/MVS VSAM functions. If you have never used the VSAM macros, you
will want to read the sections that follow before you start programming.
Additional background information on VSAM can be found in the Using Data Sets
publication for your system's level of DFP or DFSMS. Using Data Sets contains
descriptions of VSAM data sets and VSAM utilities, and VSAM programming guidance.
Getting Started
The easiest way to start using the REXXTOOLS/MVS VSAM interface is to examine, run,
and modify the VSAM-related programs of the sample library. The VSAM-related sample
members all begin with 'VSAM'. In these samples you will find ready-made applications
for reading and writing KSDS, ESDS, and RRDS data sets. The samples demonstrate
several techniques for building and parsing VSAM records, and provide examples of
report writing programs and multi-user ISPF applications.
Notes:
1. You must run the VSAM01 program before running any of the other VSAMxx
samples. VSAM01 creates the KSDS, ESDS, and RRDS data sets that are used by
the other VSAMxx programs.
2. VSAM01 and VSAM19 demonstrate how you set-up and use an alternate index.
VSAM Basics
VSAM, which stands for Virtual Storage Access Method, provides facilities for defining,
managing, and accessing 5 different types of data sets. These are:
KSDS Key-sequenced data sets. The records of this type of data set are maintained in
key-sequence order. The records of the KSDS may be of variable length, but the
key field is always in the same location and is always the same length.
KSDSs are made up of two components. The first is the data component; it
contains the actual data records of the data set. The second component is the
index. The index contains compressed key values and pointers into the data
component, and permits high-speed random access of records. There may be
only one index entry per data record (i.e., duplicate keys are not allowed). In
addition to the primary index, alternate indexes may be defined for and
associated with the data component. These alternate indexes permit random
access to the data component using fields other than the primary key field.
Alternate indexes, by default, permit duplicate keys.
Note: An example of creating and using an alternate index is contained in the

VSAM01 and VSAM19 sample execs.
VSAM Functions 67
KSDS records may be accessed both sequentially and directly (randomly).
Records may be inserted, both in between existing records and onto the end.
Records may also be deleted (erased) from the data set.
ESDS Entry-sequenced data sets. The records of the ESDS are maintained in the order
they are entered. As new records are added, they are always placed at the end
of the data set. They are never inserted into the middle. Moreover, once a record
has been added to an ESDS, it can never be deleted6. Like the KSDS, the ESDS
permits variable length records. But, the ESDS will not permit a record to grow or
shrink once it has been added. A replacement record must fit exactly over the old
record's space.
An ESDS may be accessed both sequentially and randomly. For random access,
a number called the Relative Byte Address (RBA) is used to specify the record
to retrieve. The RBA of a record can be obtained at the time it is inserted, or can
be determined by sequentially reading the data set.
Note: The REXXTOOLS interface automatically handles RBA values larger than
4G. You do not need to do anything to make this happen.
RRDS Relative record data set. The RRDS holds data that is accessed by the number
of the record. The RRDS supports only fixed length records. Records can be
inserted into the middle, or added onto the end of an RRDS. Records can also be
deleted.
The RRDS permits both sequential and random access. Random access is by
Relative Record Number (RRN), which is the sequence number of a record.
VRDS Variable-length relative record data set. The VRDS, like the RRDS, holds data
that is accessed by the number of the record. In addition, the VRDS also
supports variable length records. Records can be inserted into the middle, or
added onto the end of a VRDS. Records may also be deleted.
The VRDS permits both sequential and random access. Random access is by
Relative Record Number (RRN).
LDS Linear data set. This type of VSAM data set is used for the MVS Data-In-Virtual
(DIV) service. It is also used by DB2 to contain table-related data. Linear data
sets do not contain records in the same sense that KSDS, ESDS, and RRDS
data sets do. Because of this, the record- oriented services of VSAM cannot read
from or write to linear data sets. REXXTOOLS can, however, access linear data
sets by control interval (refer to the definition of control interval that follows).
VSAM data sets are organized first by records, then by control intervals (CIs) which
are collections of records; and then by control areas, which are collections of control
intervals. Using the processing options described in the sections that follow, you can
directly read from and write to VSAM data sets at the record and control interval levels.
You cannot read or write control areas.

Programming For VSAM
The basic flow of a program that processes VSAM files is essentially the same as the
flow of a program that processes sequential files. In general, such a program will contain
the following steps:
1. Allocate the file. A Data Definition Name (DDNAME) is associated with the data set
you wish to process.
logical connection between your program and the data set to be accessed.
Depending on the options you specify, your program can read, write, or update
records. You can also select direct or sequential processing.
3. Read a record from the file using the GET function, or write a record to the file using
the PUT function. If reading, the access method places the record's contents into a
variable or variables for the program to use. Using VSAM, an individual record can be
accessed directly without having to read through the records that precede it.
If you are writing records, the access method takes the record from an argument to
PUT.
4. Determine what processing applies to the record (if any) and perform the processing.
The program can replace the record's data with new information or request that the
access method remove the record from the data set. New records also may be added
to the data set. For information regarding the processing of record fields, please see
"Working with Record Fields."
6. Close the file using the CLOSE function. The logical connection between the program
and the data set is terminated.
Allocating VSAM Files

VSAM file allocation works just like sequential file allocation. If the program is to be run in
the batch environment, the JCL Data Definition (DD) statement may be used (you can,
however, specify additional parameters for VSAM files). If dynamic allocation is required
in the batch environment, the REXXTOOLS ALLOCATE and FREE commands can be
used. If the program is running under TSO (either batch or interactive), either the TSO or
the REXXTOOLS ALLOCATE and FREE commands can be used.
Opening and Closing VSAM Files

To associate your program with the VSAM data set you want to process, you use the
OPEN function. The CLOSE function performs the opposite action by disassociating your
program with the VSAM data set. Using the OPEN function you can connect your
program to an unlimited number of VSAM data sets.
REXXTOOLS/MVS maintains information about open VSAM files in a data structure

VSAM Functions 69
All REXX programs under a MVS task share the same REXXTOOLS VSAM data
task termination will close all files opened by program B.
Notes:
1. In address spaces where subtasks in a vertical chain (e.g., A attaches B; B attaches

C; etc.) are run asynchronously (i.e., the attaching task does not wait on the subtask),
it is the responsibility of the REXX programmer to ensure that requests to the same
ddname are serialized. The REXXTOOLS ENQ and DEQ functions may be used for
this purpose. For example, if A opens a file and attaches subtask B asynchronously,
A and B can share the file, but they must explicitly serialize their requests.
Between sibling subtasks there is more programming assistance. That is, if A

attaches B and C asynchronously, and if B and C each open the same ddname
separately, VSAM will provide implicit serialization (There are restrictions on sibling
subtask sharing. See "Sharing VSAM Data sets" for more information).
2. If you have installed the exec termination exit (which is generally not recommended),
files will be closed whenever the exec that opened them terminates.

OPEN (ACB) Options
When opening a VSAM data set, you may specify several types of options which control
how a data set can be processed. For example, you can determine whether the data set
will be processed in a "read only" mode, and whether it will be processed by record or by
control interval. The options argument of the OPEN function is where you code the data
set options.
The OPEN options are organized into groups. Some of the groups are additive. That is,
you may select one, some, or all of the options in that group. Other groups are
alternative. From these groups you may select just one option. All of the groups contain
one option that is the default value. If you do not select an option from a group, VSAM will
use the default value (the default values are underscored).
Group 1: Type of Key (additive)
Option Description
ADR Specifies that you want to use Relative Byte Addresses (RBAs) to access a
data set. Note that addressed access is not permitted for RRDSs.
CNV Specifies that you want to access the data set by control interval rather
than by records. Note that CNV access also implies addressed (ADR)
access (i.e., RBAs are used).
KEY Specifies that you want to use keys (for KSDSs) or Relative Record
Numbers (RRNs - for RRDSs) to access a data set. Keyed access is not
permitted for ESDSs.
Group 2: Type of Access (additive)
Option Description
DIR Specifies that direct access will be used in processing this data set. That is,
individual records will be randomly requested.
SEQ Specifies that sequential access will be used in processing this data set.
That is, contiguous records will be requested in either ascending or
descending sequence.
SKP Specifies that skip sequential access will be used in processing this data set.
Records will be processed in sequence but some records may be skipped.
Group 3: Direction of Access (additive)
Option Description
IN Specifies that the data set is being opened for reading (GETting) records.
OUT Specifies that the data set is being opened for writing (PUTting) records.
VSAM Functions 71
Group 4: Write Deferment (alternative)
Option Description
DFR Specifies that buffers are not to be immediately written following direct PUT
requests.
NDF Specifies that buffers are immediately to be written following direct PUT
requests.
Group 5: Insertion Strategy (alternative)
Option Description
NIS Specifies that the normal insertion strategy is to be used. Control intervals
are split at the midpoint.
SIS Specifies that the sequential insertion strategy is to be used. Control
intervals are split at the insertion point. This method is faster if several
contiguously located records are being inserted.
Group 6: Object of Access (alternative)
Option Description
NRM Specifies that the ddname gives the object to be processed.
AIX Specifies that the alternate index of the object specified by the ddname is
to be processed. You do not use this option to process the base
cluster with an alternate index. This option lets you read the records of
the alternate index itself (something you will not usually want to do). Please
refer to the VSAM01 and VSAM19 sample execs for information on using
alternate indexes.
Group 7: Reusability of Data set (alternative)
Option Description
NRS Specifies that the data set is not reusable. That is, you cannot open it for
reuse and overwrite the existing data with load mode processing.
RST Specifies that the data set is reusable. Upon opening a data set with this
option, it is as if all the existing data in the file is erased.
Group 8: VSAM buffer sharing (alternative)
Option Description
DDN Specifies that VSAM is to share control blocks and buffers by ddname.
This option only applies to sibling tasks in the same address space, and is
only available when the subtasks share subpool zero (i.e., it won't work
under TSO).
DSN Specifies that VSAM is to share control block and buffers by data set
name. This option only applies to sibling tasks in the same address space,
and is only available when the subtasks share subpool zero (i.e., it won't
work under TSO).

Examples
1. Open a new and empty KSDS for loading:
call open 'vsam', 'outdd', '(key,seq,out)'
2. Open an RRDS for random access (both input and output):
call open 'vsam', 'iodd', '(key,dir,in,out)'
3. Close a VSAM data set of any type after any type of processing:
call close 'vsam', 'mydd'

The REXXTOOLS/MVS functions which permit record and control interval level access to
VSAM data sets are:
GET The GET function is used to retrieve records or control intervals.
PUT The PUT function is used to write records or control intervals. If the PUT follows
a GET with the UPD (update) option, the record that was retrieved by the GET
will be replaced. In all other cases, PUT is interpreted as a request to insert new
records into the data set.
POINT The POINT function is used to position VSAM on a record in a VSAM file. For
example, you can position VSAM on the last record in a file when you plan to
read the file with the BWD (backward) option.
ERASE The ERASE function is used to remove records from a KSDS or RRDS. Before
you can ERASE a record you must GET it. VSAM does not permit ERASE to be
used on ESDS data sets.
Request Parameter List (RPL) Options
Request Parameter List (RPL) options are used in the options arguments of the GET,
PUT, and POINT functions. The RPL is a REXXTOOLS-managed data structure that is
shared for all requests to the same ddname (Thus, by implication, different ddnames
have different RPLs). For example, if you specify the options '(KEY,SEQ,UPD)' on the
first GET, PUT, or POINT for a ddname, subsequent invocations of the GET, PUT, or
POINT functions for the same ddname -- if they do not change these options -- will also
use '(KEY,SEQ,UPD)'.
The groups of RPL options are given in the tables below. All of the RPL options are
alternative options. From alternative option tables you may select only one option. If you
do not select an option from a table, VSAM will use a default value (the default values are
underscored).
VSAM Functions 73
Notes:
1. The options argument, like other arguments, is processed and communicated to

VSAM before the actual VSAM macros which execute the request are issued.
2. Some of the RPL options are identical to the OPEN function's options. However, for
the most part, the OPEN options merely describe the types of processing that might
take place, whereas the RPL options are specific requests for services. So, for
example, even though you may have specified ADR processing in the OPEN, you
must also specify ADR processing when you perform a GET, a PUT, or a POINT.
Group 1: Type of Key (alternative)
Option Description
ADR Specifies that you want to use Relative Byte Addresses (RBAs) to
access a record. Note that addressed access is not permitted for
RRDSs.
CNV Specifies that you want to process a control interval rather than a
record. Note that CNV access also implies addressed (ADR) access
(i.e., RBAs are used).
KEY Specifies that you want to use keys (for KSDSs) or Relative Record
Numbers (RRNs - for RRDSs) to process a record. Keyed access is not
permitted for ESDSs.
Group 2: Type of Access (alternative)
Option Description
DIR Specifies that you want to process a record directly. (i.e., you want to
specify a key, RBA, or RRN to process a record).
SEQ Specifies that you want to process the next record in the data set
(either forward or backward).
SKP Specifies that you want to process a record by key but that the key of
the record will be higher than that of the previous record processed.
Group 3: Use of Keyin (alternative)
Option Description
ARD Specifies that the keyin argument is to be used (if a form of direct
access processing has been requested) to find the record to be
located, retrieved, or stored.
LRD Specifies that the last record in the data set is to be processed. The
BWD (backward processing option) must also be specified.

Group 4: Read/Write Direction (alternative)
Option Description
FWD Specifies that if the file is being processed sequentially, processing will
proceed from the first record to the last (i.e., forward).
BWD Specifies that if the file is being processed sequentially, processing will
proceed from the last record to the first (i.e., backward).
Group 5: Positioning and Control (alternative)
Option Description
NSP Specifies that for direct processing requests VSAM is to remember the
position of the record being processed. The position will not be
"forgotten" by VSAM until a sequential request or an ENDREQ function
call is performed.
NUP Specifies that the record being processed will not be updated, or
deleted and that positioning is not to be remembered.
UPD Specifies that the record being processed is to be updated or deleted
(ERASEd). For a GET, VSAM will remember its position and (for
certain share options) obtain exclusive control of the control interval
containing the record. When a subsequent ERASE, PUT, or ENDREQ
function is executed, positioning and control are relinquished.
Group 6: Keyin Test Options (alternative)
Option Description
KEQ Specifies for keyed, direct searches that the key you provide in the
keyin argument must match, exactly, the key of a record in the data set
or else the search fails.
KGE Specifies for keyed, direct searches that the key you provide in the
keyin argument must be greater than or equal to the key of a record in
the data set.
Note: The Keyin Test Options apply to both full and generic keys.
Group 7: Generic Search Options (alternative)
Option Description
FKS Specifies that the key supplied in the keyin argument is to be treated
as a full length key.
GEN Specifies that the key supplied in the keyin argument is to be treated
as a generic key (i.e., only the leading characters of a key are
specified). Generic keys potentially will match more than one record.
VSAM Functions 75
Group 8: Variable Control Options (alternative)
Option Description
VAR Specifies that $RXT variables are to be created.
NOV Specifies that $RXT variables are not to be created. This option can
improve performance.
Sequential Processing
Using the SEQ option, you can process all VSAM data set types sequentially (i.e., one
record after another). Sequential access can be used in conjunction with either the KEY
(for keyed access) or ADR (for addressed access) options. Note, however, that ESDSs
may be processed using addressed access only. You cannot specify '(KEY,SEQ)' options
for processing an ESDS.
Examples
1. Sequentially load a KSDS. This example assumes that a REXX pseudo-array named
REC. contains the records to load (in key sequence):
/* Allocate and open the outdd file */

do i = 1 to 20
call put 'outdd', rec.i,,'(key,seq)'
end
/* Close and free the outdd file */
2. Sequentially read a KSDS:
/* Allocate and open the indd file */

recin = get( 'indd',,'(key,seq)')
do while rc = 0
parse var recin 'Address:' aline 'Date:' date,
145 custinfo
recin = get( 'indd',,'(key,seq)')
end
/* Close and free the indd file */
3. Sequentially read an ESDS:

GetCustRec = "parse value get( 'indd',,'(adr,seq)')",
"with fname +10 lname +15 ssn +9 ."
interpret GetCustRec
do while rc = 0
say 'Name:' lname','fname 'SSN:' ssn
interpret GetCustRec
end

Direct Processing
Records in VSAM files can also be accessed directly. That is, you can extract one record
for processing without having to read past the records that precede it. To specify direct
processing use the DIR RPL option.
KSDSs offer the most flexibility with respect to direct access. A KSDS may be accessed
using either keyed (KEY) or addressed (ADR) access. If keyed access is used, the keyin
argument for the function must contain a partial or complete key. If addressed access is
used, the argument must be a relative byte address (RBA). RBA values greater than 4G
are acceptable.
ESDSs may be accessed directly using the ADR (addressed) option. For a direct request
against an ESDS you must supply an RBA for the keyin argument.
A direct access request against an RRDS must use a relative record number (RRN) for
the keyin argument. You may not use addressed access for a relative record data set
even though it is possible to obtain the RBAs for an RRDS's records.
Note: The Batch Local Shared Resources (BLSR) subsystem can be used to improve the
performance of long running, direct processing jobs. The REXXTOOLS/MVS VSAM
interface supports the use of BLSR (See the BLSRJCL sample library member for
example JCL). For more information on this facility, refer to Application Development
Guide: Batch Local Shared Resource Subsystem, GC28-1672 . Do not use BLSR with
programs that process data sequentially since this will lead to increased run times.
Examples
1. Directly add a new record to a KSDS. The new record's key is 'ABC001':
/* Allocate and open the outdd file */

call put 'outdd', 'ABC001 new data',,'(key,dir)'
/* Close and free the outdd file */
2. Directly read the first record from an ESDS. The first record always has an RBA of
zero:

call get 'indd', 0, '(adr,dir)'
3. Directly retrieve then delete a record from a KSDS:
/* Allocate and open the iodd file */

call get 'iodd', 'ABC001', '(key,dir)'
if rc = 0 then
call erase 'iodd'
/* Close and free the iodd file */
VSAM Functions 77
4. Run a REXX-VSAM program using the batch REXX interpreter (this is much faster
than the batch TMP, IKJEFT01). Allocate the VSAM KSDS using a DD statement:
//JOB1 JOB
//STEP1 EXEC PGM=IRXJCL,PARM='MYRXPGM'
//SYSEXEC DD DISP=SHR,DSN=USER.VSAM.EXEC
//SYSTSIN DD DUMMY
//RXTKSDS DD DISP=SHR,DSN=USER.RXTKSDS.DATA
Sharing VSAM Data sets

VSAM data sets can be shared among many users. More importantly, VSAM data sets
can be shared by many users all at the same time. In order to understand how VSAM file
sharing is implemented, you need to understand how VSAM performs I/O and what
sharing facilities are available.
How VSAM I/O Works
First, let's examine how VSAM reads and writes records. It doesn't. While your programs
appear to read or write only one record at a time, VSAM actually reads and writes, at a
minimum, a control interval with each I/O operation. When reading, the records of the
control interval are placed into a buffer that is unique for each user of the file. After the
control interval has been loaded into the buffer, VSAM selects the desired record and
presents it to the user. Subsequent GETs or PUTs, if they are for the same record or for
other records already in the buffer, are satisfied with the copy in storage and not the copy
on DASD.
Depending on the file sharing method (which is discussed below), other users in other
address spaces may also read and write the same records. The other users will have
their own private buffers. Thus, if there are two users reading the first control interval of a
KSDS, there are really 3 copies of the data in the system: the DASD copy, the first user's
copy, and the second user's copy.
Because of VSAM buffering, two exposures to data corruption must be considered:
Read Integrity is compromised if one user is allowed to write to a control interval while
another user has a copy in memory. When this happens the second
user's memory copy is said to be "down level".
Write Integrity is compromised if two users update the same control interval at the same
time. The last user to write the control interval is the one whose changes
take effect.
At first glance, this might not appear to be a problem. Even the most scrupulous of
protocols must permit serial access to a record. However, when you consider the case
where one user updates the first record of a control interval while another user updates
the fourth, you begin see where the difficulty lies. The last user to write to the file will
completely nullify the first user's changes.

VSAM Serialization Methods
Serialization is the technique which allows asynchronous processes to share, one-at-a-

time, any resource. When used in the context of data set access, serialization is often
called "locking". The basic idea is that each accessor must first obtain a lock on a data
set (or some part thereof) prior to using it. When the access is completed, the current
accessor must release the lock to allow others to access the data. Perceived
concurrency, or the extent to which a resource appears to be simultaneously shared by
many users, is a function of the lock's scope and duration.
The scope of a lock is the amount of data that is reserved. The status portion of the
disposition parameter in JCL has a data set-wide scope, for example. Using DISP=OLD,
an accessor has exclusive control of the whole data set. The duration of a lock is the
amount of time a lock is held. Using the disposition parameter example again,
DISP=OLD locks a data set for the amount of time it takes the job step to run. Because of
these factors, the perceived concurrency for DISP=OLD serialization is very low. Other
serialization methods permit greater perceived concurrency.
Note: Often the duration of lock is the most important factor in determining perceived
concurrency. For example, if a data set-wide lock is held only briefly, perceived
concurrency does not suffer.
In general, the number of users that can concurrently access a VSAM data set is a
function of one or more of the following serialization mechanisms.
Data set disposition
Disposition is determined when the data set is allocated. If you are using JCL to allocate
the data set, the DISP parameter is used. If you are allocating the data set using the TSO
or REXXTOOLS ALLOCATE command, disposition is controlled by the status keywords
(OLD, SHR, NEW, and MOD). SHR disposition allows many users to read a data set at
the same time. User's who want to update the data set must use OLD to ensure
read/write integrity.
VSAM Share Options
Share options determine how VSAM will handle multi-user access to a data set, and are
determined by the SHAREOPTIONS keyword of the DEFINE CLUSTER command.
Share options take effect only if the data set is allocated with DISP=SHR. In addition,
share options do not apply when a VSAM file is opened and loaded for the first time.
There are 4 levels of cross-region file sharing:
SHAREOPTION 1 One user may write to the file or many users may read the file.
Using this option, VSAM ensures complete read and write
integrity. However, because the writer's lock endures while the
file is open, the perceived concurrency for other writers is usually
about as low as DISP=OLD serialization.
SHAREOPTION 2 One user may write to the file and many users may read the file.
VSAM ensures write integrity but read integrity is the
responsibility of the user.
VSAM Functions 79
SHAREOPTION 3 Many users may read and write to the file, and complete
responsibility for read and write integrity is with the user. Failure
to maintain read/write integrity can result not only in program
abends, but corrupted data as well.
SHAREOPTION 4 Many users may read and write to the file. However VSAM does
provide some support for concurrent use by ensuring that all
direct requests (read and write) result in accesses to the DASD
copy of the data. That is, a GET will cause the buffer to be
refreshed from DASD, and a PUT will cause the buffer to be
written to DASD. Sequential processing programs must use the
ENDREQ function to ensure that buffers are refreshed. Again,
failure to maintain read/write integrity can result in catastrophe.
Intra-Region Serialization
For files shared between tasks running asynchronously in the same address space,
VSAM provides serialization support based on shared buffers. This support is completely
independent of cross-region SHAREOPTIONS, and is controlled, instead, by the DDN
and DSN options of the OPEN function. If DDN (the default) is specified, VSAM will share
buffers for files that are opened with the same ddname. If DSN is specified, VSAM will
share buffers based on data set name.
When buffers are shared in this manner, VSAM maintains complete read and write
integrity. However, only subtasks that share subpool zero storage can use intra-region
file sharing. This is because VSAM allocates data buffers in subpool zero and needs
these buffers to remain allocated even though the first task to open the data set may
have terminated (when subpool zero is not shared, MVS automatically frees subpool zero
storage when a task terminates).
Unfortunately, several important address spaces, such as TSO, do not share subpool
zero. Because of this, the opportunity to apply intra-region file sharing is somewhat
limited.
Note: Any attempt to use intra-region file sharing under TSO and ISPF will result in
abends. To avoid problems, you should use the default intra-region file sharing option of
DDN. Then, to ensure that buffers are not shared between split screen applications, you
must generate a unique ddname for each screen that allocates the same VSAM data set.
Having done this, you will need to implement a file sharing protocol between split
screens. The easiest way to handle this problem is to treat it exactly as you would cross-
region file sharing (see The "Dirty Read" Technique below).
ENQ/DEQ Serialization
The MVS ENQ/DEQ service (which can be accessed via the REXXTOOLS ENQ and
DEQ functions) can be used to provide a protocol for serializing accesses to a VSAM file.
In combination with cross-region SHAREOPTIONS 2, 3, or 4, ENQ/DEQ can be used to
provide a high degree of perceived concurrency, while maintaining read/write integrity.
Note, though, that such a protocol must be strictly adhered to by all accessors. There is
no mechanism in the MVS ENQ/DEQ service to prevent "cheaters" from accessing a
data set without first obtaining the appropriate locks.

Serialization Precedence
The various serialization methods have an order of precedence. Allocation disposition

takes precedence over all other methods. This is followed by SHAREOPTIONS
serialization, which is followed by ENQ/DEQ serialization.
Sophisticated applications requiring a high degree of concurrent use, almost always

require the use of SHAREOPTIONS 3 or 4 and ENQ/DEQ serialization. Even so, you can
always use disposition serialization whenever you want to ensure that just one user has
the file (third shift batch update and reporting applications often fit this profile).
Serialization Problems
Because of the flexibility of ENQ/DEQ serialization, locks can be constructed for any part
of a data set. You could, for example, use a record's key as the resource to be locked.
Yet, because VSAM reads and writes several records at a time, the minimum unit for
serialization usually must encompass a complete control interval. In this case, the relative
byte address (RBA) of the control interval is used for the lock.
Another complication that must be considered arises from insertions into KSDSes.
Whenever a control interval is full but a new record needs to be inserted into its middle,
VSAM "splits" the control interval into two parts, each containing some free space. The
new record can then be inserted. A negative consequence of this splitting action is that it
makes impossible the use of any protocol based on control interval locks -- you can't lock
on a moving target.
Finally, the problem of splitting can cascade to higher levels: if a control area is full, it too
must be split before a new control interval can be inserted.
The "Dirty Read" Technique
The "dirty read" technique can be used to provide a high degree of concurrent access to
VSAM files while avoiding the complications associated with CI and CA splits. The dirty
read protocol can be summarized as follows:
1. The VSAM file must be defined with cross-region SHAREOPTIONS 4.
2. The file must be allocated with DISP=SHR.
3. All operations on the file, including reads, must be preceded with an ENQ for the data
set. The data set name is specified for the ENQ "rname", but any string can be used
for the ENQ "qname" (though it must be the same string for all accessors).
4. After a lock is obtained, the user's buffer must be refreshed with a GET request. This
step also applies to new record insertions.
5. At the end of all file operations, the enqueue is released with a DEQ function call.
6. No lock is held during a wait (such as terminal input wait).
7. Before updating a previously read record, a fresh copy of the record must be
obtained and compared to the original to ensure that no other user has updated the
VSAM Functions 81
record while it was being browsed and modified. As always, the second read, the
record comparison, and the update must be shielded by a lock.
An example of the dirty read technique can be found in the VSAM18 program of the
REXXTOOLS sample library. This application implements an ISPF-based transaction for
updating an employee data set (a KSDS). The employee data set can be concurrently
queried and updated by any number of TSO users. VSAM18 contains commentary that
explains each facet of the dirty read technique.
VSAM Return Codes

Upon completion, all REXXTOOLS/MVS VSAM functions provide a return code and a
In addition, except for the GET function which returns a record, all VSAM functions return
code two times, once as OPEN's returned value, and once as the value of the RC
variable
say "RC="open('vsam','indd') "RC="rc "REASON="reason
underlying VSAM macro return and reason codes. In all cases, a return code of zero
indicates success.
Notes:
1. The complete list of VSAM return and reason codes can be found in the IBM
publication Macro Instructions for Data Sets for your system's level of DFP or
DFSMS.
2. The return and reason codes (including ABEND codes) produced by the VSAM

The sections that follow describe the syntax and operation of the VSAM-related functions.
CLOSE (VSAM)
Syntax:
CLOSE(ddname[,'T'])
Arguments:
given.
Note: For compatibility with earlier releases of REXXTOOLS, the first

argument can contain the string 'VSAM', and the second argument can
contain the ddname. The 'VSAM' argument is no longer required,
provided that you use a ddname that is not 'VSAM', 'QSAM', or 'BPAM'.
'T' indicates that a TYPE=T close is to be performed. A TYPE=T close

causes VSAM to complete pending I/O operations and update catalog
information, without disconnecting the program from the data set.
Processing can continue after the close without re-opening the data set.
Module Name:
RXTCLOSE
Environments:
CLOSE performs two functions:
• If 'T' is coded, CLOSE completes I/O operations and updates the catalog information,
but does not disconnect your program from the data set. You may continue
processing without reopening the data set.
• If 'T' is not coded, CLOSE completes I/O operations, updates catalog information,
and disconnects your program from the data set.
The CLOSE function returns the VSAM CLOSE macro return code. If you CALL the
VSAM Functions 83
RC Contains the VSAM CLOSE return code. Zero means the operation was
completed successfully.
REASON Contains the VSAM CLOSE reason code. If the file was already closed
or has never been opened, a value of 1 is returned in REASON.
Examples:
2. Force I/O operations to complete and update the catalog without disconnecting the
program from the data set:
call close 'outdd', 't'

ENDREQ (VSAM)
Syntax:
ENDREQ(ddname)
Arguments:
Module Name:
RXTENDRQ
Environments:
The ENDREQ function is used to force VSAM to write buffers, release exclusive control
of control intervals (for certain share options), and to "forget" positioning. Before you can
use the ENDREQ function you must first allocate and open (using the OPEN function) the
data set associated with the ddname argument. If you do not, an error will occur.
The ENDREQ function returns the VSAM ENDREQ macro return code. If you CALL the
ENDREQ function, the returned value is contained in the RESULT special variable.
After completion of a ENDREQ function call, several special REXX variables are
populated with useful information. You should treat these variables as "read only" and
make no attempt to modify any of them. The variables are:
RC Contains the VSAM ENDREQ return code. Zero means the operation
was completed successfully.
REASON Contains the VSAM ENDREQ reason code.
VSAM Functions 85
Example:
1. After directly retrieving a record for update, either update the record using the PUT
function, or release control of the record using the ENDREQ function:
parse value get('iodd','CAT','(dir,upd)'),

with . +10 type .
if (rc = 0) & (type = 'SIAMESE') then do
/* Build new record here */
end
else
call endreq 'iodd'

ERASE (VSAM)
Syntax:
ERASE(ddname)
Arguments:
ddname
is the 1 to 8 character name that identifies the data set you want to process. This name
needs to have been previously associated with the data set, either via the ALLOCATE
command or JCL DD statement, and opened via the OPEN function.
Module Name:
RXTERASE
Environments:
The ERASE function is used to remove records from KSDSs and RRDSs. VSAM does
not honor ERASE requests for ESDSes. Before you can use the ERASE function you
must first allocate and open (using the OPEN function) the data set associated with the
ddname argument. If you do not, an error will occur. In addition, you must use the GET
function (using the UPD option) to retrieve the record you wish to remove before you
attempt to ERASE it.
The ERASE function returns the VSAM ERASE macro return code. If you CALL the
ERASE function, the returned value is contained in the RESULT special variable.
After completion of an ERASE function call, several special REXX variables are
populated with useful information. You should treat these variables as "read only" and
make no attempt to modify any of them. The variables are:
RC Contains the VSAM ERASE return code. Zero means the operation was
REASON
Contains the VSAM ERASE reason code.
Example:
1. After directly retrieving a record for update, remove the record using the ERASE
function:
record = get('iodd','cat','(dir,upd)')
if rc = 0 then
call erase 'iodd'
VSAM Functions 87
GET (VSAM)
Syntax:
GET(ddname[,keyin][,options])
Arguments:
keyin a character string that contains the key of the record to retrieve. The
keyin argument is required for GET function calls that specify the DIR or
SKP options (see options argument below). However, if the LRD (last
record positioning request) option is specified, the keyin argument is not
required. If you specify keyin, and it is not required, the argument is
ignored. Alternatively, if you omit the keyin argument and it is required,
an error will occur.
Note: The format of the keyin argument is different for different types of
data sets and data set accesses. Please see "Specifying the Keyin
Argument" on page 89 for more information.
options a character string describing the processing options for this request. You
may specify the options in any order. If multiple options are coded, they
must be enclosed in parentheses and separated by commas. The
groups, their options, and descriptions are given in the section "Request
Parameter List (RPL) Options". From each RPL option group you may
select one (and only one) option.
Module Name:
RXTGET
Environments:
The GET function is used to retrieve records and control intervals from VSAM data sets.
Before you can use the GET function you must first allocate and open (using the OPEN
function) the data set associated with the ddname argument. If you do not, an error will
occur. GET may be used to retrieve records either sequentially or directly, depending
upon the processing options you specify in the options argument. If you are using a
direct form of access (either DIR or SKP) you must specify the keyin argument.
GET is also used to update and delete records. If you wish to update or delete a record,
you must first call the GET function using the UPD (update) option.

Specifying the Keyin Argument:
The format of the keyin argument varies, depending upon the type of data set you are
processing and the type of access you have requested. If you are using addressed
access (the ADR option), or if you are processing by control interval (the CNV option), the
value of key must be a relative byte address (RBA) in REXX printable integer format.
Similarly, if you are processing an ESDS using direct access, the argument must be a
RBA. For RRDSs the value of keyin must be a relative record number (RRN) in REXX
printable integer format.
For KSDS keyed (but not addressed) access, the value of keyin must be either a full-
length (option FKS) or generic (option GEN) key. Generic keys are used to find records
that have the same prefix characters. For example, the generic key 'D' matches with
'DAVID', 'DOG', and 'DAD'. As this example demonstrates, generic keys usually have
fewer characters than full keys, although this is not a requirement. If you specify a key
that is longer than the full key length, the value is truncated on the right. If you specify a
key that is shorter than the full key length and you have not specified the GEN option, the
key is padded on the right with binary zeros up to the length of the full key.
code information. If the function call was successful, several other special REXX
variables are created. You should treat these variables as "read only" and make no
RC Contains the VSAM GET return code. Zero means the operation was
REASON Contains the VSAM GET reason code.
$RXTKEY Contains the actual value of the key for the record retrieved. For ESDSs
and any type of data set that is being processed by control interval
(option CNV), the value of the key is the RBA of the record. For RRDSs
the value of the key is the RRN. For KSDSs not being processed by
control interval, the key is the bytes extracted from the retrieved record
beginning at the key offset, and continuing for the length of the full key.
$RXTRBA Contains the Relative Byte Address (RBA) of the retrieved record.
$RXTRECL Contains the actual length of the returned record and is fully equivalent
to the following expression:
LENGTH(RESULT)
VSAM Functions 89
Examples:
1. Sequentially retrieve records from a data set starting with the first record:
parsestmt = "parse value get('indd')",

"with name +30 ssn +11",
"empno +10 salary +11"
interpret parsestmt
do while rc = 0
say 'Name:' name
say 'SSN: ' ssn
say 'Emp. No.:' empno
interpret parsestmt
end
Note that no options are specified because '(KEY,SEQ,FWD)' are defaults.
2. Directly retrieve the first record from a KSDS which has a key that begins with the
letters 'PA':
searcharg = 'PA'
parse value get('indd',searcharg,'(gen,key,dir)'),
with accountno +11 fname +15 lname +15,
birthday +8 age + 3
3. Retrieve the fifth record from a relative record data set:
record = get('indd',5,'(dir)')

OPEN (VSAM)
Syntax:
OPEN('VSAM',ddname[,options][,password])
Arguments:
'VSAM' indicates that the VSAM access method is to be used to open the file.
data set, either via the ALLOCATE command or JCL DD statement.
Note: The names 'VSAM', 'QSAM', and 'BPAM' are reserved. Do not use
these strings for ddnames.
options a character string describing the processing options for the data set. You
options are organized into several groups. The options in some groups
are additive. That is, you may specify one or more of the options in that
group. Other groups have alternative options. From each group you may
select only one option. The groups, their types, options, and descriptions
are given in the section, "OPEN (ACB) Options".
password a character string that contains the highest-level password required for
the options specified in the options argument. If no password is
supplied, but one is required, VSAM will prompt the console operator for
the password.
Note: Passwords are not supported for SMS-managed data sets. You must have the
appropriate security package (RACF, ACF2, etc.) authorization to open SMS-managed
data sets.
Module Name:
RXTOPEN
Environments:
you can get (using the GET function) records from the data set, or put (using the PUT
function) records into the data set. All data sets should be closed (using the CLOSE
function) when you are finished using them.
VSAM Functions 91
Note: The REXXTOOLS/MVS VSAM interface is in no way connected with the REXX
EXECIO command. You may use EXECIO and the REXXTOOLS QSAM and BPAM
interfaces to access non-VSAM files at the same time you are accessing VSAM files.
The OPEN function returns the VSAM OPEN macro return code. If you CALL the OPEN
After completion of an OPEN function call, the RC and REASON variables will contain
return code information. If the function call was successful, several other special REXX
RC Contains the VSAM OPEN return code. Zero means the operation was
REASON Contains the VSAM OPEN reason code.
$RXTTYPE Indicates the type of data set that has been opened: 'KSDS', for key-
sequenced data sets; 'ESDS', for entry-sequenced data sets; 'RRDS' for
relative record data sets; 'VRDS' for variable-length relative record data
sets; and 'LDS', for linear data sets.
Note: Linear data sets can be accessed by control interval only.
$RXTLRCL Specifies the maximum record length of records in the opened data set.
$RXTCNVL Specifies the length of a control interval for the data set.
$RXTKEYO Specifies the offset of the key field in the records of the data set (this
variable has meaning for KSDSs only).
Note: The value of $RXTKEYO is zero- based. Thus a key that begins in
the first byte of a record has an offset of 0; one that begins in the second
byte has an offset of 1; and so on.
$RXTKEYL Specifies the length of the keys in a key-sequenced data set's records.
$RXTRECS Specifies the number of records currently in the data set.
Note: The value of the $RXTRECS variable is derived from the

"statistics" portion of the entry for the data set. An alternative display of
this information may be obtained from the "LISTC ENT(data set name)
ALL" command. Be aware that the number of records can be inaccurate
if the file is open for update by another program, or if the last program to
update the data set failed to properly close it. Use the IDCAMS EXPORT
and IMPORT commands to reset the statistics.
$RXTHRBA Specifies the relative byte address of the end of the data set (applies
only to the data component for KSDSs).
$RXTERBA Specifies the high-used RBA. (applies only to the data component for
KSDSs).

$RXTXADR Indicates whether extended addressing is being used. The returned
values are "YES" and "NO".
Examples:
1. Open a KSDS for sequential read access:
if open('vsam','indd') <> 0 then say 'Open failed.'
Note that no options are specified because '(KEY,SEQ,IN)' are defaults.
2. Open a KSDS for direct reading and writing:
call open 'vsam', 'indd', '(key,dir,in,out)'
Note that while '(KEY,IN)' are defaults, we have coded them explicitly in this case (if
nothing else, explicitly coded options serve as good documentation of what you are
trying to accomplish).
3. Open an ESDS for direct read access:
call open 'vsam', 'indd', '(dir,adr)'
This example shows that you can specify the options in any order.
VSAM Functions 93
POINT (VSAM)
Syntax:
POINT(ddname[,keyin][,options])
Arguments:
keyin a character string that contains the key of the record to retrieve. The
keyin argument is required for all invocations of POINT except when the
LRD (last record positioning request) option is specified. If you specify
keyin, and it is not required, the argument is ignored. Alternatively, if you
omit the keyin argument and it is required, an error will occur.
Argument" for more information.
Parameter List (RPL) Options" . The RPL option groups are all
alternative option groups. From each group you may select only one
option.
Module Name:
RXTPOINT
Environments:
The POINT function is used to position VSAM at specific records and control intervals in
VSAM data sets. Before you can use the POINT function you must first allocate and open
(using the OPEN function) the data set associated with the ddname argument. If you do
not, an error will occur. POINT does not actually retrieve a record. If you want to retrieve
a record that you have POINTed to, you must use the GET function.
The primary use of POINT is to position VSAM for subsequent sequential access
(beginning at a location that is not the first record of the data set).
Note: POINT is especially useful for switching between forward and backward sequential
processing without closing the data set.

value of key must be a relative byte address (RBA) in REXX printable integer format.
For KSDS keyed (but not addressed) access, the value of keyin must be either a full-
length (option FKS) or generic (option GEN) key. Generic keys are used to find records
that have the same prefix characters. For example, the generic key 'D' matches with
'DAVID', 'DOG', and 'DAD'. As this example demonstrates, generic keys usually have
fewer characters than full keys, although this is not a requirement. If you specify a key
that is longer than the full key length, the value is truncated on the right. If you specify a
key that is shorter than the full key length and you have not specified the GEN option, the
key is padded on the right with binary zeros up to the length of the full key.
The POINT function returns the VSAM POINT macro return code. If you CALL the POINT
After completion of a POINT function call, the RC and REASON variables will contain
return code information. If the function call was successful, several other special REXX
RC Contains the VSAM POINT return code. Zero means the operation was
REASON
Contains the VSAM POINT reason code.
Example:
1. Sequentially retrieve records from a data set starting with the last record and
proceeding to the first record:
call point 'indd', , '(lrd,bwd)'

do while rc = 0
call get 'indd'
say 'result='result
end
After the POINT, options do not need to be re-specified, since the BWD option stays
in effect until it is changed by another request.
VSAM Functions 95
PUT (VSAM)
Syntax:
PUT(ddname,recin[,keyin][,options])
Arguments:
recin contains the record to be inserted or updated. For KSDS and ESDS data
sets, the records can be of varying lengths. However, the records of
ESDS data sets, once loaded, cannot change lengths. If you attempt to
change the length of an ESDS record VSAM will reject the request.
For RRDSs, since the record lengths are known at open time and are
fixed, the REXXTOOLS/MVS VSAM interface is able to pad (with blanks)
or truncate the recin argument to fit the data set. For ESDS and KSDS
data sets, no padding or truncation is performed.
keyin a character string that contains the key of the record to update or insert.
If the request is for sequential (SEQ) and/or update (UPD) processing; or
if the data set you are processing is a KSDS (and you are not accessing
it by control interval), then the keyin argument is not required. For all
other requests, the keyin argument is required. If you specify keyin, and
it is not required, the argument is ignored. Alternatively, if you omit the
keyin argument and it is required, an error will occur.
Argument" for more information.
must be enclosed in parentheses and separated by commas. The option
Parameter List (RPL) Options" . From each RPL option group you may
select one (and only one) option.
Module Name:
RXTPUT
Environments:

The PUT function is used to update or insert records and control intervals in VSAM data
sets. The operation of PUT (like GET) depends upon the processing options you specify
in the options argument. Before you can call the PUT function you must first allocate and
open the data set associated with the ddname argument. If you do not, an error will
occur.
function (with the UPD option). All other PUT requests are treated as insertion requests.
value of keyin must be a relative byte address (RBA) in REXX printable integer format.
For KSDS keyed (but not addressed) direct access (including skip sequential processing)
the value of the key is taken directly from the key location in recin. If you supply a keyin
argument for this type of access, the argument is ignored.
The PUT function returns the VSAM PUT macro return code. If you CALL the PUT
function, the returned value is contained in the RESULT special variable. After
completion of a PUT function call, the RC and REASON variables will contain return code
information. If the function call was successful, several other special REXX variables are
created. You should treat these variables as "read only" and make no attempt to modify
any of them. The variables are:
RC Contains the VSAM PUT return code. Zero means the operation was
REASON Contains the VSAM PUT reason code.
$RXTKEY Contains the actual value of the key for the record updated or inserted.
For ESDSs and any type of data set that is being processed by control
interval (option CNV), the value of the key is the RBA of the record. For
RRDSs the value of the key is the RRN. For KSDSs not being processed
by control interval, the key is the bytes extracted from record beginning
at the key offset, and continuing for the length of the full key.
$RXTRBA Contains the Relative Byte Address (RBA) of the inserted or updated
record.
$RXTRECL Contains the length of the inserted or updated record and is fully
equivalent to the following expression:
LENGTH(recin)
VSAM Functions 97
Examples:
1. Sequentially retrieve and update records from a data set starting with the first record:
record = get('iodd',,'upd')
do while rc = 0
end
After the first GET, no options are required, since the UPD option stays in effect until
it is changed by another request. The P2D and D2P functions (see "General REXX
Extensions") are used to convert packed decimal numbers to the REXX decimal
format, and vice versa.
2. Directly retrieve and update a KSDS record with the key 'CAT':
call get 'iodd', 'cat', '(key,dir,upd)'

if rc = 0 then do
/* modify the record here */
call put 'iodd', record
end
The PUT requires neither a keyin nor an options argument. Keyin is not required
because for KSDS updates the key is taken from the record itself. The options
argument is not required because the '(KEY,DIR,UPD)' options argument of the GET
is still in effect.
3. Load an ESDS from a sequential file:
"execio * diskr indd (stem line. finis)"
do i = 1 to line.0
call put 'outdd', line.i
if rc <> 0 then leave i
end

VERIFYV (VSAM)
Syntax:
VERIFYV(ddname)
Arguments:
Module Name:
RXTVERFY
Environments:
The VERIFYV function is used to correct information the catalog contains related to the
location of the end of the data set. Before you can use the VERIFYV function you must
first allocate and open (using the OPEN function) the data set associated with the
ddname argument. If you do not, an error will occur.
The primary purpose of the VERIFYV function is to correct catalog information that may
have been corrupted due to system failures. The action performed by the VERIFYV
function is identical to the action performed by the IDCAMS VERIFY command.
Notes:
1. The VERIFYV function has the extra "V" on the end of its name so as not to interfere
with the REXX built-in function, VERIFY.
2. VERIFYV changes the RPL options to '(CNV,SEQ,FWD)' prior to executing the

VSAM VERIFY macro. If different RPL options are required for subsequent
processing, your program must specify the new options itself.
The VERIFYV function returns the VSAM VERIFY macro return code. If you CALL the
VERIFYV function, the returned value is contained in the RESULT special variable.
After completion of a VERIFYV function call, two special REXX variables are populated
RC Contains the VSAM VERIFY return code. Zero means the operation was
VSAM Functions 99
REASON
Contains the VSAM VERIFY reason code.
Example:
1. Call the VERIFYV function to fix the catalog entry for the allocated (and opened) data
set:
call verifyv 'iodd'

IDCAMS
REXXTOOLS/MVS includes a host command environment for issuing IDCAMS
commands, and functions that make common IDCAMS-related operations easier. Using
the REXXTOOLS IDCAMS interfaces you can:
• Define, modify, and remove catalogs, page spaces, VSAM and non-VSAM data sets,
alternate indexes, generation data groups, etc.
• List or print catalog and data set information.
• Convert and back-up data
Neither the IDCAMS host command environment nor the IDCAMS functions require TSO
services. These interfaces can be used in any address space.
Address IDCAMS
The most generalized IDCAMS interface provided by REXXTOOLS is the IDCAMS host
command environment. This interface permits IDCAMS commands to be embedded
directly in your REXX programs. As in other host command environments, IDCAMS
commands are REXX expressions that resolve to a string. The expressions can be as
simple as a literal string, like this:
"listc lvl('sys1.rexxtool') nonvsam volume"
Or they can be complex REXX expressions, like this:
"define "||type||DataKeywords||GetIndexKW(type)
To direct commands to the IDCAMS host command environment, you use the REXX
ADDRESS instruction. If you want to send more than one command to IDCAMS, code
the ADDRESS instruction on a line by itself. For example:
address idcams
"define cluster."
"define cluster."
"listc."
If you want to send just one command to IDCAMS without changing the current host
command environment, you code the command immediately after the ADDRESS
instruction, like this:
address idcams "listc lvl('rexxtool')"
The IDCAMS host command environment returns IDCAMS messages in stem variables
of the form:
$RXTIDCMS.n
Where n is a numeric subscript.
IDCAMS 101
The number of variables returned is contained in the "zeroth" variable, $RXTIDCMS.0.
So, for example, to display messages returned from a LISTC command, you would code
something like the following:
/* REXX */
address idcams
"listc lvl('rexxtool') volume"
if rc = 0 then
do i = 1 to $rxtidcms.0
say $rxtidcms.i
end
If the IDCAMS host command environment has not been permanently installed on your
system, you will need to use the RXSUBCOM function to add it dynamically. The
following code checks to see if the IDCAMS host command environment is available, and
if not, adds it:
address mvs "subcom idcams"

if rc <> 0 then do
call rxsubcom 'add', 'idcams', 'rxtidcms'
if rc <> 0 then do
say 'Error adding IDCAMS. RC='rc 'REASON='reason
exit 8
end
end
address idcams
"listc."
Notes:
1. You can call RXSUBCOM to add a host command environment unconditionally. If the
environment already exists, no action is taken.
2. IDCAMS host command environment examples can be found in the VSAM01 exec of
the REXXTOOLS sample library.
3. Complete IDCAMS command information can be found in the Access Method

Services manual for your system's level of DFP or DFSMS. Additional IDCAMS
information can be found in the Using Data Sets manual for your system's level of
DFP or DFSMS.
4. The IDCAMS host command environment uses the level of IDCAMS that is available
on your system (REXXTOOLS issues an undirected LOAD macro to obtain its
address). Because of this, ADDRESS IDCAMS will handle commands for VSAM or
ICF catalogs.

IDCAMS Functions
REXXTOOLS provides the following IDCAMS functions:
DSNDEL a function for deleting data sets.
LISTC a function for listing catalog information. The information is returned in a

more "programmer friendly" format than is provided by the raw LISTC
command.
These functions, like the IDCAMS host command environment, are TSO-independent.
That is, you can use them in REXX programs in any address space.
You use the IDCAMS functions as you would use any other REXX function. Simply code
references to them in your REXX programs. For example, to delete a data set using
DSNDEL you could code:
/* REXX */
if dsndel("'us01.user.data'") = 0 then
say 'Data set deleted.'
else do
say 'Delete failed.'
do i = 1 to $rxtidcms.0
say $rxtidcms.i
end
end
Alternatively, you can use the REXX CALL instruction or PARSE VALUE, as is shown
below:
parse value listc("sys1.rexxtool",,"v") with rc dsncount

if rc = 0 then do
do i = 1 to dsncount
parse pull dsname volser devtype .
say dsname volser devtype
end
end
Notes:
1. The DSNDEL and LISTC functions are not implemented over ADDRESS IDCAMS.
They are separate assembler programs. You do not need to ensure that ADDRESS
IDCAMS is present before issuing a call to either of these functions.
2. The IDCAMS functions are incorporated into the OST-supplied IRXFLOC function
package, as are all REXXTOOLS functions.
3. All "IDC" messages produced as a result of running an IDCAMS function are stored
in the $RXTIDCMS. stem variable array.
4. The primary argument to the LISTC function is data set level. Because this is not truly
a data set name, the LISTC function will not automatically append a userid to it. The
DSNDEL's primary argument is a data set name (or data set name pattern), and it
will automatically append a userid, if the data set name argument is not enclosed in
single quotes.
IDCAMS 103
5. An example of the LISTC function is contained in the LC exec of the REXXTOOLS
exec library.
IDCAMS Return Codes

The IDCAMS host command environment returns the IDCAMS return code in the RC
variable. The IDCAMS functions do not set the RC variable. They return as their value
the IDCAMS return code.
A zero return code always indicates successful execution. Non-zero return codes indicate
partial or complete command failure. The precise meaning of non-zero IDCAMS return
codes is documented in the Access Method Services manual for your system's level of
DFP or DFSMS. However, non-zero return codes are almost always accompanied by
explanatory "IDC" messages. These messages can be obtained by displaying the
contents of the $RXTIDCMS array.

The sections that follow describe the syntax and operation of the IDCAMS services.
ADDRESS IDCAMS
Syntax:
ADDRESS IDCAMS [command [;command]...]
Commands:
IDCAMS commands. IDCAMS commands are documented in the Access Method

Services manual for your system's level of DFP or DFSMS.
There are minor restrictions concerning the coding of IDCAMS commands. These are as
follows:
1. The PARM MARGINS command is supported, but should not be used because it can
adversely affect the way in which IDCAMS reads subsequent commands. The default
values for the LEFTMARGIN and RIGHTMARGIN parameters are 1 and 32760 (the
maximum), respectively.
2. You may not code IDCAMS comments in any command string. If you require
comments, code REXX comments. For example:
"DELETE (KSDS.DATA)" /* DELETE THIS ONE */
3. You may not use IDCAMS continuation characters in any command string. However,
you may (and should) use REXX statement continuations whenever you have a
command that won't fit on one source line. For example:
"LISTC ENTRIES(KSDS.DATA",
"VRDS.DATA) ALL"
4. It is permissible to execute more than one IDCAMS command per REXX host
command. The commands must be separated by a semicolon. The semicolons must
be contained within the REXX command string. For example:
"LISTC ENTRIES(KSDS1); LISTC ENTRIES(KSDS2)"
Note: If you "stack" commands like this, the output will also be stacked.
5. The IDCAMS IF-THEN-ELSE sequence is supported, but its use is strongly

discouraged. If you require control logic between your IDCAMS commands you
should use REXX control instructions, which are far more flexible.
Module Name:
RXTIDCMS
IDCAMS 105
Environments:
ADDRESS IDCAMS is a host command environment. As with other host command

environments, you switch to the IDCAMS host command environment using the
ADDRESS instruction. To send a command to the host command environment you
simply embed a command expression in your program. Because REXX performs
expression evaluation on host commands before it invokes the host command processor,
you can dynamically construct IDCAMS commands using various REXX arithmetic and
string operators.
SYSPRINT output from ADDRESS IDCAMS is directed to a special stem array (See
"Returned Information" below).
The IDCAMS host command environment, like other REXX host command environments,
returns a return code in the special variable RC. The possible return values are as
follows:
-4 Zero length command string was passed.
-3 IDCAMS host command environment not found. This RC is set by REXX (not by
REXXTOOLS) whenever REXX is unsuccessful in locating a host command
entry in the host command table of the current REXX environment. Probable
cause: ADDRESS IDCAMS has not been installed. Use RXSUBCOM to
dynamically add the IDCAMS host command environment.
0 Successful execution. Informational messages may have been produced.
4 Some problem was encountered (for example, an entry was not found on a
LISTCAT command), but execution continued. Refer to the messages produced
by the command for more information.
8 A more severe error was met, and some portion of the command may not have
been performed. Refer to the messages produced by the command for more
information.
12 The entire command could not be performed.
16 Severe problem encountered.
The IDCAMS host command processor also returns the SYSPRINT output produced by
IDCAMS commands. The lines of output are returned in a special array whose stem is
"$RXTIDCMS.". The zeroth element ($RXTIDCMS.0) contains the number of lines of
SYSPRINT output produced by the most recent IDCAMS host command. If you execute
more than one IDCAMS command within a REXX host command expression, the lines of
output for the commands will appear, one after another, in the $RXTIDCMS. array.

Notes:
1. The SYSPRINT lines contained within the ”$RXTIDCMS." array are in "ready-to-print"
format. That is, printer control characters appear in the first byte of each record. Use
PARSE VAR or SUBSTR to remove these, if you so desire.
2. The interface performs a REXX drop on the "$RXTIDCMS." stem prior to executing
each command string (but not each command within the command string, if there is
more than one).
3. The interface performs a MARGINS command prior to executing each command

string. Because of this, the first IDC message in the "$RXTIDCMS." stem array is the
"FUNCTION COMPLETED" message for the MARGINS command.
Example:
1. Execute a LISTCAT command and print each line to the terminal:
call rxsubcom 'add', 'idcams', 'rxtidcms'

address idcams "listcat entries(employee) all"
if rc = 0 then
do i = 1 to $RXTIDCMS.0
say substr($RXTIDCMS.i,2)
end
Notice the use of the REXX SUBSTR function to strip off the carriage control characters
on the front of each $RXTIDCMS record. Note also that the LISTCAT command is issued
from the ADDRESS instruction itself. This tells REXX to issue the command to IDCAMS,
but not to change the current host command environment. If you wanted to change the
current host command environment so that subsequent commands would be sent to
IDCAMS without using the ADDRESS instruction, you would code:
address idcams
"listcat entries(employee) all"
IDCAMS 107
DSNDEL (Data Set Delete)
Syntax:
DSNDEL(dsnpattern[,options][,catalog])
Arguments:
dsnpattern is the 1 to 64 character name that identifies the data set or data sets you
want to delete. If dsnpattern contains single quotes, it is assumed to be
fully qualified. If not, the current userid (as given by IRXUID) will be
appended to the front of the argument.
• You may use DELETE command wild card characters to delete

(possibly) more than one data set per invocation.
• You may specify a password for the data set, using the form
dsname/password.
options is the 1 to 80 byte string containing DELETE command data set name
qualifiers and options. For example, you can use this argument to specify
the SCRATCH option which causes the data set's VTOC information to
be removed. If you supply more than one DELETE command operand,
they must be separated by at least one blank. The interface does not
check this string for errors. If any keyword is incorrect, IDCAMS will
detect the error.
catalog is the catalog containing the entry for the data set to be deleted. If a
password is required use the form catalog/password. The catalog
name must be fully qualified, without quotes. Userid is never appended
to the catalog name.
Module Name:
RXTDSNDL
Environments:
The DSNDEL function is used to invoke the IDCAMS DELETE command. Using this
function you can:
• Remove a data set's catalog information.
• Remove a data set's VTOC information.
• Clear the space the data set occupied with binary zeros.

Notes:
1. The DSNDEL constructs a DELETE command of the form:
DELETE dsnpattern [options] [CATALOG(cat/pw)]
Because of this you cannot specify multiple patterns in the dsnpattern argument. You
may, however, use IDCAMS wild card characters to delete more than one data set.
2. You cannot scratch (remove from the VTOC) a data set that is not cataloged. Use the
SCRATCH function of IEHPROGM.
3. Refer to the Access Method Services publication for your system's level of DFP or
DFSMS for more information on the DELETE command.
The DSNDEL function returns the IDCAMS return code. If you CALL the DSNDEL
function, the returned value is contained in the RESULT special variable. The RC
variable is unchanged (unless you assign the return code to it). A return code of zero
always indicates success.
The DSNDEL function returns any "IDC" messages produced the DELETE command.
The messages are returned in a special array whose stem is $RXTIDCMS. The zeroth
element ($RXTIDCMS.0) contains the number of messages produced by the command.
Notes:
1. Only "IDC" messages are returned in the $RXTIDCMS. stem array. The messages
are not in "ready-to-print" format (i.e., there are no printer control characters).
2. The function performs a REXX drop on the $RXTIDCMS. stem prior to executing the
DELETE command.
3. The function performs a MARGINS command prior to executing the DELETE

command. Because of this, the first IDC message in the $RXTIDCMS. stem array is
the "FUNCTION COMPLETED" message for the MARGINS command.
Examples:
1. Uncatalog a data set. The function will automatically append the userid. The data set
is not removed from the VTOC:
if dsndel("user.data","noscratch") = 0 then
say 'Deleted.'
2. Uncatalog and scratch a data set from the VTOC. The data set name is fully
qualified:
call dsndel "'sys1.locproc'", 'scratch'
3. Delete a member of a partitioned data set. The userid is automatically appended:
IDCAMS 109
if dsndel("user.exec(mem01)") = 0 then
say 'Deleted.'
LISTC (List Catalog)
Syntax:
LISTC([level][,dsnqual][,catalog][,option][,stem])
Arguments:
level is the 1 to 64 character name that identifies the data set or data sets for
which you want catalog information. This argument must never contain
single quotes. The userid is never appended to level.
You may use the asterisk (*) wild card character as long as you abide by
the rules for the LISTC LEVEL parameter (i.e., the asterisk cannot be the
last qualifier).
Note: If you do not specify level, the entire catalog will be listed. If the
catalog is large, this operation may take some time.
dsnqual is the 1 to 80 byte string containing LISTC command data set name
qualifiers. Keywords must be separated by at least one blank. Do not use
this argument to specify other LISTC keywords such as VOLUME or
ALL. This string is not checked by the interface. Any errors are detected
by IDCAMS itself.
catalog is the catalog containing the entry for the data set(s) to be listed. If a
password is required use the form catalog/password. The catalog
name must be fully qualified, without quotes. Userid is never appended
to the catalog name.
option one of the following may be specified:
'N' list only names. This is the default.
'V' list names and volume information.
stem the name of a stem array into which you want LISTC function output
directed. If you desire a true REXX stem, code a period suffix (e.g.,
"abc." will yield variables abc.1, abc.2. abc.n). If stem is not coded,
LISTC function output is directed to the REXX data stack.
Note: No zeroth variable is created. The number of stem elements

created is returned as a component of the function's value (see
"Returned Information" on the next page).

Module Name:
RXTLISTC
Environments:
The LISTC function is used to invoke the IDCAMS LISTCAT command. Using this
function you can retrieve lists of data set names and associated catalog information. The
LISTC function parses the LISTCAT command output and places the information in
records (one per data set) with fixed columns. The records are returned in the REXX data
stack (the default) or in a stem array.
Notes:
1. The LISTC function constructs a LISTCAT command of the form:
LISTCAT [LEVEL(level)] [dsnqual]

[CATALOG(cat/pw)] {VOLUME | NAME}
2. Refer to the Access Method Services publication for your system's level of DFP or
DFSMS for more information on the LISTCAT command.
3. If you need to execute a LISTCAT command with the ENTRIES keyword, do not use
the LISTC function. Use the LISTC command under ADDRESS IDCAMS.
The LISTC function returns a string containing the IDCAMS return code and the number
of records of information produced. These fields are separated by one blank. If you CALL
the LISTC function, the returned value is contained in the RESULT special variable. The
RC variable is unchanged (unless you assign the return code to it). A return code of zero
always indicates success.
Data set information is formatted into records with fixed columns. If the stem argument is
specified, the information is placed into a stem array. Otherwise, the information is
returned in the REXX data stack. In both cases, each data set is represented by exactly
one record.
IDCAMS 111
If you specify the "N" option (or allow it to be defaulted) only one column of information is
returned: the fully qualified data set name. If you specify the "V" option, the following
columns of information are returned:
Word Data Item Description

1. dsname Fully qualified data set name (no quotes).
2. volser Volume serial number. If the data set spans volumes,
only the first volser is reported.
3. unit Type of unit (e.g., "3390"). If the data set spans volumes,
only the first unit is reported.
4. type Type of catalog entry (e.g., "NONVSAM").
5. cdate The date the data set was created.
6. edate Expiration date.
7. storclass SMS storage class.
8. mgmtclass SMS management class.
9. dataclass SMS data class.
10. last back-up The date of the most recent back-up.
If a data item is unavailable, the interface supplies a single question mark (?) as a
placeholder. This ensures that the word position of all columns remains constant. By
default, the records are ordered by dsname in ascending sequence.
The LISTC function returns any "IDC" messages produced the LISTCAT command. The
messages are returned in a special array whose stem is $RXTIDCMS. The zeroth element
($RXTIDCMS.0) contains the number of messages produced by the command.
Notes:
1. Only "IDC" messages are returned in the $RXTIDCMS. stem array. The messages
are not in "ready-to-print" format (i.e., there are no printer control characters).
2. The function performs a REXX DROP on the $RXTIDCMS. stem prior to executing
the LISTCAT command.
3. The function performs a MARGINS command prior to executing the LISTCAT

command. Because of this, the first IDC message in the $RXTIDCMS. stem array is
the "FUNCTION COMPLETED" message for the MARGINS command.

Examples:
1. List all data sets with the SYS1 prefix:
parse value listc("sys1") with rc dsncount

if rc = 0 then
do i = 1 to dsncount
parse pull dsname; say dsname
end
2. List all data sets in a user catalog. Retrieve volume information and sort it by volser:
parse value listc(,,usercat,'v','lc.') with rc dc

if rc = 0 then do
if dc ] 1 then
if stemsort('lc.',,dc,'(46,6,CH,A)') = 0 then
do i=1 to dc; say lc.i; end
else
say 'sort failed'
else
say lc.1
end
else
say 'listc failed'
Note: Because it uses specific column positions for the sort, this program may
require modification to run with future releases of DFP, DFSMS, and REXXTOOLS.
3. Retrieve the names of all aliases whose first and third qualifier is "A". Search the
default catalog:
parse value listc('a.*.a','alias') with rc dsnc

if rc = 0 then
do i = 1 to dsnc
parse pull dsn; say dsn
end
IDCAMS 113
Data Set Information Functions
Most high-level language programs process a fixed number of data sets and are
generally "unaware" of the data set environment in which they run. REXXTOOLS
provides functions that extract data set environmental information which may be used to
generalize data set processing.
Introduction
The REXXTOOLS data set information functions are:
DDNINFO returns in-memory allocation and DCB information for a ddname.
DSNINFO returns catalog, VTOC, space allocation and utilization, SMS class, and
ddname information for single-volume DASD data sets.
LISTA returns allocation information for one or more ddnames. A ddname

pattern containing wildcard characters may be specified.
LISTM returns PDS/PDSE directory information for one or more members.
Using the data set information functions, you can make your applications more flexible
and able to anticipate problems before they occur. For example, the following code
examines the extents and directory blocks of a partitioned data set prior to creating new
members. If not enough space is available, the program can take steps to prevent an out-
of-space abend before it occurs:
parse value dsninfo("'prod1.data'",'mvs001','f') with rc,

. . . . . . . . . . . . . . . . . . . . . . .,
extents . . . . . adirblks udirblks .
if rc <> 0 then do
say 'Unable to obtain data set information.'
exit 8
end
if (extents > 14) | ((adirblks-udirblks) < 3) then do
/* 1. Allocate a new and bigger data set.
2. Copy members from the old data set to the new.
3. Delete the old data set.
4. Rename the new data set with the old dsname. */
end
/* Create the new members */
The data set information functions are integrated into the REXXTOOLS function package.
To use the functions, simply code references to them in your programs.
Note: The DSNINFO and DDNINFO functions rely on MVS/SP 4.2 (or later) and
MVS/DFP 3.3 (or DFSMSdfp) services to provide complete results. If your system is
running earlier levels of this software some data items will not be available. To determine
operating system software levels on your system, execute the REXXTOOLS OSENVIR
exec.
Data Set Information Functions 115

Specifying Data Set Names
The DSNINFO and LISTM functions require that you specify the name of a data set as
the primary argument. The syntax rules for the data set name argument are as follows:
• The data set name may be passed as a literal string or in a REXX variable.
• If the data set name is fully qualified, this must be indicated by enclosing it in single
quotes. The single quotes must be a part of the argument (not merely the enclosing
quotes for a REXX literal), as the following code demonstrates:
call dsninfo "'sys1.parmlib'"
• If the data set name is not enclosed in single quotes, a fully qualified name is
automatically derived by appending the user ID to the front of the name. The user ID
is obtained from the IRXUID module (or installation replacement).
• If the data set is not cataloged, you must specify the volume serial number. Both
DSNINFO and LISTM accept volume serial number in the argument following the
data set name.
• DSNINFO supports generation data group (GDG) data set names. You can specify
GDG data set names in one of two ways:
o Specify the specific generation, as in: GDG01.G0001V00.
o Specify the relative generation number, enclosed in parentheses, as in:

GDG01(-1).
• DSNINFO accepts but ignores member names. Information will be returned for the
entire data set.
• LISTM accepts member names. The names may be fixed, or may contain wild card
characters (see next section). If a member name is not specified, LISTM behaves as
if you had coded a single asterisk for the member name. For example,
listm("'sys1.samplib'") is equivalent to listm("'sys1.samplib(*)'")

Using Pattern Matching
The LISTA and LISTM functions permit the specification of ddname and member name
patterns, respectively. Patterns may be composed of letters, numbers, national
characters, and "wild card" characters. The letters, numbers, and national characters of a
pattern must match exactly with the characters in corresponding positions in a ddname or
member name. Because of this, these characters are referred to as "fixed". Conversely,
the wild card characters are used to generalize a pattern so that it will match more than
one entity.
The valid wild card characters and their meanings are as follows:
* (asterisk) indicates that zero or more characters, of any type, will match.
? (question mark) indicates that a single character, of any type, will match.
% (percent sign) indicates that a single character, of any type, will match.
Notes:
1. To find all entities with a fixed prefix, use a pattern with the fixed characters followed
by an asterisk (e.g., abc*).
2. To find all entities with a fixed suffix, use a pattern with an asterisk followed by the
fixed characters (e.g., *abc).
3. Prefix and suffix type patterns can be combined, as in abc*123.
4. LISTM and LISTA automatically translate their arguments to uppercase letters.

Because of this, a pattern of aBc will match with a ddname or member name of ABC.
5. A pattern composed only of fixed characters will match one (and only one) entity
(ddname or member name).
6. Multiple consecutive asterisks are treated as one asterisk. Thus, abc*** is the same
as abc*.
Examples:
abc* Select all entities that begin with "ABC".

*yxZ Select all entities that end with "XYZ".
abc*xyz Select all entities that begin with "ABC" and end with "XYZ" (this includes
"ABCXYZ").
??? Select all 3-character entities.
Abc??? Select all 6-character entities that begin with "ABC".
??* or *?? Select all entities having at least 2 characters.
a*b*c Select all entities that begin with "A", end with "C", and have "B" somewhere in
the middle.

Parsing Returned Values
VERY IMPORTANT: Open Software recommends that you do not use fixed or relative
position parsing with the data set information functions (you also should avoid using the
SUBSTR function). Future releases of operating system software or of REXXTOOLS may
change the lengths of various values.
To provide maximum flexibility, the data set information functions do not return values in
pre-defined variables. Instead, these functions return information using one or more of
the following methods:
• Information is returned as the function's value (i.e., a string). Individual data items are
contained in blank-delimited words within the string.
• Information is returned in the REXX data stack. Individual columns of information are
blank-delimited.
• Information is returned in user-defined stem variables. Individual columns of

information are blank-delimited.
Missing information (information that the function was unable to derive) is indicated with a
question mark (?). The question mark serves as a placeholder for the information,
thereby ensuring that the relative word position of each data item remains constant.
String Parsing
The most convenient way to separate a returned string into its components is with the
REXX PARSE instruction. For example, one variation of the LISTM function returns a list
of member names as a part of its returned value. To process each member name you
could use the following code:
parse value listm("user.data(abc*)") with rc mc mlist

if rc = 0 then
do i = 1 to mc
parse var mlist member mlist
say member
end
In this example, PARSE VALUE breaks the string returned by LISTM into 3 variables.
The first word, which contains the return code, is assigned to a variable named RC. The
second word, which contains the number of member names returned, is assigned to a
variable named MC. And the list of member names is assigned to the MLIST variable.
Subsequently, the PARSE VAR instruction is used to extract each member name from
MLIST. PARSE VAR assigns the first word of MLIST to the MEMBER variable, and the
remainder of the list is re-assigned to MLIST itself. Thus, each iteration of the loop
reduces MLIST by one word.
Another way to parse MLIST is to use the REXX WORD function, as is shown in the
following code segment:
do i = 1 to words(mlist)
say word(mlist,i)
end

For small numbers of words, this method works pretty well. Its performance can degrade,
however, when the list of words is large. This is because the WORD function must count
out to the desired word with every invocation. As your loop extracts each word -- working
from left to right -- later iterations take longer as WORD searches farther and farther
down the string. If you use the PARSE VAR technique, the last extraction performs just
as quickly as the first because it never searches beyond the first word.
Stack and Stem Parsing
Certain forms of the LISTA and LISTM functions return rows of information in the REXX
data stack or in stem variables. The returned rows contain columns of blank-delimited
information that may be deconstructed using the PARSE instruction or the WORD
function. In the following example, rows of information are pulled from the data stack and
parsed into variables using the PARSE instruction:
parse value listm(dsname,,,'u') with rc mc

if rc = 0 then
do i = 1 to mc
parse pull name ttr alias userfld
end
When LISTA or LISTM output is directed to stem variables, you may use the "VAR"
variant of the PARSE instruction to separate the fields:
parse value listm(dsname,,,'u','mystem.') with rc mc

if rc = 0 then
do i = 1 to mc
parse var mystem.i with name ttr alias userfld
end
Note: When a stem variable is specified, the interface always performs a REXX DROP
(un-assign) operation on the stem prior to loading it with new information. This prevents
your program from inadvertently processing data from an earlier invocation. For this
reason, you must explicitly save any stem data that you want to keep prior to invoking the
data set information function (or use a different stem name).
Using the Period Placeholder
One advantage of using PARSE is that you can specify the names of the variables into
which values are placed. Another important advantage, is that you can completely skip
any information you do not need. Skipping non-essential information can make your
programs run faster and use less storage.
To skip information with PARSE, use the period placeholder. The period placeholder
works exactly like a template variable except that no variable is created. For example, if
we want only the data set name from a call to DDNINFO we can code:
parse value ddninfo('isptabl') with rc . dsname .

if rc = 0 then say 'ISPTABLE is allocated to' dsname
In this example, the ddname is skipped with the first period placeholder, and all data
items after dsname are assigned to the second period placeholder. Only the RC and
DSNAME variables are created.

DSORG, Status, and Disposition
Several of the data set information functions return information regarding the organization
and allocation of a data set. The following sections describe the meaning of these values.
DSORG
CX Communications line group.
DA Direct access data set.
DAU Direct access data set unmovable.
GS Graphic data control block.
IS Indexed sequential data set.
ISU Indexed sequential data set unmovable.
PO Partitioned data set.
PO-E Partitioned data set extended. This is a synthetic designation produced by the
DDNINFO and DSNINFO functions. For LISTA, a PDSE is designated PO,
making it indistinguishable from a PDS.
POU Partitioned data set unmovable.
PS Physical sequential data set.
PSU Physical sequential data set unmovable.
VS VSAM data set.
Status
MOD The data set may or may not be new. If it already existed, records are being
added to the end of the data set. The data set is held exclusively.
NEW The data set is being created in this step.
OLD The data set exists and is held exclusively.
SHR The data set exists and is shared with other users.
Disposition
CATLG
A catalog entry is to be created at the end of the job step.
DELETE
The data set is to be deleted (removed from the catalog and the VTOC) at the
end of the job step.

KEEP The data set is to be kept on the volume at the end of the job step.
PASS The data set is to be passed to a subsequent step within the same job.
UNCATLG
The data set is to be removed from the catalog at the end of the job step. The
data set is not removed from the VTOC.
Required Reading and Examples

PARSE is a powerful component of the REXX language, one with which you will want to
become intimately acquainted. For more information on REXX parsing see "Appendix A:
Working with Record Fields" on page 279. For a definitive explanation of PARSE, read
chapter 5 of TSO/E Version 2 REXX/MVS Reference, SC28-1883.
The REXXTOOLS exec library contains several utility programs that demonstrate the
data set information functions. These are:
DDINFO a command that uses the DDNINFO function to report information about
an allocated ddname. This exec contains a complete PARSE template
for DDNINFO. You can use this template as a starting point for your own
programs.
DSINFO a command that uses the DSNINFO function to report information about
a cataloged or un-cataloged single-volume DASD data set. This exec
contains a complete PARSE template for DSNINFO. You can use this
template as a starting point for your own programs.
LA a command for listing allocations. This exec demonstrates the use of the
LISTA function.
LM a command for listing PDS/PDSE directory information using the LISTM

function.
Return Codes and Messages

The data set information functions do not set the RC variable. However, you may assign
the function's return code to the RC variable, if you so choose. The first word of the
returned value for all of the data set information functions is always the return code. A
return code of zero indicates successful execution.
In most cases, a non-zero return code is taken directly from the underlying system
service that failed. In other cases, the return code is either an abend code or a synthetic
code set by the REXXTOOLS function.
Whenever a data set information function returns a non-zero return code, the rest of the
return string will contain diagnostic information that indicates:
• The name of the entity (data set, ddname, member) that had a problem.
• If possible, a reason code from an underlying service.

• The name of the service that detected the problem.
• Text describing the nature of the problem.
In addition to this information, the system may produce messages indicating the source
of the problem. You should always examine these messages (and their descriptions)
when conducting problem determination.
Partial results are possible whenever a non-zero return code is encountered. For this
reason, you must always check the return code.
Descriptions of relevant system service return codes, reason codes, and messages can
be found in the following IBM manuals for your system's level of MVS, DFP or DFSMS:
Service IBM Publication

DYNALLOC MVS/ESA Authorized Assembler Services Reference (various
volumes)
RACROUTE
UCBSCAN MVS/ESA Authorized Assembler Services Guide
DEVTYPE MVS/DFP System Programming Reference
IGWASMS
DFSMS/MVS Using Advanced Services Data Sets
LOCATE
OBTAIN
TRKCALC
CLOSE MVS/DFP Macro Instructions for Data Sets

OPEN
DFSMS/MVS Macro Instructions for Data Sets
All Services MVS/ESA System Messages (various volumes)

The sections that follow describe the syntax and operation of the data set information
functions.
DDNINFO
Syntax:
DDNINFO(ddname)
Arguments:
ddname is the 1 to 8 character ddname for which you want information. The
ddname must be allocated at the time DDNINFO is invoked.
Module Name:
RXTDDNIF
Environments:
The DDNINFO function is used to extract in-storage information about a ddname. The
information is taken from the Task Input Output Table (TIOT) and the Job File Control
Block (JFCB) for the ddname.
Notes:
1. If more than one data set is associated with the ddname, only information for the first
data set is returned. If that data set spans volumes, only information about the first
volume is returned.
2. If the ddname has not been opened, the DCB information (RECFM, LRECL,
BLKSIZE) will not be available.
3. MVS/SP 4.2 and DFP/MVS 3.3 are the minimum software levels for DDNINFO. If
your software is older than this, some data items may not be available.

The DDNINFO function returns a string containing the return code and ddname
information or an error message.
When the return code is zero, the fields below are returned (separated by one blank):

1. rc Return code.
2. ddname The data definition name.
3. dsname The first or only data set associated with the ddname. The
data set name is fully qualified (no quotes).
4. volser Volume serial number. If the data set spans volumes, only
the first volser is reported.
5. unit Type of unit (e.g., "3390"). If the data set spans volumes,
only the first unit is reported.
6. dsorg Data set organization. PDSE data sets are indicated with the
"PO-E" designation.
7. recfm The record format. If the data set is a VSAM data set, it is
possible that the record organization will be reported (e.g.,
"KSDS").
8. lrecl The logical record length.
9. blksize The block size.
10. dsntype The SMS data set type.
11. storclas SMS storage class.
12. mgmtclas SMS management class.
13. dataclas SMS data class.
14. status The allocation status.
15. ndisp The normal disposition.
16. cdisp The conditional disposition.
placeholder. This ensures that the word position of all data items remains constant.
If the return code is non-zero, the fields returned are as follows:

1. rc Return code.
2. ddname The data definition name.
3. reason The reason code in printable hex, or 8 zeros if not
applicable.
message A textual message describing the service detecting the error,
and the nature of the error. The message can (and usually
does) contain embedded blanks.

If you CALL the DDNINFO function, the returned value is contained in the RESULT
special variable. The RC variable is unchanged (unless you assign the return code to it).
A return code of zero always indicates success.
Example:
1. Retrieve ddname information for SYSPRINT:
parse value ddninfo("sysprint") with rc SysprintInfo

if rc = 0 then
parse var SysprintInfo ddname dsname volser unit,
dsorg recfm lrecl blksize,
dsntype sclass mclass dclass,
status ndisp cdisp
else
parse var SysprintInfo ddname reason message

DSNINFO (Data Set Information)
Syntax:
DSNINFO(dsname[,volser][,option])
Arguments:
dsname is the 1 to 64 character name of the data set for which you want
information. If a member name is supplied, it is ignored. A relative
generation name may be specified using the standard notation (e.g.,
mygdg(-3)). If you fully qualify the data set name, you must enclose it in
single quotes (see examples below). If dsname is not enclosed in single
quotes, the userid (as determined by IRXUID) will be appended to the
front. For more information on specifying data set names see "Specifying
Data Set Names".
Note: If the data set is not cataloged, you must specify the volser
argument.
volser is the 1 to 6 character volume serial number identifying the volume upon
which the data set resides. If the data set is not cataloged, you must
specify this argument. If the data set is cataloged, you do not need to
specify volser; a catalog search will find the correct volume for you.
option indicates the type of processing desired. The valid options are:
'B' indicates basic information is to be returned (see "Returned

Information" below). This is the default.
'F' indicates full information is to be returned.
Module Name:
RXTDSNIF
Environments:
The DSNINFO function is used to retrieve catalog, VTOC, allocation, space, directory,
and SMS information for single volume, DASD data sets.
Notes:
1. If more than one volume is associated with the data set, only information about the
first volume is returned.
2. For VSAM data sets, only the following are returned:
o Catalog group.

o DSORG of the VTOC group (DSORG=VS).
o Allocation group.
All other items will contain question marks.
3. If the data set is not allocated, allocation information will not be present.
4. If the data set is not managed, SMS information will not be present.
5. If the data set is not partitioned, directory information will not be present.
6. If directory information is requested, but the user is not authorized to open the data
set for input, directory information will not be present. No error indication is given.
7. If directory information is requested, but another user holds an exclusive enqueue for
the data set (i.e., it is allocated DISP=OLD), directory information will not be present.
No error indication is given.
8. If allocation units cannot be determined, tracks is assumed. In this situation, the units
value will be "TRACKS?".
9. The values for blocks/track, tracks/cylinder, and cylinders/volume are obtained from
the TRKCALC and DEVTYPE macros. For more information on this topic, refer to
DFP System Programming Reference, or DFSMS Using Advanced Services for Data
Sets.
10. When allocation units is "BLOCKS", the number of blocks allocated is determined by
adding up the total number of tracks allocated and dividing the result by the number
of blocks per track. However, this number is only an estimate, because the data set
may contain short blocks (blocks less than BLKSIZE length).
11. The number of units used is based on the DS1LSTAR field of the format 1 DSCB
(Data Set Control Block). DS1LSTAR has 2 parts, the number of tracks and the
number of records (blocks). The computation for units used is as follows:
o For cylinder allocations, the tracks part of DS1LSTAR is converted to cylinders. If

the records portion of DS1LSTAR is not zero, the used cylinders value is
increased by one.
o For track allocations, the tracks part of DS1LSTAR is used as is. If the records
portion of DS1LSTAR is not zero, the used tracks value is increased by one.
o For block allocations, the tracks part of DS1LSTAR IS multiplied by the number
of blocks per track, and the records portion is added in to obtain blocks used.
The lesser of blocks used or blocks allocated is returned (i.e., blocks used will
never exceed blocks allocated).
12. MVS/SP 4.2 and DFP/MVS 3.3 are the minimum software levels for DSNINFO. If
your software is older than this, some data items may not be available.
13. An example of DSNINFO is contained in the DSINFO exec of the REXXTOOL.EXEC

library. This example contains a complete parsing template for DSNINFO.

The DSNINFO function returns a string containing the return code and data set
information or an error message.
When the return code is zero, the fields below are returned (the fields are separated by
one blank).
Word Data Item Option Group Description

1. rc B N.A. Return code.
2. dsname B Catalog The data set name (fully qualified, no quotes).
3. volser B Catalog Volume serial number. If the data set spans
volumes, only the first volser is reported.
4. unit B Catalog Type of unit (e.g., "3390"). If the data set
spans volumes, only the first unit is reported.
5. dsorg B VTOC Data set organization. PDSE data sets are
indicated with the "PO-E" designation.
6. recfm B VTOC The record format.
7. lrecl B VTOC The logical record length.
8. blksize B VTOC The block size.
9. keylen B VTOC Hardware key length (not usually present).
10. rkp B VTOC Relative key position (not usually present).
11. created B VTOC Date of creation.
12. expires B VTOC Date the data set expires (is deleted).
13. referenced B VTOC Date most recently opened.
14. password B VTOC READ
Password required for reading and writing.
WRITE
Password required to write but not read.
?
No password required.
15. updated B VTOC 1
Data set opened for other than INPUT since
last back-up.
0
Data set only opened for INPUT since last
back-up.
16. racfprof B VTOC 1
Data set is protected by a discrete profile.
0
Data set's protection is unknown.
17. managed B VTOC 1
Data set is managed.
0
Data set is not managed.
18. ddname B Alloc. The data definition name.
19. status B Alloc. The allocation status.
20. ndisp B Alloc. The normal disposition.
21. cdisp B Alloc. The conditional disposition.

Word Data Item Option Group Description
22. units F Space The units by which the data set is allocated
(CYLINDERS, TRACKS, BLOCKS).
23. alloc F Space Number of units presently allocated.
24. used F Space Number of units presently used.
25. extents F Space Number of extents presently allocated.
26. primary F Space Number of units specified for primary
allocation.
27. secondary F Space Number of units specified for secondary
allocations.
28. blkstrk F Space Number of blksize blocks that will fit on a
track on this volume.
29. trkscyl F Space Number of tracks per cylinder for this
volume
30. cylsvol F Space Number of cylinders for this volume
31. adirblks F Dirctry Number of directory blocks allocated. Not
available for PDSEs.
32. udirblks F Dirctry Number of directory blocks in use.
33. members F Dirctry Number of members.
34. dsntype F SMS The SMS data set type.
35. storclass F SMS SMS storage class.
36. mgmtclass F SMS SMS management class.
37. dataclass F SMS SMS data class.
placeholder. This ensures that the word position of all data items remains constant.
If the return code is not zero, the following data items are returned.

1. rc Return code.
2. dsname The data set name (fully qualified, no quotes).
3. reason The reason code in printable hex, or 8 zeros if not applicable.
message A textual error message describing the service detecting the
error, and the nature of the error. The message can (and
usually does) contain embedded blanks.
If you CALL the DSNINFO function, the returned value is contained in the RESULT
special variable. The RC variable is unchanged (unless you assign the return code to it).
A return code of zero always indicates success.

Examples:
1. Retrieve full information for a cataloged data set. The userid will be automatically
appended to the dsname argument:
parse value dsninfo("user.data",,'f') with rc info

if rc = 0 then
parse var info dsname volser unit dsorg recfm lrecl,
blksize keylen rkp created expires referenced,
password updated racfprof managed ddname,
status ndisp cdisp units alloc used extents,
primary secondary blkstrk trkscyl cylsvol,
adirblks udirblks members dsntype sclass mclass,
dclass
else
parse var info dsname reason message
2. Retrieve basic information for a data set that is not cataloged. The userid will not be
automatically appended to the dsname argument:
parse value dsninfo("'sys1.lib1'",'mvs001') with rc info

if rc = 0 then
parse var info dsname volser unit dsorg recfm lrecl,
blksize keylen rkp created expires referenced,
password updated racfprof managed ddname,
status ndisp cdisp
else
parse var info dsname reason message

LISTA (List Allocations)
Syntax:
LISTA([ddpattern][stem])
Arguments:
ddpattern is the 1 to 8 character name that identifies the ddname or ddnames for
which you want allocation information. If the pattern does not contain any
wild card characters, at most, information for one ddname will be
returned. For more information on specifying this argument, see "Using
Pattern Matching".
Note: If ddpattern is not specified, information for all currently allocated

ddnames will be returned.
stem the name of a stem array into which LISTA is to direct ddname
information. If you desire a true REXX stem, you must code a period
suffix. For example, coding "abc." will yield variables of the form abc.1,
abc.2. abc.n.
If stem is not coded, ddname information is queued to the REXX data

stack.
Note: No zeroth variable is created. The number of stem elements

created is returned as a component of the function's value (see
"Returned Information").
Module Name:
RXTLISTA
Environments:
The LISTA function is used to retrieve current allocation environment information. One
record of information is produced for each ddname matching the ddpattern argument.
The records are returned in the REXX data stack (the default) or in a stem array.
Notes:
1. LISTA uses the DYNALLOC information function to extract allocation environment

information. DYNALLOC obtains an authorized, job-step-wide enqueue on
SYSZTIOT to prevent abends. In multi-tasking environments, contention for
SYSZTIOT can cause a task using LISTA to wait.
2. In multi-tasking environments, it is possible for the information returned by LISTA to

change even as it is being gathered. This is because other tasks can allocate new

ddnames and/or free others while LISTA is executing.
3. Refer to the Authorized Assembler Services Guide for your system's level of MVS or
OS/390 for more information on the DYNALLOC service.
4. The LISTA function, itself, does not run authorized (i.e., no APF, no supervisor state,
no authorized storage keys). All authorized work is performed by SVC 99
(DYNALLOC).
The LISTA function returns a string. The contents of the string depends on the success of
the operation.
If the return code is zero, LISTA returns the return code and the number of ddname
information records produced. The return code and the record count are separated by
one blank. If the stem argument is specified, the ddname records are placed into a stem
array. Otherwise, the records are returned in the REXX data stack. A ddname is
represented by exactly one record.
The records of ddname information are structured as follows:

1. ddname The data definition name. This field is exactly 8 bytes in
length (i.e., it is blank-padded to permit sorting).
2. dsncount The number of dsn groups that follow. This field is exactly 3
bytes long and right-justified to facilitate sorting.
dsngroups Data set information groups. Each group describes a data
set.
The content of each data set information group is as follows:

1. dsname fully qualified data set name.
2. dsorg data set organization.
3. status allocation status.
4. ndisp normal disposition.
5. cdisp conditional disposition.
placeholder. This ensures that the word position of all data items remain constant.
The order of the ddname records is not defined. However, you can use the REXXTOOLS
STEMSORT function to sort the records into ddname or dsncount order. The dsngroups
within each ddname record are in allocation order.

Note: LISTA performs a REXX DROP on the stem (if specified) prior creating the
ddname records.
If the return code is not zero, the function's returned value consists of:

1. rc the DYNALLOC return code.
2. reason the DYNALLOC reason code in printable hexadecimal
digits.
message a textual message describing the error. This message can
contain embedded blanks.
Depending on the nature of the error, a partial result -- in the form of stem variables or
stack entries -- is possible.
If you CALL the LISTA function, the returned string is contained in the RESULT special
variable. The RC variable is unchanged (unless you assign the return code to it). A return
code of zero always indicates success.
Examples:
1. List all currently allocated ddnames:
parse value lista() with rc ddncount

if rc = 0 then do i=1 to ddncount
parse pull ddname .; say ddname; end
else do
parse var ddncount reason message
say 'LISTA error:' message
end
2. List all ISPF allocations, sorted by ddname:
parse value lista('isp*','dd.') with rc dd.0

if dd.0>1 then call stemsort 'dd.',,,'(1,8,ch,a)'
do i=1 to dd.0
parse var dd.i ddname dsncount dsngrps
say ddname
do j=1 to dsncount
parse var dsngrps dsn do st nd cd dsngrps
say left(do,3) left(st,3) left(nd,7) left(cd,7) dsn
end
say
end

LISTM
Syntax:
LISTM(dsname[,volser][,maxcount][,option][,stem])
Arguments:
dsname is the 1 to 64 character data set name that identifies the PDS or PDSE.
The valid formats for dsname are:
datasetname
and
datasetname(memberpattern)
If the data set name is fully qualified, the dsname argument must be
enclosed in single quotes. If it is not enclosed in single quotes, the userid
(as determined by IRXUID) will be appended to the front. For more
information see "Specifying Data Set Names".
If memberpattern does not contain any wild card characters,

information retrieval begins with the member name given, or at the next
highest member name, if the specified member does not exist. For more
information on member pattern matching see "Using Pattern Matching".
Note: If memberpattern is not coded, it is the same as specifying

datasetname(*).
volser is the 1 to 6 character volume serial number identifying the volume upon
which the data set resides. If the data set is not cataloged, you must
specify this argument. If the data set is cataloged, you do not need to
specify volser; a catalog search will find the correct volume for you.
maxcount specifies the maximum number of members for which you want
information retrieved. If this argument is not coded, information for all
members satisfying the dsname argument is returned.
option indicates the type of processing desired. The valid options are:
'N' return member names only. This is the default. The member
names are returned as a component of the function's value.
Neither stem variables nor stack entries are created.
'S' return directory entries. If the user field of an entry contains ISPF
statistics, it is returned in a printable format. The information is
returned in either stem variables or the REXX data stack.
'U' return directory entries. The user field of an entry is returned in

raw binary format (which may not be printable). The information
is returned in either stem variables or the REXX data stack.

stem the name of the stem array into which LISTM is to place directory
information. If you desire a true REXX stem, you must code a period
suffix. For example, "abc." will yield variables of the form abc.1, abc.2.
abc.n.
If stem is not coded (and option "S" or "U" is used), directory entries are
queued to the REXX data stack.
Notes:
1. No zeroth variable is created. The number of stem elements created

is returned as a component of the function's value (see "Returned
Information").
2. The stem argument applies only to options "S" and "U". For option
"N", the stem argument is ignored.
Module Name:
RXTLISTM
Environments:
The LISTM function is used to retrieve PDS/PDSE directory information. If member

names are requested (option "N"), these are returned as blank-delimited words in the
LISTM's value. If full directory information is requested (options "S" and "U"), one record
of information is produced for each directory entry that matches the dsname argument.
The records are returned in the REXX data stack (the default) or in a stem array.
Notes:
1. LISTM must allocate the data set (DISP=SHR) prior to reading its directory. If another
user has exclusive use of the data set, LISTM's dynamic allocation request will fail.
An error indication is given.
2. LISTM must open and read the data set's directory. If the user does not have
sufficient authority, the request will fail. An error indication is given.
3. Listing very large directories in their entirety can:
o take a significant amount of time, and
o cause out-of-storage abends.
If you must process all of the members of a large directory, you may want to increase
your region size, and/or use a member pattern and maxcount to process blocks of
member entries.

4. If you are using an application-specific locking protocol you must incorporate your
use of LISTM into that protocol.
5. When ISPF statistics are requested, LISTM examines the user field of each directory
entry to determine if valid statistics are present. If the validation check fails, no
conversion is performed, and ISPF statistics are omitted from the member's record.
No error indication is given.
6. If a member's directory entry does not contain a user field, and option "S" or "U" is
specified, the output record will not contain user field information. No error indication
is given.
7. Certain versions of ISPF support directory entries with 4-digit years. LISTM
recognizes these entries, and will correctly report dates beyond 1999. Refer to IBM's
documentation for more information on ISPF's 4-digit year support.
Performance Considerations:
As you design your application keep the following points in mind:
1. The "N" option provides the best performance and uses the least amount of storage.
If you do not require TTR or user field information, you should use this option. Refer
to the topic "Parsing Returned Values" for more information.
2. If you are using the BPAM functions to read listed members, you may want to
consider using the "S" or "U" options of LISTM in conjunction with the TTR form of
FINDM. The TTR form of FINDM locates a member without performing a search. You
must ensure that the members to be processed are not re-written -- by your task or
another -- prior to calling FINDM. Re-writing a member changes its TTR.
3. A prefix member pattern (e.g., "abc*"), in most cases, performs better than a suffix
pattern (e.g., "*abc").
The LISTM function returns a string. The contents of the string depends on the value of
the option argument, and the success of the operation. The following table describes the
contents of the returned string under various conditions.
Return Code Option N Option S or U

Zero rc membercount memberlist rc membercount
Not Zero rc reason dsname message rc reason dsname message
The components of the returned string are as follows:
rc the return code.
membercount the number of members listed.
memberlist a blank-delimited list of member names.

reason the reason code (in printable hexadecimal characters) of the failing
service.
dsname the name of the data set.
message a textual message giving the name of the failing service and a
description of the error. The message contains embedded blanks.
If you CALL the LISTM function, the returned string is contained in the RESULT special
variable. The RC variable is unchanged (unless you assign the return code to it). A return
code of zero always indicates success.
If option "S" or "U" is specified, and the return code is zero, LISTM returns zero or more
records of directory information. If the stem argument also is specified, the records are
placed into a stem array. Otherwise, the records are returned in the REXX data stack. A
member's directory entry is represented by exactly one record.
When the "S" option is used, the records of directory information are structured as
follows:

1. name The name of the member.
2. ttr The address of the member in TTR (Track and record) format. The
address is 6 printable hexadecimal digits.
3. c The alias bit of the "C" byte of the directory entry. A value of "1"
indicates that the entry is an alias entry. A value of "0" indicates that
the entry is a primary entry.
4. vv ISPF version number.
5. mm ISPF modification level.
6. cdate ISPF creation date in CCYY.DDD format (Julian date with 4-digit
year).
7. mdate ISPF modification date in CCYY.DDD format (Julian date with 4-digit
year).
8. mtime SPF modification time in HH:MM:SS format.
9. cl ISPF current lines.
10. il ISPF initial lines.
11. ml ISPF modified lines.
12. muserid ISPF last modification user ID.
If an entry does not contain a user field, or if the user field does not appear to contain
ISPF statistics, only the name, ttr, and c fields will be returned. No placeholders are
supplied for the missing ISPF statistics.

If the "U" option is used, the records contain the following fields:

1. name The name of the member.
2. ttr The address of the member in TTR (Track and record) format. The
address is 6 printable hexadecimal digits.
3. c The alias bit of the "C" byte of the directory entry. A value of "1"
indicates that the entry is an alias entry. A value of "0" indicates that the
entry is a primary entry.
userfield The user field of the entry in raw binary format. This field may contain
embedded blanks.
If an entry does not contain a user field, only the name, ttr, and c fields will be returned.
No placeholder is supplied for the missing user field.
Notes:
1. LISTM performs a REXX DROP on the stem (if specified) before creating the
ddname records.
2. Member records are returned in the order in which they are read.
3. Depending on the nature of an error, a partial result -- in the form of stem variables or
stack entries -- is possible.
Examples:
1. List all member names for a PDS. The data set name is fully qualified:
parse value listm("'user01.pli'") with rc memcnt mlist

if rc = 0 then do i=1 to memcnt
parse var mlist mem mlist; say mem; end
else do
parse var memcnt reason dsn message
say 'LISTM error:' message
end
2. List the ISPF statistics for all members that start with "R" and end with "05":
parse value,
listm("user.exec(r*05)",,,'s'),
with rc memcount
do i=1 to memcount
parse pull line; say line
end
3. Retrieve directory entries with unformatted user fields into stem "de.". We only want
the entries of members with 5-character names:
parse value,
listm("user.data(?????)",,,'u','de.'),
with rc de.0
do i=1 to de.0; say de.i; end

MVS Supervisor Services
The REXXTOOLS/MVS function package includes functions that provide access to MVS
control program services. Using these services, you can write programs that:
• Explicitly manage virtual storage.
• Obtain system-wide control of resources before using them.
• Query the system authorization facility about the user's authority to use a resource.
• Write messages to the system log and to the system operator's console.
Environmental Issues
The MVS supervisor service functions of REXXTOOLS/MVS provide only those services
that are available to all problem state programs. Privileged operations (those requiring
APF authorization, supervisor state, or key zero) are not supported.
Unless stated otherwise, MVS supervisor services are MVS task-related. Any resources
allocated or reserved using the MVS supervisor services functions, but not freed or
released, will be automatically cleaned-up by the control program at task termination.
Thus, a REXX program that is executed using either the EXEC command or implicit
execution, will have any "dangling" resources cleaned-up for it when the EXEC
terminates. No termination clean-up takes place for REXX programs invoked using either
the CALL instruction or the function call, since they do not run on a new MVS task level. If
you do not explicitly free resources allocated by programs invoked in this way, and if they
are repeatedly invoked from the same task, unpredictable abends may occur.
Virtual Storage Management

Two functions are provided for virtual storage management:
GETMAIN a function for requesting an allocation of virtual storage.
FREEMAIN a function for relinquishing virtual storage.
When you allocate virtual storage, the storage is assigned to a subpool. You can control
which subpool an individual allocation is assigned to using the sp argument. The valid
range of subpool numbers is 0 to 127. If you do not specify a subpool, subpool zero is
assumed. By grouping related storage allocations into the same subpool, you can release
several areas with a single FREEMAIN.
When used with the REXX STORAGE function (or the REXXTOOLS STORAGEX
function), virtual storage can be used to communicate between REXX programs and
programs written in other languages, such as assembler. For example, by allocating a
work area and passing the address of the work area to a called (or linked) program, you
can economically pass a large and complex data structure. Moreover, if the called
MVS Supervisor Services 139

program modifies the data structure, the calling (REXX) program will have access to the
changes when control is returned.
Resource Control
A common programming problem is the synchronization of asynchronous processes for
the purpose of sharing a resource. REXXTOOLS/MVS supports two sets of functions that
address this problem. The first set permits you to acquire and release control of arbitrary
resources. There are two functions that support this function. These are:
ENQ a function for acquiring control of a resource before using it. The caller of ENQ
can optionally wait for a resource if it is not immediately available.
DEQ a function for releasing a previously ENQed resource.
The MVS ENQ/DEQ facility can be thought of as a system-wide resource reservation

system. Before you use a resource, you must first make a reservation using the ENQ
function. When you are finished with the resource, you "check out" using the DEQ
function. Note though, that for arbitrary, user-defined resources, there is nothing in the
system to prevent cheaters (i.e., programs that use resources without first reserving
them). The ENQ/DEQ mechanism works only as long as all the participating programs
"play by the rules."
Note: If you are considering writing multiple user VSAM-based applications, and you
want to provide record (control interval) level locking, you will need to use the ENQ and
DEQ functions. The details of this process are described in the IBM publication MVS/ESA
Using Data sets, SC26-4749.
The second set of synchronization functions are for halting the execution of programs
until conditions are such that execution can continue. These are:
WAIT a function for halting the execution of a REXX program. A program can wait on a
timer to expire or for the completion of an arbitrarily defined event.
POST a function for signaling the completion of an arbitrary event.
The non-timer forms of WAIT and POST require the use of a 4 byte control block know as
the Event Control Block (ECB). Since the ECB is identified by a storage address, its
explicit allocation (either via the GETMAIN function or some other equivalent program) is
required.
Security
The MVS System Authorization Facility (SAF) provides a centralized and generalized
mechanism for directing authorization requests to whatever system security package
your installation is running (RACF, ACF2, Top Secret, etc.). Authorization requests are
implicitly made whenever you use certain system resources, such as data sets. The
access methods (like VSAM) invoke the SAF to provide protection for the resources (data
sets) that they manage. However, the protection provided by the SAF and your security
package is not limited to data sets. Arbitrary resources can be defined and protected
using user-supplied programs as the resource managers.

The REXXTOOLS/MVS interface to the SAF is the RACROUTE function. Your REXX
programs can protect an arbitrary resource by calling RACROUTE and passing the name
of the resource. If your security administrator has defined the resource, and if the user
has been authorized to use the resource, the RACROUTE function will return an
indication that the access is to be allowed. RACROUTE, itself, does not allow or deny
access to a resource. Your program, the resource manager, must do that part.
Notes:
1. The SAF must be active and the router table must be properly configured in order for
RACROUTE requests to be propagated to the system security package.
2. Not all RACROUTE functions are supported. Specifically, the parameters requiring
APF or key zero, supervisor state authorizations are not supported. This includes the
parameter to suppress SMF recording.
Operator Communication
Four functions are provided for communicating with the system operator and for placing
messages in the system log. These are:
WTL a function for writing single-line messages to the system log.
WTO a function for writing single-line and multi-line messages to the system operator's
console and to the system log.
WTOR a function for querying the system operator for information. This function prompts
the operator for information and returns the information entered by the operator
in a REXX variable.
DOM a function for removing previously sent messages from the system operator's
console.
WARNING: If your program writes large numbers of messages to the operator console,
you may impair the ability of system operators to manage the system. In addition,
depending on the size of the console buffers, you could cause a console buffer shortage
condition.

Specifying Routing Codes
You can control the console to which the WTO and WTOR functions send messages
using route codes. The actual consoles to which the messages will be sent depends
upon how the consoles have been defined. If, for example, you are sending a message
using a route code of 3 (tape pool), but there is no console that is "listening" for route
code 3 messages, the message will not appear anywhere (except the system log). The
following table gives the first 16 routing codes. These codes are the ones most commonly
used.
1 Master console action
2 Master console information
3 Tape pool
4 Direct access pool
5 Tape library
6 Disk library
7 Unit record pool
8 Teleprocessing control
9 System security
10 System error/maintenance
11 Programmer information
12 Emulators
13 Customer defined
14 Customer defined
15 Customer defined
16 Customer defined

Specifying Descriptor Codes
By specifying descriptor codes you can control how your messages appear (i.e., color,
intensity, scroll ability). The actual appearance of a message is dependent on definitions
supplied by your systems programmer. The following table gives the first 16 descriptor
codes. These codes are the ones most commonly used.
1 System failure
2 Immediate action required
3 Eventual action required
4 System status
5 Immediate command response
6 Job status
7 Application program
8 Out-of-line message
9 Operator request
10 Dynamic status display
11 Critical eventual action
12 reserved
13 reserved
14 reserved
15 reserved
16 reserved

The sections that follow describe the syntax and operation of the MVS supervisor
services-related functions.
DEQ
Syntax:
DEQ(qname,rname[,scope][,reqtype])
Arguments:
qname (also referred to as the "major name") is the 1 to 8 character name that
identifies the first level of qualification for the resource you want to
process. If you code fewer than 8 characters the name is blank padded
on the right out to a length of 8. This name needs to have been
previously used in the ENQ function. The qname can be any arbitrary
set of characters. The only requirement is that all users of a resource use
the same qname (and rname) to represent the same resource.
Note: Certain qnames are reserved for authorized programs only. You
should especially avoid using qnames that begin with 'SYS' since some
of these are reserved for the control program. SYSDSN, for example,
cannot be used because it is reserved by the access methods.
rname (also referred to as the "minor name") is the 1 to 255 character name that
identifies the second level of qualification for the resource you want to
process. Note that the rname (unlike the qname) is not blank padded.
This name needs to have been previously used in the ENQ function. The
rname can be any arbitrary set of characters. The only requirement is
that all users of a resource use the same rname (and qname) to
represent the same resource.
scope indicates scope of control for the resource. The valid values are:
'STEP' The resource is only used on one address space.
'SYSTEM' The resource is used on one system.
'SYSTEMS' The resource is used on several systems. Note that

'SYSTEMS' will only work if global resource serialization
(GRS) is active.
The default value is 'STEP'.
reqtype This argument is used to indicate the type of DEQ request. The valid
values are:

'HAVE' The request for releasing control of a resource is
conditional. If the resource is not held, a return code is
issued.
'NONE' The request for releasing control of a resource is

unconditional. If the resource is not held, an error
occurs. The default value is 'NONE'.
Module Name:
RXTDEQ
Environments:
The DEQ function is used to release control of resources that were previously acquired
via the ENQ function. All users of the resource must agree upon and use the same
qname/rname/scope combination.
The DEQ function returns the DEQ macro return code. If you CALL the DEQ function, the
returned value is contained in the RESULT special variable. In addition, the REXX
special variable, RC, is also set to contain the DEQ macro return code.
The following DEQ return code values are possible:
0 Successful execution. Control of the resource is released.
4 Successful execution. The task has requested the resource but has not been
give control of it yet. The task remains in a wait condition.
8 Execution failed. The current task does not hold the resource.
Other The abend code in REXX decimal (use the REXX D2X function to convert to
hexadecimal).
Note: Abend code X'130' (resource is not owned by the current task) is ignored
and the return code is set to zero.
Examples:
1. Call the DEQ function to release control of a data set:
call deq 'APPLDSN', 'USER1.EXEC', 'system'
2. Call the DEQ function to release control of an arbitrary resource:
call deq 'THEQNAME', 'THERNAME', 'system'

DOM
Syntax:
DOM(wtoid)
Arguments:
wtoid the system identification number of the operator console message. This
number is returned by the WTO function when the message is created.
Module Name:
RXTDOM
Environments:
The DOM function is used to remove messages from the operator console. Most Write-
To-Operator ( WTO ) messages will scroll off of the console display automatically.
However, high-intensity, non-scrollable messages will remain on the console until the
operator initiates an action to remove them (such as the "K S,1" command) or the
program uses the DOM service to remove them. If you attempt to DOM a message that is
no longer on the console, it is not an error.
Note: It is not necessary to DOM Write-To-Operator-with-Reply messages that have

been generated by the REXXTOOLS/MVS WTOR function. The WTOR function will
automatically DOM the message for you before returning control to your program.
The MVS DOM macro does not return a useful return code. Therefore, the DOM function
always returns a value of zero. If you CALL the DOM function the RESULT special
variable will contain zero, also. The RC special variable remains unchanged.
Example:
1. Call the DOM function to remove a message from the console:
call dom MsgWTID
In this example the message deleted is the one given by the number contained within the
REXX variable, MSGWTID. This variable was previously set by a call to the WTO
function.

ENQ
Syntax:
ENQ(qname,rname[,control][,scope][,reqtype])
Arguments:
qname (also referred to as the "major name") is the 1 to 8 character name that
identifies the first level of qualification for the resource you want to
process. If you code fewer than 8 characters the name is blank padded
on the right out to a length of 8. The qname can be any arbitrary set of
characters. The only requirement is that all users of a resource use the
same qname (and rname) to represent the same resource.
Note: Certain qnames are reserved for authorized programs only. You
should especially avoid using qnames that begin with 'SYS' since some
of these are reserved for the control program. SYSDSN, for example,
cannot be used because it is reserved by the access methods.
rname (also referred to as the "minor name") is the 1 to 255 character name that
identifies the second level of qualification for the resource you want to
process. Note that the rname (unlike the qname) is not blank padded.
The rname can be any arbitrary set of characters. The only requirement
is that all users of a resource use the same rname (and qname) to
represent the same resource.
control Specifies the type of control you are trying to acquire:
'E' You want exclusive control of the resource. While your program
holds exclusive control, other programs' attempts to gain either
exclusive or shared control will fail. This option is usually
reserved for occasions when you are planning to modify the
resource.
'S' You want shared control of the resource. While your program
holds shared control, other programs' attempts to gain shared
control will succeed, but attempts to gain exclusive control will
fail.
The default value is 'E'.
scope indicates scope of control for the resource. The valid values are:
'STEP' The resource is only used on one address space.
'SYSTEM' The resource is used on one system.
'SYSTEMS' The resource is used on several systems. Note that

'SYSTEMS' will only work if global resource serialization
(GRS) is active.
The default value is 'STEP'.

reqtype This argument is used to indicate the type of ENQ request. The valid
values are:
'CHNG' The enqueue is to be "upgraded" to exclusive from

shared control.
'HAVE' The request for acquiring control of a resource is

conditional. If the resource is already held by the current
task, a return code is issued.
'TEST' Only the availability of the resource is to be tested. If the

resource is held by another user, a return code is issued.
'USE' The request for acquiring control of a resource is

conditional. If the resource is not immediately available,
a return code is issued and the current task is not placed
in a wait state.
'NONE' The request for acquiring control of a resource is

unconditional. If the resource is already held by the
current task, an error occurs.
The default value is 'NONE'.
Module Name:
RXTENQ
Environments:
The ENQ function is used to acquire control of system resources. All users of the
resource must agree upon and use the same qname/rname/scope combination. When
you wish to relinquish control of a resource, use the DEQ function.
For most forms of ENQ, the caller will be placed in a wait state until the request can be
satisfied. However, if you specify a reqtype of 'USE', control will be returned to your
program immediately, regardless of the availability of the resource.
The ENQ function returns the ENQ macro return code. If you CALL the ENQ function, the
special variable, RC, is also set to contain the ENQ macro return code.

The following ENQ return code values are possible:
0
reqtype Meaning
'TEST' The resource is available.
'USE' The current task has control of the resource.
'HAVE' The current task has control of the resource.
'CHNG' The resource is now held exclusively.
4
reqtype Meaning
'TEST' The resource is not available.
'USE' The resource is not available.
'CHNG' The resource is not available for exclusive use.
8
reqtype Meaning
'TEST' The resource already held.
'USE' The resource already held.
'HAVE' The resource already held.
'CHNG' The resource was not previously held shared.
20
A previous request for the resource has been made and this task does not control the
resource.
24
reqtype Meaning
'USE' No more concurrent resource requests can be made. Request
rejected.
'HAVE' No more concurrent resource requests can be made. Request
rejected.
Other
The abend code in REXX decimal (use the REXX D2X function to convert to
hexadecimal).
Note: Abend code X'138' (the resource is already owned by the current task) is ignored
and the return code is set to zero.

Examples:
1. Call the ENQ function to gain exclusive control of a data set:
call enq 'OURDSN', 'USER1.EXEC', 'e', 'system'
2. Call the ENQ function to gain shared control of an arbitrary resource:
call enq 'THEQNAME', 'THERNAME', 's', 'system'
FREEMAIN
Syntax:
FREEMAIN([addr][,lv][,sp])
Arguments:
addr the address of the virtual storage to be freed. The format of this argument is the
REXX printable hexadecimal format (e.g. '1FC0'), not the printable decimal
format. Note that this format is the same as what is produced by the GETMAIN
function when allocating storage.
The addr argument must be supplied, except when freeing storage by subpool
(i.e., you want to free the whole subpool with one FREEMAIN).
lv the length of the storage to be freed. This number is given in the REXX printable
decimal format.
The lv argument must be supplied except when freeing storage by subpool.
sp the subpool of the storage to be freed. This number is given in the REXX
printable decimal format. The number must be between 0 and 127.
The sp argument is not required, unless:
• You are freeing by subpool only.
• You used a subpool when you GETMAINed the storage. In this case you
must specify the same subpool that you specified on the GETMAIN function.
Note: You may not use the subpool-only FREEMAIN for subpool zero.
Module Name:
RXTFREMN
Environments:

The FREEMAIN function is used to free storage that was previously acquired via the
GETMAIN function. There are two formats you may use with FREEMAIN: You may either
free storage by address and length (and optionally subpool); or you may free an entire
subpool with one FREEMAIN.
The FREEMAIN function returns the FREEMAIN macro return code. If you CALL the
FREEMAIN function, the returned value is contained in the RESULT special variable. In
addition, the REXX special variable, RC, is also set to contain the FREEMAIN macro
return code.
The following FREEMAIN return code values are possible:
0 The virtual storage was freed.
4 The virtual storage was not freed.
Examples:
1. Call the FREEMAIN function to free the 1000 bytes virtual storage that is pointed to
by the address in STGADDR:
call freemain stgaddr, 1000
2. Call the FREEMAIN function to free all of subpool 3:
call freemain , , 3

GETMAIN
Syntax:
GETMAIN(amount[,sp][,loc][,bndry][,fill])
Arguments:
amount the amount of virtual storage to try to allocate (in bytes). If the number is
not a multiple of 8, the amount of storage allocated, if successful, will be
the next higher multiple of 8.
sp the subpool of the storage to be allocated. This number is given in the

REXX printable decimal format. The number must be between 0 and
127.
If not specified, subpool zero is assumed.
loc determines from where the virtual storage is to be allocated. The

possible values are:
'ABOVE' the storage is to be allocated from above the 16M line.
'BELOW' the storage is to be allocated from below the 16M line.
The default value for loc is 'ABOVE'.
bndry specifies on what type of storage boundary the allocated storage is to

begin. The possible values are:
'DBLWD' the storage is to be allocated on a doubleword (8 byte)

boundary.
'PAGE' the storage is to be allocated on a page (4096 byte)

boundary.
The default value for bndry is 'DBLWD'.
fill specifies the character you want used to initialize the allocated area. A
sufficient number of copies of the fill character are copied to the allocated
area to fill it completely.
The default fill character is binary zero.
Note: The fill character will be used to initialize the number of bytes
specified in the amount argument. If the control program rounds up to the
next multiple of 8, the bytes between amount and the actual number of
bytes allocated will not get copies of the fill character.
Module Name:
RXTGETMN

Environments:
The GETMAIN function is used to allocate virtual storage. You may use the FREEMAIN
function to later free the storage you have allocated. To modify the storage, you use the
REXX/MVS STORAGE function.
Depending on the way the task your REXX program is running under was attached, and
the subpool you have specified, the storage may or may not be freed when the task
terminates. For a more detailed discussion of this topic, see "Virtual Storage
Management" in the IBM publication, MVS/ESA Assembler Programming Guide, GC28-
1644.
WARNING: If your program allocates large amounts of storage you may make it difficult
(if not impossible) for other programs to run in your address space. The best way to avoid
trouble is to use storage sparingly and free it when you have finished using it.
The GETMAIN function returns address of the storage allocated (if successful), or zero (if
not successful). If you CALL the GETMAIN function, the returned value is contained in
the RESULT special variable. In addition, the REXX special variable, RC, is also set to
contain the GETMAIN macro return code.
The following GETMAIN return code values are possible:
0 The virtual storage was allocated.
4 The virtual storage was not allocated because there was not enough of it.
Examples:
1. Call the GETMAIN function to allocate 1000 bytes of virtual storage and fill it with
blanks:
stgaddr = getmain(1000, , , ,' ')
2. Call the GETMAIN function to allocate 512 bytes from subpool 3:
call getmain 512, 3

stgaddr = result

POST
Syntax:
POST(ecbad[,compcode])
Arguments:
ecbad the address, in the REXX printable hexadecimal format (e.g., '1FC0') of
the Event Control Block (ECB) to post as completed.
compcode the completion code to place in the ECB completion code field. This
argument is specified as a REXX printable integer.
Module Name:
RXTPOST
Environments:
The POST function is used to signal the completion of events. Other tasks that may be
waiting on the Event Control Block (ECB) will become available for execution. Optionally,
you may supply an event completion code which is placed in the ECB and may be
examined by other programs.
The primary purpose the POST function, is to notify other programs, which may be
running in the same address space but under different Task Control Blocks (TCBs), of
the completion of a synchronizing event. For example, two independently executing
programs may occasionally need to pass data to each other. The POST function (along
with the WAIT 'ECB' function) can be used to coordinate the process of passing
information from one program to the other.
The MVS POST macro does not return a useful return code. Therefore, the POST
function always returns a value of zero. If you CALL the POST function the RESULT
special variable will contain zero, also. The RC special variable remains unchanged.
Example:
1. Call the POST function to indicate the completion of an event:
call post MyECB, 4
In this example a completion code of 4 is set. This completion code may be examined by
any program that was waiting on MYECB.

RACROUTE
Syntax:
RACROUTE('AUTH',entity[,class][,attr][,dstype][,volser]
[,oldvol][,appl][,owner][,acclvl][,racfind]
[,generic][,reqstor][,subsys][,msgsuppress])
Arguments:
'AUTH' indicates that authorization checking is to be performed. This argument

is not optional and must always be coded with this value.
entity the name of the resource that RACF is to perform authorization checking
for. If the class argument value is either 'TAPEVOL' or 'DASDVOL', the
value of entity must be a 6 character volume serial number (blank
padded on the right, if necessary). The lengths of other resource names
can be found in the system class descriptor tables.
Note: When specifying a data set name, make sure it is fully qualified
and do not include quotes in the string.
class a 1 to 8 character value naming the resource class which contains the
entity for which authorization checking is to be performed. If you specify
less than 8 characters the value is blank padded on the right.
The default value is 'DATASET'.
attr specifies the type of access authority you are trying to acquire:
'READ' you require read access only.
'UPDATE' you require both read and write access.
'CONTROL' For non-VSAM, this is the same as 'UPDATE'. For

VSAM this is the same as the level of authority for the
control password.
'ALTER' you require complete control over the resource.
The default value is 'READ'.
dstype gives the type of data set (if any) for this request. The valid values are:
'N' non-VSAM
'V' VSAM
'M' model profile
The default value is 'N'.

volser the 1 to 6 character volume serial number. For a VSAM data set this is
the serial number of the volume that controls the VSAM data set. For
non- VSAM data sets, it is the volume that actually holds the data set. If
you specify less than 6 characters the argument is padded on the right
with blanks.
This argument is required when the value for class is 'DATASET', except
when the value for dstype is 'M'. In all other cases, volser is not used.
Note: For SMS managed data sets, the volser argument is ignored, but
must still be coded, and a dummy value such as 'XXXXXX' can be used.
oldvol specifies, when class is 'TAPEVOL', a volume within the same tape
volume that contains the volume given in the entity argument. When
class is 'DATASET', oldvol gives the serial number of a volume in the
same multi-volume data set as volser. The argument is padded on the
right with blanks if you specify less than 6 characters.
appl a 1 to 8 character application name. It gives the name of the application

that wants the authorization checking.
Note: This string is not checked by RACF. It is handed to the local exit
routine.
owner a 1 to 8 byte field that gives the name of the profile owner. The owner is
permitted 'ALTER' access.
acclvl a 1 to 8 byte field that gives, for tape label processing, access level
information. RACF does nothing with this field. It is passed to installation
exits.
racfind specifies that the resource is or is not protected by a discrete (as

opposed to generic) profile. The possible values are:
'YES' the resource is protected by a discrete profile.
'NO' the resources is not protected by a discrete profile.
generic specifies that the resource name is either a generic profile name or not.
The possible values are:
'YES' the resource name is a generic profile even if generic characters

(asterisk or percent) are not present.
'ASIS' the resource name is a generic profile only if generic characters

(asterisk or percent) are present. This is the default.
reqstor specifies a 1 to 8 byte control point name used by RACF router table
processing. The default is blanks.
subsys the 1 to 8 character name of the subsystem requesting access. This

name, like reqstor is used to match with the RACF router table. The
default is blanks.

msgsuppress specifies one of the following:
'Y' suppress messages.
'N' do not suppress messages (the default).
Module Name:
RXTRROUT
Environments:
The RACROUTE function is used to check whether a user is authorized to use a security
package-protected resource. The information which you supply as arguments to this
routine, along with system-maintained information, is used to determine whether access
to a resource should, or should not be permitted. Note however, that the actual act of
allowing the requested action to take place (or not) is the responsibility of your program.
The RACROUTE function returns the RACROUTE macro return code. If you CALL the
RACROUTE function, the returned value is contained in the RESULT special variable. In
addition, the RC special variable is set to contain the return code. Possible values are:
0 authorization is granted.
4 the resource or class is unknown to your security package or the MVS router is
not active.
8 authorization is denied.
Other the abend code in decimal (use D2X to convert to hex). If an abend code is
returned, the REASON variable will be set to contain the abend reason code.
Two other special variables are created by RACROUTE. These are:
SAFPRRET which contains the RACF or installation exit return code.
SAFPRREA which contains the RACF or installation exit reason code.
Example:
1. Call the RACROUTE function to check 'ALTER' access to entity 'ACCOUNTS' in

class 'FINANCE':
call racroute 'auth','accounts','finance','alter'

if rc = 0 then
/* allow the access */
else
/* don't allow the access */

WAIT
Syntax:
WAIT('ECB',ecbad[,longwait])
WAIT('ECBLIST',ecblad[,eventno][,longwait])
WAIT('SEC',seconds)
Arguments:
ecbad the address, in the REXX printable hexadecimal format (e.g., '1FC0') of
the Event Control Block (ECB) to WAIT on until posted as completed.
The ECB must be 4 bytes wide, and must be initialized to binary zeros.
ecblad the address, in the REXX printable hexadecimal format (e.g., '1FC0') of
the Event Control Block (ECB) List to WAIT on until posted as
completed. Each 4 byte wide element in the list points to a standard 4
byte ECB. The last address in the list has the high order bit (bit zero)
turned on.
eventno the number of events to wait on (in ecblad) until completed. The
eventno argument must be a number that is equal to or less than the
number of events in the ECB list pointed to by ecblad.
longwait indicates whether the task will be in a "long wait" (such as waiting for
terminal input) or not. The possible values are 'YES' to indicate a long
wait will take place, and 'NO' to indicate that no long wait will take place.
seconds the number of seconds to wait before returning control to the REXX
program. This argument is specified as a REXX printable integer
between 0 and 86400 (the number of seconds in 24 hours).
Module Name:
RXTWAIT
Environments:
All REXX/MVS environments. However, in environments where waiting can conflict with
the address space's operation, you should avoid using the WAIT function. In particular,
the 'SEC' format uses the STIMER service which may interfere with the operation of
some tasks.
The WAIT function is used to stop the execution of the REXX program until one or more
events have completed. Optionally, the WAIT function, in its 'SEC' format, may be used
to wait for some number of seconds to pass before returning control to the program.
Depending on the type of WAIT you specify, the function may or may not return a useful
return code. If you specify an ECB WAIT, the return code is take from the completion

code field of the posted ECB (see the POST function). If you specify an ECBLIST WAIT,
the return code is the largest of the return codes in the list pointed to by ecblad. If you
specify a SEC WAIT, the WAIT function always returns a value of zero.
If you CALL the WAIT function, the RESULT special variable will contain the value of the
return code. In addition, the RC special variable is set to contain the return code value.
Examples:
1. Call the WAIT function to wait on the ECB pointed to by MYECB:
call wait 'ecb', myecb
2. Call the WAIT function to wait for 10 seconds:
call wait 'sec', 10

WTL (Write-To-Log)
Syntax:
WTL(msgtxt)
Arguments:
msgtxt a 1 to 126 character message that can contain any printable EBCDIC
characters.
Module Name:
RXTWTL
Environments:
The WTL function is used to write messages to the system log. The messages go directly
to the log and do not appear on the operator's console.
The MVS WTL macro does not return a useful return code. Therefore, the WTL function
always returns a value of zero. If you CALL the WTL function the RESULT special
variable will also contain zero. The RC special variable remains unchanged.
Example:
1. Call the WTL function to write a message to the system log:
call wtl 'Beginning of application test.'

WTO (Write-To-Operator)
Syntax:
WTO(msgtxt[,msgcount][,route][,desc])
Arguments:
msgtxt if msgcount is omitted or is zero, msgtxt is the 1 to 125 character text of

the message to be written to the system operator's console. If msgcount
is greater than zero, msgtxt is interpreted as the stem name of the
variables which contain the message lines. If the stem name is a true
REXX stem (i.e., it contains a dot), you must code the dot in msgtxt.
Notes:
1. The variables specified by msgtxt and msgcount will be written to

the console until msgcount is reached or a null or un-initialized
variable is encountered.
2. If the stem format is used (i.e., msgcount > 0) the value of each
message line will be padded or truncated to 70 bytes as necessary.
msgcount is a REXX printable integer between zero and ten. If msgcount is

greater than zero, it represents the number of stem variables, named by
msgtxt, that contain the messages to be written to the operator's
console.
route the routing codes for this message. Each routing code is a REXX
printable integer between one and twenty. If more than one routing code
is specified, they must be enclosed within parentheses and separated by
commas. See "Specifying Routing Codes" for more information.
desc the descriptor codes for this message. Each descriptor code is a REXX
printable integer between one and sixteen. If more than one descriptor
code is specified, they must be enclosed within parentheses and
separated by commas. See "Specifying Descriptor Codes" for more
information.
Module Name:
RXTWTO
Environments:

The WTO (Write-To-Operator) function is used to write messages to MVS system

consoles. There are two formats for this function. The first format, where msgcount is
omitted or is zero, causes the system to write a single line WTO to one or more system
consoles. In addition the message will be recorded in the system log.
The second format, where msgcount is greater than zero (but less than 10), causes the
system to use the MLWTO (Multi-Line WTO) format. The MLWTO format sends
messages to the console grouped together, and prevents other WTO messages from
appearing inside the group.
For a more detailed discussion of this topic, see "Communicating with the System
Operator" in the IBM publication, MVS/ESA Assembler Programming Guide, GC28-1644.
WARNING: If your program writes large numbers of WTO messages to the operator
console, you may impair the ability of system operators to manage the system. In
addition, depending on the size of the console buffers, you could cause a console buffer
shortage condition.
The WTO function returns the WTO ID number. The WTO ID number may be used with
the DOM (Delete-Operator-Message) function to remove WTOed messages. If you CALL
the WTO function, the returned value is contained in the RESULT special variable. In
addition, the REXX special variable, RC, is also set to contain the WTO macro return
code.
The following WTO return code values are possible:
0 operation successful.
48 routing code 11 was specified, but the resource required was not available. Other
route codes for the same message are processed normally.
Examples:
1. Call the WTO function to send a single line message to the tape pool:
call wto 'Starting IEHINIT job. Get scratch',, 3
2. Call the WTO function to write a 3 line high intensity (non-scrollable) message:
mline.1 = '**********************************'
mline.2 = '******* Application failed *******'
mline.3 = '**********************************'
call wto 'mline.', 3,, 2

WTOR (Write-To-Operator-with-Reply)
Syntax:
WTOR(msgtxt[,wait][,route])
Arguments:
msgtxt a 1 to 122 character message to send to the operator's console.
wait a REXX printable integer between 1 and 86400 that represents the
number of seconds to wait on the operator's reply before giving up.
The default wait is 60 seconds.
route the routing codes for this message. Each routing code is a REXX
printable integer between one and twenty. If more than one routing code
is specified, they must be enclosed within parentheses. See "Specifying
Routing Codes" for more information.
Module Name:
RXTWTOR
Environments:
All REXX/MVS environments. The WTOR function uses the STIMER service which may
interfere with the operation of some address spaces.
The WTOR (Write-To-Operator-with-Reply) function is used to write messages to MVS

system consoles which prompt the system operator for a reply. The messages appear as
high-intensity, non-scrollable messages. The operator may use the "D R,L" command to
list WTOR message that have been deleted (but not replied to).
The WTOR function will automatically remove (DOM) the message when either the wait
time expires, or the operator replies to the message. You do not need to use the
REXXTOOLS DOM function for this purpose.
For a more detailed discussion of this topic, see "Communicating with the System
Operator" in the IBM publication, MVS/ESA Assembler Programming Guide, GC28-1644.

The WTOR function returns the operator's reply text or a null length string if no reply is
present. If you CALL the WTOR function, the returned value is contained in the RESULT
special variable. In addition, the REXX special variable, RC, is also set to contain a return
code that indicates whether or not the operator replied.
The following WTOR return code values are possible:
0 the operator replied to the message.
4 the operator did not reply to the message. The wait time expired.
Examples:
1. Call the WTOR function to prompt the operator for a data set name:
if wtor('Enter Y or N') = 'Y' then

say 'Yes, indeed!'
2. Send a WTOR to the master and tape pool consoles. Return if no reply for 30
seconds:
call wtor 'Continue processing? Y or N:',30,'(1,3)'

TSO Services
The TSO Services functions of REXXTOOLS/MVS permit you to access TSO terminal
I/O functions normally reserved for assembler programs. Using these services you can
create both line mode and full-screen applications.
Writing and Reading Line Mode Messages

The TPUT and TGET functions of REXXTOOLS/MVS can be used to send and receive
line-mode messages to and from the terminal. Using the TPUT function, you can achieve
effects which are not possible with the REXX SAY statement. For example:
• You can write prompts for information that do not move the cursor to a new line at the
end of the prompt. This is in contrast to the REXX SAY instruction, which always
moves the cursor to a new line.
• You can make the terminal inhibit the display of characters typed in from the
keyboard. So, if you want to prompt the user for sensitive data, such as a password,
you can do so without echoing the data to the terminal display.
TGET, which performs a function similar to that of the REXX PULL instruction, facilitates
prompting the user when the data stack contains information which you do not want to
purge (PULL only reads from the terminal when the data stack is empty).
Using Full-Screen I/O

The TPUT and TGET functions may also be used to send and receive full-screen
messages. Full-screen messages are transmitted using the 'FULLSCR' (or 'NOEDIT')
argument, and are received using the 'ASIS' argument. A full screen-message (both
inbound and outbound) is in the form of a 3270 data stream (displayable data intermixed
with special hexadecimal control codes). 3270 data streams (especially extended data
streams) permit special effects that are not achievable using the ISPF Dialog Manager.
For example, using extended data streams you can display strings of characters where
each character has a different color, and there is no intervening attribute byte.
The SBA function is provided to make it easier to build 3270 data streams. Using SBA
(which stands for Set Buffer Address) you can build SBA "orders" which indicate to the
3270 control unit the location at which to place displayable characters.
If you are unfamiliar with the topic of 3270 data streams, refer to the IBM publication 3270
Information Display System, Data Stream Programmer's Reference, GA23-0059.
TSO Services 165

The sections that follow describe the syntax and operation of the TSO Services-related
functions.
SBA (Set Buffer Address)
Syntax:
SBA(row,col[,width])
Arguments:
row the row on the terminal where you want the output to be placed. The
number must be in the range 1-43.
col the column on the terminal where you want the output to be place. The
number must be in the range 1-132.
width the width of a line on the terminal. The acceptable values for this
argument are:
80 the width of most 3270 terminals.
132 the width of 3278 model 5 terminals.
The default value is 80.
Module Name:
RXTSBA
Environments:
TSO, TSO Batch.
The SBA (Set Buffer Address) function provides an easy way to construct an SBA order
for placing data on a screen in full-screen mode. The output of the SBA function, along
with 3270 commands and attribute bytes, can be sent to the terminal using the TPUT
function ('NOEDIT' or 'FULLSCR').
The SBA function returns a 3 byte field. The first byte is the SBA order ('11'X); the last
two bytes contain a 12 bit buffer address. If you CALL the SBA function, the returned
value is contained in the RESULT special variable. The RC special variable is
unchanged.

Example:
1. Call the SBA function to position data on the 4th row, 6th column:
NamePrompt = SBA(4,6) || HiLite || 'Enter Name:'
Note that HILITE in this example is assumed to be a REXX variable containing field
attribute information.
TGET
Syntax:
TGET([tptype][,tpwait])
Arguments:
tptype describes the type of TGET you wish to do. The possible values are:
'ASIS' minimal editing is performed on the received buffer. See "ASIS

Editing". This option is used for full-screen-mode messages.
'EDIT' additional editing beyond the 'ASIS' edits are performed. See
"EDIT Editing" below. This option is used for line mode
messages.
The default value for tptype is 'EDIT'.
tpwait determines whether the program will wait for terminal input. The possible
values are:
'WAIT' specifies that the program cannot continue until there is terminal
input data.
'NOWAIT'
specifies that the program will continue, even if terminal input
data is not available. If there is no terminal input data available,
however, the operation fails.
The default value for tpwait is 'WAIT'.
Module Name:
RXTTGET
Environments:
TSO, TSO Batch.
TSO Services 167

The TGET function, when operating in line mode ('EDIT') performs an operation similar to
the REXX PULL statement. Note, however, that unlike PULL, which is implemented with
the GETLINE service, TGET cannot have its source of input redirected. That is, TGET
will not read from the data stack.
In full-screen mode ('ASIS'), the TGET function permits you to communicate with the
terminal using 3270 data streams.
ASIS Editing:
If you specify 'ASIS' for tptype, the following edits are performed on the contents of the
retrieved data:
1. Transmission control data is removed from the buffer.
2. Invalid (non-EBCDIC) characters are removed from the data.
3. Characters and lines are deleted according to Terminal Status Block (TSB)
specifications.
4. NL, LF, and CR characters at the end of the data are removed.
5. The cursor is positioned at the beginning of the next line.
EDIT Editing:
In addition to the edits performed by 'ASIS' editing, specifying 'EDIT' for tptype will cause
all terminal control characters (3270 data stream commands and orders) to be removed
from the data, except for backspace, if it is not being used for character deletion.
The TGET function returns the data from the terminal input buffer. The length of the value
returned ranges from 0 (a null string) to 4000. If you CALL the TGET function, the
special variable, RC, is also set to contain the TGET macro return code.
The following TGET return code values are possible:
0 The operation was successful.
4 You specified 'NOWAIT' and a terminal input data was not available. The
operation does not continue.
8 An attention interrupt from the terminal has stopped TGET processing before the
message could be received.
12 The input buffer was not large enough to hold all of the input received. You must
issue more TGETs to get the rest of the message.
24 The operation was successful. The data was received in NOEDIT mode.

28 The input buffer was not large enough to hold all of the input received. You must
issue more TGETs to get the rest of the message. The data was received in
NOEDIT mode.
Examples:
1. Call the TGET function to get a line from the terminal (fully edited):
call tget
2. Call TGET to receive a 3270 data stream from the terminal:
call tget 'asis'
TSO Services 169

TPUT
Syntax:
TPUT(buffer[,tptype][,tpwait][,tphold][,tpbreak])
Arguments:
buffer a 1 to 32767 byte area containing the data you want to send to the
terminal.
tptype describes the type of TPUT you wish to do. The possible values are:
'ASIS' the contents of buffer are processed only slightly before

transmittal. See "ASIS Editing". This option is used for
line mode messages.
'EDIT' additional editing beyond the 'ASIS' edits are performed.

See "EDIT Editing". This option is used for line mode
messages.
'NOEDIT' no editing is performed. This option is used for full-

screen messages.
'CONTROL' specifies that the contents of buffer is entirely terminal

control characters. No data is displayed.
'FULLSCR' specifies that the message will be unedited, except that

if the first character is escape ('27'X), the 2 characters
past the escape are treated as the 3270 data stream
command code. The command code should always be
the code for a remote 3270. TPUT FULLSCR processing
will convert the command code to the appropriate one
for a local terminal, if necessary.
Also, transmission control characters are converted to

printable colons.
The default value for tptype is 'EDIT'.
tpwait determines whether the program will wait on TPUT buffers to be

available. The possible values are:
'WAIT' specifies that the program cannot continue until buffer

has been placed into a terminal output buffer.
'NOWAIT' specifies that the program will continue, even if no

buffers are available. If no buffers are available,
however, the operation fails.
The default value for tpwait is 'WAIT'.

tphold determines whether the program will wait for the message to be written
from the TPUT buffers to the terminal. The possible values are:
'HOLD' the program must wait until the message is actually

written from the terminal output buffer to the terminal.
'NOHOLD' the program does not wait for the message to be written
from the terminal output buffer to the terminal.
The default value for tphold is 'NOHOLD'.
tpbreak determines whether data from the user or from the program has
precedence. The possible values are:
'BREAKIN' output from the program takes precedence over input

from the user.
'NOBREAK' input from the user takes precedence over output from
the program.
The default value for tpbreak is 'NOBREAK'.
Module Name:
RXTPUT
Environments:
TSO, TSO Batch.
The TPUT function, when operating in line mode ('ASIS' or 'EDIT') performs an operation
similar to the REXX SAY statement. The major difference between the SAY statement
and the TPUT function is that SAY, which is implemented with the PUTLINE service, can
have its output redirected (to a REXX variable, for example), while the TPUT function can
not.
In full-screen mode ('NOEDIT' or 'FULLSCR'), the TPUT function permits your program to
communicate with the terminal using 3270 data streams.
ASIS Editing:
If you specify 'ASIS' for tptype, the following edits are performed on the contents of
buffer:
1. Unprintable characters, other than those which are acceptable terminal codes
(backspace, uppercase, bell ring, etc.) are translated to printable characters.
2. If you have included as the last character of buffer, the new line (NL) character,
TPUT processing will replace the NL with whatever is required to cause the cursor to
move to the next line after the message is written.
TSO Services 171

3. If buffer is longer than what can be displayed on a single line of the terminal, control
characters are added to display the contents of buffer on several lines.
4. If you send a bypass character ('24'X), a bypass carriage return, or a bypass new line
character, the next line of input from the user will be in a non-display mode. This is
particularly useful when prompting the user for sensitive information, such as
passwords.
5. The necessary transmission control characters are added to the message.
EDIT Editing:
In addition to the edits performed by 'ASIS' editing, specifying 'EDIT' for tptype cause the
following to occur:
1. Trailing blanks are removed from buffer.
2. Control characters are added to cause the cursor to be positioned at the beginning of
the next line.
3. All control characters (other than the backspace character) are replaced with
printable characters.
The TPUT function returns the TPUT macro return code. If you CALL the TPUT function,
the returned value is contained in the RESULT special variable. In addition, the REXX
special variable, RC, is also set to contain the TPUT macro return code.
The following TPUT return code values are possible:
4 You specified 'NOHOLD' and a terminal output buffer was not available. The
operation does not continue.
8 An attention interrupt from the terminal has stopped TPUT processing before the
message could be sent.
32 No storage was available for TPUT processing.

Examples:
1. Call the TPUT function to send a single line to the terminal without moving the cursor
to the next line:
call tput 'Enter Your Name:', 'asis'
2. Prompt the user for a password and do not echo the user's typing to the terminal:
call tput 'Enter Your Password:'||'24'X,'asis'
3. Call TPUT to send the 3270 data stream contained in DISPLAY1 to the terminal:
call tput display1, 'noedit'
TSO Services 173

General REXX Extensions
The programs of this section are designed to improve the general usability of the REXX
language and to increase the productivity of REXX programmers. These programs may
be categorized as follows:
Data conversion:
Functions are provided for converting to and from specialized numeric formats:
D2P/P2D Packed decimal conversions.
D2F/F2D Floating point conversions.
D2PIC/PIC2D COBOL-style numeric editing.
Stem handling:
Functions are provided for sorting (STEMSORT) and displaying (STEMDISP) the
contents of certain types of stem variables (those that contain numeric subscripts).
String handling:
A function is provided for breaking a string into its constituent tokens where the location
and frequency of delimiters is not predictable in advance (PARSETOK). Another function
is used to sort the blank delimited words in a string into either ascending or descending
collating sequence (WORDSORT).
Pattern Matching:
The MATCH function is used to compare strings to a pattern. The pattern may contain
wild card characters.
MVS/Quick-Ref access:
A function is provided for accessing the MVS/Quick-Ref database (QWIKREF). The
results of a successful search are placed in a user-specified stem array.
Note: Requires Chicago-Soft's MVS/Quick-Ref Release 3.0 or later.
REXX Environment Control:

A function, RXFUNC, is provided for maintaining entries in REXX function package
directories. Another function, RXSUBCOM, allows you to maintain entries in the host
command environment table.
Storage Manipulation:
The STORAGEX function gives the REXX programmer direct access to processor main
storage, using a relative addressing syntax similar to the one used by TSO TEST.
Global Variables:
A host command environment (ADDRESS REXXTOOL) and several host commands
(VPUT, VGET, VERASE) are provided to permit the sharing of data between REXX
programs.
General REXX Extensions 175

The sections that follow describe the syntax and operation of the General REXX
Extensions.
ADDRESS REXX
Syntax:
ADDRESS REXX [command]
Commands:
User-defined commands.
Module Name:
RXTADDRX
Environments:
ADDRESS REXX is a host command environment. As with other host command

environments, you switch to the REXX host command environment using the ADDRESS
instruction. To send a command to the host command environment you simply embed a
command string in your program.
Note: Since the permanent installation of the REXX host command environment is not
required, your site may not have included it in the REXX parameters modules. To
dynamically load the REXX host command environment, use the RXSUBCOM function.
The meaning of host command strings is defined by an EXEC named RXTADDRX.

RXTADDRX, when invoked by REXXTOOLS/MVS, is passed a single argument which is
the command string. The actual processing of a command string is user-defined. The
default RXTADDRX EXEC, echoes the command string to the terminal. You may modify
RXTADDRX to do whatever processing you desire.
The default RXTADDRX will place a return code of 1 in the RC special variable. User-
defined RXTADDRX routines must return a REXX integer (either positive or negative).
Example:
1. Pass a command string to the REXX host command environment:
address rexx
"this is a command string"

ADDRESS REXXTOOL
Syntax:
ADDRESS REXXTOOL [command]
Commands:
REXXTOOL commands. See “Service Description” below.
Module Name:
RXTARXT
Environments:
For global variable access: All REXX/MVS environments.
For dynamic allocation: All REXX/MVS environments. However, under NetView you
should use NetView's ALLOC and FREE commands.
ADDRESS REXXTOOL is a host command environment. As with other host command

environments, you switch to the REXXTOOL host command environment using the
ADDRESS instruction. To send a command to the host command environment you
simply embed a command string in your program.
Note: Since the permanent installation of the REXXTOOL host command environment is
not required, your site may not have included it in the REXX parameters modules. To
dynamically load the REXXTOOL host command environment, use the RXSUBCOM
function.
The host commands supported by ADDRESS REXXTOOL are:
ALLOCATE A host command for allocating data sets.
FREE A host command for freeing previously allocated data sets.
OPTIONS A host command for setting product options.
VERASE A host command for removing variables from a REXXTOOLS/MVS

variable pool.
VGET A host command for retrieving the values of variables in a

REXXTOOL/MVS variable pool into REXX simple symbols.
VPUT A host command for copying the values of REXX simple symbols
(variables) into a variable pool that is managed by REXXTOOLS/MVS.

The REXXTOOL host command environment, like other REXX host command
environments, returns a return code in the special variable RC. Certain RC values are
common to all REXXTOOL host commands. These are as follows:
-7 Syntax error. Refer to command documentation for the correct syntax.
-6 Invalid keyword. Refer to command documentation.
-5 Command verb not recognized. Verify that you have sent the command to the
proper host command environment.
-4 Zero length command string was passed.
-3 REXXTOOL host command environment not found. This RC is set by REXX (not
by REXXTOOLS/MVS) whenever REXX is unsuccessful in locating a host
command entry in the host command table of the current REXX environment.
Probable cause: you haven't installed the REXXTOOL host command
environment. See RXSUBCOM for information regarding dynamic installation of
REXX host command environments.
0 Successful execution.
Positive integer return codes are specific to the command that is being executed. Refer to
the command documentation for these RC values.
Note: Other information may also be returned by REXXTOOL commands. Refer to the
command documentation for descriptions of returned information.
Examples:
1. Dynamically install the REXXTOOL host command environment and execute a VPUT
command:
call rxsubcom 'add', 'rexxtool', 'rxtarxt'

namestr = "wanda rosalie brian richard earl"
address rexxtool "vput (namestr) shared"
2. Allocate a data set to file IN:
address rexxtool
"alloc fi(in) da(mydata) shr reuse"

D2F
Syntax:
D2F(rexxnum[,float-type][,synerrval])
Arguments:
rexxnum the REXX number to be converted. Can be any valid REXX number.
float-type indicates the desired size for the floating point result. The following
values may be specified:
'SHORT' Indicates a short (4 byte) floating point result is desired.

This is the default.
'LONG' Indicates a long (8 byte) floating point result is desired.
synerrval indicates the value to be returned if a syntax error is detected. This

argument can be used to handle normally occurring, but invalid, data.
For example, null strings.
Module Name:
RXTD2F
Environments:
The D2F function is used to convert printable REXX decimal numbers into the System
370 floating point format. The short floating point format is 4 bytes in length and is
compatible with a declaration of FLOAT DEC(6) in PL/I and COMPUTATIONAL-1 in
COBOL. The long floating point format is 8 bytes in length and is compatible with a
declaration of FLOAT DEC(16) in PL/I and COMPUTATIONAL-2 in COBOL.
The D2F function returns the System 370 floating point representation of rexxnum. If you
CALL the D2F function, the returned value is contained in the RESULT special variable.
The RC special variable is unchanged.
Example:
1. Call the D2F function to convert the REXX decimal number 3.14 to the short (4 byte)
floating point format.
sfloat = d2f(3.14)
/* sfloat = '41323d70'x */

D2P
Syntax:
D2P(printnum[,n][,,synerrval])
D2P(printnum[,precision,scale][,synerrval])
Arguments:
printnum the 1 to 31 significant digit number (in REXX printable decimal format) to
be converted. The number may have a sign and a decimal point. The
value for printnum can not be in "E" (exponential) format.
n a REXX printable integer, ranging from 1 to 16, indicating the number of

bytes for the result. If you do not supply n, the result will be a sufficient
number of bytes (up to a maximum of 16) to hold the digits in printnum.
precision a REXX printable integer, ranging from 1 to 31, indicating the number of
decimal digits to be allocated for the result. Precision is distinguished
from n by the presence of the scale argument.
scale a REXX printable integer ranging from 0 to the value for precision. This
number indicates the number of decimal digits to reserve for the
fractional part of the result.

Module Name:
RXTD2P
Environments:
The D2P function is used to convert printable REXX decimal numbers into the System
370 packed decimal format. If n is larger than what is required to hold printnum, the result
is right justified and left filled with packed decimal zeros. If n is smaller than what is
required to hold printnum, the result is right justified and truncated from the left (i.e., the
most significant digits are lost).
If you do not specify n, the D2P function will produce a result that will hold the digits of
printnum (up to a maximum of 16 bytes). The length of the result can be computed using
the following formula:
n = (no. of significant digits in printnum % 2) + 1
where n is the length, in bytes; and '%' is the integer divide operator (it throws any
remainder away).

In the alternative format you can specify the precision and scale of the result, and the
D2P function will adjust the digits within the packed number to achieve the proper result
(see example 2 below).
The D2P function returns the System 370 packed decimal representation of printnum. If
you CALL the D2P function, the returned value is contained in the RESULT special
variable. The RC special variable is unchanged.
Examples:
1. Call the D2P function to convert the printable decimal number 100.42 to 5 byte
packed decimal number
packdata = d2p(100.42,5)
/* packdata = '000010042c'x */
2. Call the D2P function to convert the printable decimal number 100.42 to a packed
decimal number with a precision of 9 and a scale of 4:
packdata = d2p(100.42,9,4)
/* packdata = '001004200c'x */
3. The following function can be used to return unsigned packed decimal data:
/* REXX - D2UP - Decimal to Unsigned Packed */

xdnum=c2x(d2p(arg(1),arg(2),arg(3)))
return x2c('0'substr(xdnum,1,length(xdnum)-1))
Note: For optimal performance you may want to incorporate this function in the
source of your application.

D2PIC
Syntax:
D2PIC(rexxnum,picstr[,national][,synerrval])
Arguments:
rexxnum the REXX decimal number to be converted. The number may have a
sign and a decimal point. Exponential format is not supported. The total
number of characters in rexxnum (including sign, decimal point and
blanks) cannot exceed 256.
picstr a string representing the formatting to be applied to rexxnum. This string

cannot exceed 256 bytes in length, and may not contain embedded
blanks. See Picture String Symbols" for more information on this
argument.
national a 3 byte string containing the characters to be used for the currency
symbol, the decimal point, and the hundreds separator, respectively. The
default national string is '$.,' (where the dollar sign is the currency
symbol, the period is the decimal point character, and the comma is the
hundreds separator). This string, if coded, must be exactly 3 bytes in
length and cannot contain blanks or any of the other valid picture
symbols.

Module Name:
RXTD2PIC
Environments:
The D2PIC function is used to convert REXX decimal numbers into a format suitable for
printing reports. The D2PIC function is especially helpful for formatting numbers that
represent currency amounts.
Formatting is performed -- under the control of the picstr argument -- in a manner similar
to that of COBOL numeric-edited fields. The national argument permits customization of
D2PIC's algorithm to account for local differences in currency formats.
Conceptually, the operation of D2PIC is as follows:
1. The REXX number is validated and its precision (total digits) and scale (fractional
digits) are determined.

2. The picture string is validated and its precision and scale are determined.
3. The REXX number is sized to fit the picture specification. If the REXX number's scale
is smaller than that of the picture specification, trailing zeros are appended to the
number. If the REXX number's scale is too large to fit the picture specification, some
or all of the fractional digits may be truncated. If the whole number digits of the REXX
number are fewer than those of the picture specification, leading zeros are appended
to the number. However, it is an error if the picture specification does not contain
enough whole number digit positions to accommodate the REXX number.
4. Finally, the picture specification is processed one symbol at a time, working from left
to right. As each picture symbol is recognized, a determination is made as to whether
a result byte is to be generated and, if so, what its value will be. The processing of
some picture symbols involves the selection of the next digit from the REXX number.
Note: Each picture symbol's operation depends, in some part, on whether or not the
symbol lies within the significant portion of the result. Significance is said to be
"started" whenever a significant digit is encountered in the REXX number, or when a
'9', 'V' or decimal point symbol is encountered in the picture string.
Picture String Symbols:
The picstr argument specifies the manner in which the REXX decimal number given in
rexxnum is to be formatted. The following symbols are permitted in picstr:
9 indicates a position that will always contain a numeric digit (0-9), regardless of
significance. This symbol is counted when determining the size of the result.
Z indicates a position that will contain a blank if it corresponds to a leading (non-

significant) zero in the REXX number. Otherwise it will contain a numeric digit.
This symbol is counted when determining the size of the result. For more
information on the use of the 'Z' symbol, refer to "Zero Suppression and
Replacement Editing".
$ (dollar sign) this symbol, or its replacement as given by the national argument, is
used to specify the placement of the currency mark. When only one such symbol
is coded, it will appear in the result in exactly the same position as it is appears in
picstr. The currency symbol may also be used in floating insertion editing, which
is discussed below. This symbol is counted when determining the size of the
result.
* (asterisk) indicates a position that will contain an asterisk (*) if it corresponds to a

leading (non-significant) zero in the REXX number. Otherwise it will contain a
numeric digit. This symbol is counted when determining the size of the result. For
more information on the use of the '*' symbol, refer to "Zero Suppression and
Replacement Editing".
B indicates a position where a blank is to be inserted in the result. This symbol is

counted when determining the size of the result.
0 (zero) indicates a position where a zero digit is to be inserted in the result. This
symbol is counted when determining the size of the result.

/ indicates a position where a slash is to be inserted in the result. This symbol is
counted when determining the size of the result.
, (comma) this symbol, or its replacement as given by the national argument, is

used to indicate a position where a hundreds separator is to be inserted in the
result. This symbol is counted when determining the size of the result.
. (period) this symbol, or its replacement as given by the national argument, is

used to indicate the position where the decimal point is to be inserted in the
result. Note that '.' is used to indicate both the location of the decimal point for
alignment purposes, and the actual representation of the decimal point. Either
this symbol or the "V", but not both, may appear in picstr. This symbol is counted
when determining the size of the result.
V indicates the location of the decimal point in picstr for alignment purposes only.
The "V" does not cause any formatting to take place (i.e., it does not produce a
character position in the result), and thus, is not counted when determining the
size of the result. Either this symbol or decimal point symbol (default: '.') but not
both, may appear in picstr.
+ (plus) indicates the position for the sign of the result. When rexxnum is zero or
positive, the result will contain a '+'. Otherwise the result will contain a '-'. This
symbol may be used in floating insertion editing and is counted when determining
the size of the result.
- (minus) indicates the position for the sign of the result. When rexxnum is zero or
positive, the result will contain a blank. Otherwise the result will contain a '-'. This
symbol may be used in floating insertion editing and is counted when determining
the size of the result.
CR indicates the position for the sign of the result. When rexxnum is zero or
positive, the result will contain 2 blanks. Otherwise the result will contain 'CR'.
The 2 positions occupied by this symbol are counted when determining the size
of the result.
DB indicates the position for the sign of the result. When rexxnum is zero or
positive, the result will contain 2 blanks. Otherwise the result will contain 'DB'.
The 2 positions occupied by this symbol are counted when determining the size
of the result.
Notes:
1. The alphabetic symbols may be coded in lower case. However, the resulting
numeric-edited number will contain only uppercase characters.
In the examples below, the lowercase letter "b" is used to indicate a blank position in
the result.
2. A repetition factor, contained in parentheses, may immediately follow a picture

symbol. For example, the following picture strings are equivalent:
99999.99
9(5).99
3. The "V" is the only symbol that does not produce a position in the result.

Simple Insertion Editing:
The characters 'B', '0', '/' and the hundreds separator (default: ',') are simple insertion
symbols. These characters are replaced, one-for-one, with the indicated character in the
result. For example:
picstr rexxnum Result
999B99/9 123 000b12/3

99,999 12345 12,345
99/99/99999 01021995 01/02/1995
Note: Simple insertion symbols may also be used in floating insertion editing. Their use
in this context is described in "Floating Insertion Editing."
Decimal Point Editing:
The decimal point symbol (default: '.') or the 'V' is used to specify the location of the
decimal point in picstr. The value in rexxnum is aligned on the decimal point location in
picstr. For example:
999.999 12.34 012.340

999.99 1.234 001.23
999V9999 12.345 0123450
Fixed Insertion Editing:
The currency symbol (default: '$') and the '+', '-', 'CR' and 'DB' symbols are used to
indicate the currency and sign of the number. When used in fixed insertion editing, only
one occurrence of any of these symbols is permitted. Fixed insertion characters will
appear in the result in exactly the same location as they are found in picstr. The currency
symbol will always appear as coded. The resulting representation of the other fixed
insertion characters depends upon the sign of rexxnum (refer to the symbol definitions
above for the exact translation that takes place). Below are some examples of fixed
insertion editing:
999.99+ 0 000.00+
$999.99CR 22.45 $022.45bb
$999.99CR -27 $027.00CR
-99.99 42 b42.00
-99.99 -79.4 -79.40

Floating Insertion Editing:
Floating insertion editing is used to specify both numeric digit positions and an insertion
character to place to the left of the resulting number. For example, in the picture string
++++.99
the '+' symbol -- a floating insertion character -- is used to reserve 4 whole number
positions, and indicates that a sign is to be inserted to the left of the most significant digit.
If the number 22 were to be formatted using this picture string, the result would be:
b+22.00
Notice that the sign is placed immediately to the left of the leftmost '2', and that the whole
number position to the left of the sign is blank.
The rules for floating insertion are as follows:
1. Only the currency symbol (default: '$') and the '+' and '-' symbols may be used as
floating insertion characters. The use of these characters in floating insertion is
distinguished from their use in fixed insertion by the repetition of the character to be
"floated". For example, in the string '$999.99' the currency symbol is used as a fixed
insertion character, but in '$$$$.99' it is used as a floating insertion character. The
collection of floating insertion characters in a picture string is referred to as the
floating string.
2. A picture string may contain only one floating string, and that string may be
composed of only one of the valid floating insertion characters. Thus, '+$$$9.99' is a
valid picture string, while '++$$9.99' and '$$99.$$' are not. Moreover, a symbol may
not be used for both floating and fixed insertion in the same picture string.
3. Floating insertion may not be used in any picture string that contains the '*' or the 'Z'
characters (see "Zero Suppression and Replacement Editing").
4. A floating insertion character's influence on its corresponding result byte is

determined as follows:
a. If significance has not started, the result byte will contain a blank.
b. If significance has not started, but the position lies immediately to the left of
the start of significance, the result byte will contain the floating insertion
character (remember that with '+' and '-' the actual result depends on the sign
of the REXX number).
c. If significance has started, the result byte will contain the corresponding
REXX number digit.
5. If simple insertion characters ('B' '0' '/' and the hundreds separator) or the decimal
point are contained within or immediately to the right of a floating string, they are
considered to be part of the floating string. The behavior of simple insertion
characters within a floating string is different from their behavior elsewhere:
a. If significance has not started, the result byte will contain a blank.

b. If significance has not started, but the position lies immediately to the left of
the start of significance, the result byte will contain the floating insertion
character.
c. If significance has started, the result byte will contain the value specified by
the simple insertion character.
6. A special rule for floating insertion is applied whenever:
a. all numeric positions in picstr are occupied by the floating insertion

character, and
b. the value of rexxnum is zero.
In this situation, the entire result will be filled with spaces. So for example, if the picture
string:
$$,$$$.$$
is applied to a zero REXX number, the result will be:
bbbbbbbbb (9 blanks)
The following examples demonstrate the operation of floating insertion editing:
$$$$9.99 123.45 b$123.45

+++++.++ 22.9 bb+22.90
+++++.++ 0.01 bbbb+.01
+++++.++ 0 bbbbbbbb
-----.99 23.72 bbb23.72
$$,$$9.99 432.97 bb$432.97
$$,$$9.99 2195.49 $2,195.49
Zero Suppression and Replacement Editing:
Zero suppression and replacement editing is a special case of floating insertion editing.
The two symbols used for this type of editing -- 'Z' and '*' -- reserve numeric digit
positions, and specify the value that will be used to replace leading (non-significant)
zeros in the result.
The rules governing the use of zero suppression and replacement editing are as follows:
1. Either 'Z' or '*', but not both may appear in a picture string. Unlike the floating
insertion symbols, the appearance of only one of these symbols indicates that zero
suppression and replacement editing is in effect.
2. Zero suppression and replacement editing is mutually exclusive with floating insertion
editing. However, the currency symbol, and the '+' and '-' symbols may be used as
fixed insertion characters (i.e., only one occurrence of any of the fixed insertion
characters may appear in a picture string that contains 'Z' or '*'. For example, under
this rule '$zzz.zz+' is permissible).

3. A 'Z' or '*' character's influence on its corresponding result byte is determined as
follows:
a. If significance has not started, the result byte will contain a blank, if the
character is a 'Z'; or an asterisk, if the character is a '*'.
b. If significance has started, the result byte will contain the corresponding
REXX number digit.
4. If simple insertion characters (B 0 / and the hundreds separator) or the decimal point
are contained within or immediately to the right of a string of 'Z' or '*' characters, they
are considered to be part of that string. The behavior of simple insertion characters
within a string of 'Z' or '*' characters is different from their behavior elsewhere:
a. If significance has not started, the result byte will contain a blank, if the string
contains 'Z' characters; or an asterisk, if the string contains '*' characters.
b. If significance has started, the result byte will contain the value specified by
the simple insertion character.
5. A special rule for zero suppression and replacement editing is applied whenever:
a. all numeric positions in picstr are occupied by 'Z' or '*' characters, and
b. the value of rexxnum is zero.
If the string is composed of 'Z' characters, the entire result will be filled with spaces. If the
string is composed of '*' characters, the entire result will be filled with asterisks, except
that if a decimal point is present, it will be placed in its specified position.
The following examples demonstrate the operation of zero suppression and replacement
editing:
ZZZZ9.99 123.45 bb123.45

ZZZZZ.ZZ 22.9 bbb22.90
*****.** 0.01 *****.01
ZZZZZ.ZZ 0 bbbbbbbb
*****.** 0 *****.**
*****.99 0 *****.00
ZZZZZ.99 0 bbbbb.00
Z,ZZZ.ZZ 2194.973 2,194.97
Z,ZZZ.ZZ 46.92 bbb46.92
$*,***.** 46.92 $***46.92
The D2PIC function returns the edited representation of rexxnum. If you CALL the
D2PIC function, the returned value is contained in the RESULT special variable. The RC
special variable is unchanged.

Examples:
1. Call the D2PIC function to convert the REXX decimal number 100.42 to a formatted
dollar value:
dollar = d2pic(100.42,'$$,$$9.99')
/* dollar = ' $100.42' */
2. Convert the packed decimal number 100.42 to a formatted dollar value:
dollar = d2pic(p2d('000010042c'x,2),'$$,$$9.99')
/* dollar = ' $100.42' */
3. Convert the number 1958.21 to a formatted value using the comma as the decimal
point, and the period as the hundreds separator (French currency notation):
amount = d2pic(1958.21,'ff.ff9,99','f,.')
/* amount = 'f1.958,21'*/

F2D
Syntax:
F2D(floatnum[,synerrval])
Arguments:
floatnum the 4 or 8 byte System 370 floating point number to be converted. For
information regarding the format of floating point numbers, refer to any
edition of Principles of Operation.

argument can be used to handle normally occurring invalid data. For
example, null strings.
Module Name:
RXTF2D
Environments:
The F2D function converts System 370 floating point numbers into the REXX exponential
number format. In every case, except one, the resulting REXX number is formatted using
the REXX exponential notation. The exception occurs whenever the exponent part of the
number (the part after the "E") is zero. In this case, blanks are supplied where the zero
exponent would be, thus making the result a REXX decimal number.
Note: The output of F2D can easily be formatted into REXX decimal notation using one
of the following methods:
1. Set NUMERIC DIGITS sufficiently high enough to express the result, and then add
zero to the number.
2. Use the FORMAT function.
The F2D function returns the REXX exponential number representation of floatnum. If
you CALL the F2D function, the returned value is contained in the RESULT special
variable. The RC special variable is unchanged.
Example:
1. Call the F2D function to convert the floating point number in F_PI:
f_pi = '41323d70'x
d_pi = f2d(f_pi)
/* d_pi = 3.1399993896484 */

MATCH
Syntax:
MATCH([pattern][,string][,caseopt])
Arguments:
pattern the pattern to use for the match. The pattern may contain combinations
of fixed and wild card characters (see “Service Description”), and can
range from zero to 256 bytes in length. It may not contain the binary
zeros ('00'X). A null pattern (zero length pattern) will match only with a
null string argument.
string the target string for the pattern match. The string can be zero to 256
bytes in length. It may contain any character except '00'X.
caseopt indicates whether case sensitive pattern matching is to be used. 'N' (the
default) indicates normal, case-insensitive matching is to be used. 'C'
indicates that case-sensitive matching is desired.
Module Name:
RXTMATCH
Environments:
The MATCH function is used to compare a pattern with a string. If the pattern matches
the target string, a '1' is returned. If not, a '0' is returned.
In the simplest case, the pattern contains only "fixed" characters. Fixed characters
consist of the letters of the alphabet, numbers, and all other characters except the wild
card characters and '00'X. Fixed characters in pattern are compared to characters in
corresponding positions in string. When normal, case-insensitive matching is specified
(or defaulted), the case of the characters in pattern and string is irrelevant, because the
MATCH function folds both arguments to uppercase prior to comparison. When case-
sensitive matching is specified, alphabetic characters must match exactly.
Wild card characters permit a single pattern to successfully match many strings. The
valid wild card characters and their meanings are as follows:
* (asterisk) indicates that zero or more characters, of any type, will match.
? (question mark) indicates that a single character, of any type, will match.
% (percent sign) Same as question mark.

In addition, the backslash (\) is defined as an escape character. When prefixed with the
escape character, a wild card character is interpreted as a fixed character. For example,
to search for a string that begins with an asterisk, you would code:
if match('\**',string) then say 'It matched!'
The first asterisk is treated as a fixed character (because of the backslash), and the
second is treated as a wild card character.
Note: To make the escape character fixed, use 2 consecutive backslashes, as in "\\abc".
The MATCH function returns a REXX boolean value. If string matches pattern, a '1' is
returned. If not, a '0' is returned. If you CALL the MATCH function, the returned value is
contained in the RESULT special variable. The RC special variable is unchanged.
Examples:
1. say match('abc*','abcdef') /* '1' */
2. say match('abc*','abc') /* '1' */
3. say match('abc???','abcdef') /* '1' */
4. say match('abc???','abcd') /* '0' */
5. say match('*xyz','xyz') /* '1' */
6. say match('\*abc','abc') /* '0' */
7. say match('\*abc','*abc') /* '1' */

OPTIONS Command
Syntax:
OPTIONS {MSGS | NOMSGS}
Keywords:
MSGS Indicates that product and system service messages are to be produced.
NOMSGS Indicates that messages are not to be produced.
Module Name:
RXTARXT
Environments:
OPTIONS is a host command that is executed under the REXXTOOL host command
environment. OPTIONS is used to set REXXTOOL/MVS processing options. At present,
only the printing of messages is controlled by this command.
Notes:
1. Since the permanent installation of the REXXTOOL host command environment is

not required, it may not be included in the REXX parameters modules. To
dynamically load the host command environment, use the RXSUBCOM function.
2. The ADDRESS REXXTOOL OPTIONS statement shares responsibility for message

processing with the ADDRESS SQL OPTIONS statement. Hence, use of the
MSGS/NOMSGS keywords in either host command environment affects message
processing for the entire product.
The OPTIONS command returns a return code in the REXX RC variable. Some return
codes are common to all REXXTOOL host commands. These are documented under the
topic "ADDRESS REXXTOOL".
If successful, the OPTIONS command produces a return code of zero.
Example:
1. Suppress the printing of REXXTOOLS messages:

address rexxtool "options nomsgs"

P2D (Packed-to-Decimal)
Syntax:
P2D(packnum[,scale][,synerrval])
Arguments:
packnum the 1 to 8 byte packed decimal number to be converted. The number

must be in packed format or an error will occur. See "Packed Format."
scale the number of digits to the right of the decimal point. If this argument is
omitted a scale of 0 is assumed. The value for scale cannot exceed the
number of decimal digits in packnum. The maximum value for scale is
15.

Module Name:
RXTP2D
Environments:
The P2D function is used to convert packed decimal data into the REXX printable format.
Since the System 370 packed decimal format does not include information regarding the
location of the decimal point (if any), you must, if a decimal point is required, supply this
information via the scale argument.
Note: P2D removes all leading zeros, except that a leading zero will be placed to the left
of the decimal point if you specify a scale that is equal to the number of decimal digits in
packnum.
Packed Format:
Each byte of packed decimal data contains 2 decimal digits, except for the right-most
byte which contains, in the left nibble, a decimal digit; and a sign designation in the right
nibble ('C'X is positive; 'D'X is negative).
Notes:
1. The precision (i.e., the maximum number of digits) of a number is inferred from the
number of bytes.
2. If the value of packnum is not a valid packed decimal number, the function call is in
error.

The P2D function returns the REXX printable decimal representation of packnum. If you
CALL the P2D function, the returned value is contained in the RESULT special variable.
The RC special variable is unchanged.
Example:
1. Call the P2D function to convert the packed decimal number in PNUM. Since the
value is in dollars, format the number with 2 decimal places:
pnum = '1020000c'x
salary = p2d(pnum,2)
/* salary = 10200.00 */

PARSETOK (Parse Tokens)
Syntax:
PARSETOK(string,stemname[,nbd][,blankopt][,dropopt])
Arguments:
string the string to be parsed into tokens. The string may be of any size and
may contain any number of tokens (up to the storage limits of the
machine).
stemname the name of the stem array that will contain the parsed tokens. The
combined lengths of the stemname argument and the largest subscript
(including any periods) cannot exceed the REXX maximum length for
symbols (250 characters). If stemname is to be a true REXX stem, code
a period (.) as the last character. If you do not specify the period, the
subscripts will abut the stem name without an intervening period. For
example, if you specify a stemname of "ABC.", PARSETOK will create
variables of the form "ABC.1", "ABC.2", "ABC.3", etc. If you specify a
stemname of "ABC" (no period), PARSETOK will create variables of the
form "ABC1", "ABC2", "ABC3", etc.
nbd a string containing the non-blank delimiters to be used in the parsing

process. Each byte in nbd is interpreted as a delimiter. Multi-byte
delimiters are not supported. The characters of the nbd argument are
treated as tokens, and are included in the stemname-specified array. If
you specify a character more than once in nbd, only the first occurrence
is used.
For the purpose of finding tokens, blanks are always treated as

delimiters. However, unless you specify BLANKS (see blankopt below),
blanks will not appear in the stemname-specified array. Furthermore,
specifying the blank character in the nbd string has no effect. Thus, if
you want to improve the readability of the nbd string, you can separate
the delimiter characters with blanks.
blankopt an option string (only the first character of which is recognized) used to
indicate whether blanks themselves are to be treated as tokens and
returned as elements of the stemname array. The valid values are:
Blanks specifies that blanks are to be treated as tokens.
Noblanks specifies that blanks are not to be treated as tokens.

dropopt an option string (only the first character of which is recognized) used to
indicate whether the stem given in stemname should be dropped (all
existing values are unassigned) prior to parsing the string. The valid
values are:
Drop specifies that stemname is to be dropped prior to

parsing. All stemname variables will be restored to their
original un-initialized state.

Nodrop specifies that stemname is not to be dropped prior to
parsing. Any stemname variables that are not
overwritten by the parsing process will be preserved.
Module Name:
RXTPTOK
Environments:
The PARSETOK function is used to parse strings into tokens where the location and
types of delimiters are difficult to predict. For example, consider the following string which
contains keywords to be parsed:
keywords = 'DSN(ABC.DATA(LIST)) NOPARENKEYWRD'
Parsing this string with WORD or PARSE would be difficult because:
a. not all of the interesting tokens are delimited by blanks, and
b. delimiter tokens that we would like to use in breaking the string down (like the
parentheses) are either nested or not present.
Using the PARSETOK function you can break the string down into its constituent tokens
and parse it by successively examining each token.
The PARSETOK function returns the number of stemname variables created. If you
CALL the PARSETOK function, the returned value is contained in the RESULT special
variable. If tokens are found, they will be returned in stemname-named variables. The
zeroth element of the stemname array contains the number of stemname variables
created. The RC special variable is unchanged.
Examples:
1. Call the PARSETOK function to parse STRING into words and place the resulting
tokens into variables that begin with 'TOK.':
string = 'The rain in Spain'

call parsetok string, 'tok.'
/* tok.0 = 4; tok.1 = 'The'; tok.2 = 'rain';
tok.3 = 'in'; tok.4 = 'Spain' */
Note that while blanks are used as delimiters in this example (as always), they are
not returned in the TOK. array since the default value for the blankopt argument is
'NOBLANKS'.

2. Call the PARSETOK function to parse KEYWORDS into tokens and place the
resulting tokens into variables that begin with 'TOK.'. In addition to blanks,
parentheses are to be used as delimiters. Blanks should be returned in the TOK.
array:
keywords = 'dsn(abc) noname'

call parsetok keywords, 'tok.', '()', 'blanks'
/* tok.0 = 6; tok.1 = 'dsn'; tok.2 = '(';
tok.3 = 'abc'; tok.4 = ')'; tok.5 = ' ';
tok.6 = 'noname' */

PIC2D (Picture-to-Decimal)
Syntax:
PIC2D(picnum[,national][,synerrval])
Arguments:
picnum the printable formatted number to be converted. The number must not
exceed 256 bytes in length, including blanks and editing characters.
national a 3 byte string containing the characters to be used for the currency
symbol, the decimal point, and the hundreds separator, respectively. The
default national string is '$.,' (where the dollar sign is the currency
symbol, the period is the decimal point character, and the comma is the
hundreds separator). This string, if coded, must be exactly 3 bytes in
length and cannot contain blanks or any of the other valid picture
symbols.

Module Name:
RXTPIC2D
Environments:
The PIC2D function is used to format "pretty printed" numeric data into the REXX decimal
number format. Blanks and all characters other than numeric digits (0-9), the sign
indictor, and the decimal point are stripped out in the result.
The recognized sign indicators are '+', '-', 'DB', and 'CR'. The 'DB' and 'CR' symbols
produce a negative result. If more than one sign indicator is present, the last one
scanned (working from left to right) will be used.
The decimal point character is identified using the second byte of the national argument
(the default is a period). If necessary, this character is converted to the REXX decimal
point character (always a period) before it is copied to the result. An error results if more
than one decimal point is present in the picnum argument.
If no decimal digits are found in the picnum argument, a single zero is returned.
The PIC2D function returns the REXX decimal representation of picnum. If you CALL the
PIC2D function, the returned value is contained in the RESULT special variable. The RC
special variable is unchanged.

Example:
1. Call the PIC2D function to convert the picture formatted number in PICNUM. In this
example, the roles of the comma and decimal point are reversed (French currency
notation).
picnum = 'f 1.792,42 CR'

amount = pic2d(picnum,'f,.')
/* amount = -1792.42 */
QWIKREF
Syntax:
QWIKREF(fastpath,stemname[,maxlines][,dropopt][,lrecl])
Arguments:
fastpath a character string describing the information you want to retrieve. The
character string must be in the MVS/Quick-Ref "fast-path" format (see
"Specifying the Fastpath String").
stemname the name of the stem array that will contain the lines of retrieved
information. The combined lengths of the stemname argument and the
largest subscript (including any periods) cannot exceed the REXX
maximum length for symbols (250 characters). If stemname is to be a
true REXX stem, code a period (.) as the last character. If you do not
specify the period, the subscripts will abut the stem name without an
intervening period. For example, if you specify a stemname of "ABC.",
QWIKREF will create variables of the form "ABC.1", "ABC.2", "ABC.3",
etc. If you specify a stemname of "ABC" (no period), QWIKREF will
create variables of the form "ABC1", "ABC2", "ABC3", etc.
maxlines a REXX printable integer, indicating the maximum number of lines of

information to retrieve. If the database item specified in fastpath
contains more lines than maxlines, the lines beyond maxlines are not
retrieved and RC will be set to 4.
dropopt an option string (only the first character of which is recognized) used to
indicate whether the stem given in stemname should be dropped (all
existing values are unassigned) prior to retrieving the requested
information. The valid values are:
Drop specifies that stemname is to be dropped prior to

retrieval. All stemname variables will be restored to their
original un- initialized state.
Nodrop specifies that stemname is not to be dropped prior to

retrieval. Any stemname variables that are not
overwritten by the retrieved lines will be preserved. This
is the default.

lrecl a REXX integer indicating the maximul logical record length of the item to
be retrieved. This argument is used with MVS/Quick-Ref Version 5 (and
later versions) to determine how large a buffer to allocate. It is ignored
for earlier versions of MVS/Quick-Ref. The actual LRECL of the data
returned may be longer or shorter than the value specified in this
argument. The default value is 78.
Module Name:
RXTQR
Environments:
The QWIKREF function is used to retrieve lines of information from the MVS/Quick-Ref
database.
Notes:
1. You must have licensed MVS/Quick-Ref (Release 3.0 and later) from Chicago-Soft,
Ltd. in order to use the QWIKREF function.
2. Before you invoke the QWIKREF function you must have pre-allocated the
MVS/Quick-Ref database to the QWREFDD ddname. If you are going to access a
user database, you may also need to allocate the QWREFDDU ddname.
3. The QWIKREF function uses the MVS/Quick-Ref module QWIKREF1. This module
must be accessible to the MVS LINK macro (i.e., it must be in one of: ISPLLIB, a
STEPLIB, the link list, or the link pack area). If you attempt to access a user
database, you must also make sure that the QWIKREFU module can be loaded via
the MVS LOAD macro (the same criteria as for QWIKREF1).
4. Successful searches return the "top-of-data" and "bottom-of-data" markers (lines) in

addition to the lines of text.
5. As of Release 5.0 of MVS/Quick-Ref, the largest database item contains 2400 lines
of information.
6. For more information refer to the MVS/Quick-Ref User's Guide. See especially the
topic of "Direct Program Invocation."
Specifying the Fast-Path String:
The fastpath argument must contain a valid MVS/Quick-Ref "fast-path" string. A fast-
path string has the following format:
topic-indicator'='topic-item
Where topic-indicator is a one character code indicating the type of database item you
want to retrieve, and topic-item is the specific database item. Leading, trailing, and
embedded blanks are not permitted. A few of the valid topic-indicators are:

M MVS messages and abend codes
J JCL syntax
L MVS utilities syntax
VC REXXTOOLS/MVS syntax (the topic indicator was '/' in early releases of

MVS/Quick-Ref)
A comprehensive discussion of topic indicators can be found in the MVS/Quick-Ref

User's Guide.
The QWIKREF function returns a return code that indicates the success of the operation.
If you CALL the QWIKREF function, the returned value is contained in the RESULT
special variable. If lines of information are found, they will be returned in stemname-
named variables. The zeroth element of the stemname array contains the number of
stemname variables created. The RC special variable is set to contain the QWIKREF
return code.
The following QWIKREF return code values are possible:
0 The search was successful. The lines of information are contained in the
stemname variables. stemname.0 contains the actual number of lines retrieved.
4 The search was at least partially successful. However, the database item you
requested contained more lines than could be contained in the internal buffer.
The actual number of lines returned is contained in stemname.0. To obtain a
larger buffer, specify a larger value for maxlines and/or lrecl.
8 No database item was found that matches the fastpath specification. No lines
are returned.
12 The local security exit or PREVENT or ALLOW statement caused the request to
be denied.
16 The parameter list for the QWIKREF1 program was incorrect. Repeat the query.
If the problem persists, contact Open Software Technologies or your local
distributor.
20 The MVS/Quick-Ref database could not be opened. Check to be sure that the
QWREFDD name has been allocated.
24 A severe internal error occurred. Repeat the query. If the problem persists,
contact Open Software Technologies or your local distributor.
28 The QWIKREFU user database access module could not be loaded. Make sure
that this module can be reached via the MVS LOAD macro instruction.
Another possibility is that your license to use MVS/Quick-Ref has expired. Verify the
status MVS/Quick-Ref with your systems programmer.

Example:
1. Retrieve and display the database entry for message IEF450I:
if qwikref('M=IEF450I','infoline.') = 0 then
do i = 1 to infoline.0
say infoline.i
end
RXFUNC
Syntax:
RXFUNC(function,name[,routine][,ddname])
Arguments:
function describes the action you want to be performed. The valid values are:
'ADD' specifies that a new function entry is to be created, and

the associated routine is to be loaded into storage (if it
has not already been pre-loaded). If the function entry
already exists, but the associated routine has not been
pre-loaded, the ADD function will pre-load the routine
without modifying the existing function entry.
'UPDATE' specifies that an existing function entry is to be modified

(only the routine name and/or the ddname can change),
and the associated routine name is to be loaded into
storage. If the old module was dynamically pre-loaded, it
is deleted from storage.
'QUERY' specifies that an entry with the name given in name is to

be searched for, and if found, its contents are to be
copied into special REXX variables (see "Returned
Information").
'DELETE' specifies that an entry is to be removed (blanked out),

and if its module has been pre-loaded, the module is to
be deleted from storage.
name the name that will be used in REXX programs to call the function. This
name does not need to be the same as the name of the module that
implements the function.
routine the name of the load module that implements the function. RXFUNC
(and REXX) must be able to load this module using the LOAD SVC. If
the module is in a private load library you may use the ddname
argument to specify the private load library.
For ADD requests only, the default value for routine is the value of the
name argument.

Very Important: You cannot specify a REXX source program for
routine. You may, however compile an exec using either REXX/370 or
the REXXTOOLS/MVS interpretive compiler and use the resulting load
module for routine.
ddname the ddname from which routine can be loaded. If not specified, routine
will be loaded from a library that is in the standard search sequence for
the LOAD SVC.
Note: The ddname argument is used both by RXFUNC and REXX.

Because of this, you must ensure that ddname is still allocated for
invocations after the initial installation using RXFUNC.
Module Name:
RXTFUNC
Environments:
The RXFUNC function is used to maintain entries in the current REXX environment's set
of function packages. Changes made using the RXFUNC function are in effect only for
the life of the environment, and do not affect function package modules residing on
DASD. For ADD and UPDATE functions, RXFUNC also pre-loads the routine associated
with the function package entry. The routine remains pre-loaded until it is explicitly
deleted with a DELETE, or until the task which issued the ADD or UPDATE terminates.
Function packages are searched by REXX whenever it encounters a CALL or function

call the target of which cannot be resolved to a built-in function or an internal label. When
a function package entry is found that matches the target of a CALL or function call, the
associated routine (load module or CSECT) is invoked.
Notes:
1. REXXTOOLS/MVS supplies an IRXFUSER function package directory (DSIRXUFP

for NetView) that contains 20 empty entries. If this directory module has not been
properly installed, or if it becomes full, you will not be able to add new functions.
2. Other REXX invocation methods (the EXEC and ISPEXEC commands, for example)
are not affected by function packages or by RXFUNC.
For more information regarding REXX function packages refer to TSO/E Version 2
MVS/REXX Reference, SC28-1883.

Search Order:
RXFUNC searches for function package entries using the same search sequence that
REXX uses when it attempts to find the target of a CALL or function call. The search
sequence is as follows:
1. The 3 groups of function package directories, USER, LOCAL, and SYSTEM, are
searched in that order.
2. The directories listed within each group are searched bottom to top. For example, if
the USER group has directories A, B, and C, directory C is searched first, B is
searched second, followed by A.
3. The entries of each directory are searched from top to bottom.
If there are multiple entries with the same key (i.e., the same REXX name) the first one
that is encountered in the search sequence is the one that is used.
The RXFUNC function returns a return code that indicates the success of the operation. If
you CALL the RXFUNC function, the returned value is contained in the RESULT special
variable. The RC special variable is set to contain the RXFUNC return code. In addition,
the REASON special variable contains a value indicating the success of the routine pre-
load operation.
The following RXFUNC RC values are possible:
4 For ADD functions only, an entry that matches the name argument already
exists. No modification takes place.
8 For UPDATE, DELETE, and QUERY functions, no entry was found that matches
the name argument.
12 For ADD functions only, an empty function package entry was not available, no
modification takes place.
16 For ADD, UPDATE, and DELETE functions, the entry to be modified was in
protected storage. No modification takes place.
20 An error occurred trying to load routine. Usually, a message indicating the

nature of the problem accompanies this return code.
The following RXFUNC REASON code values are possible:
0 The pre-load operation was successful.
8 The OPEN for ddname failed.
12 The LOAD for routine failed.

16 The CLOSE for ddname failed.
20 The module had unacceptable attributes. Modules must be link-edited

AMODE(31), and must be marked as reentrant.
24 Load service routine parameter list error. Call REXXTOOLS/MVS technical

support.
For successful QUERY function calls, the following REXX variables are set:
$RXTFPK_FPKNAME Contains the name of the function package containing name.
$RXTFPK_FUNCPOS Contains the number of the function within the function package.
$RXTFPK_FUNCNAME
Contains the REXX name of the function (identical to name).
$RXTFPK_ADDRESS Contains address of the routine that implements the function, or
zero. The value is given in printable hexadecimal characters.
$RXTFPK_SYSNAME Contains the name of the routine that implements the function, or
blanks.
$RXTFPK_SYSDD Contains the ddname from which the routine that implements the
function is to be loaded, or blanks.
Examples:
1. Create a function package entry named 'CAT' with a routine name of CATRTN:
call rxfunc 'add', 'cat', 'catrtn'
2. Remove the 'CAT' function package entry:
call rxfunc 'delete', 'cat'

RXSUBCOM
Syntax:
RXSUBCOM(function,name[,routine][,token][,ddname])
Arguments:
function describes the action you want to be performed. The valid values are:
'ADD' specifies that a new host command table entry is to be

created, and the associated routine is to be loaded into
storage (if it has not already been pre-loaded). If the host
command table entry already exists, but the associated
routine has not been pre-loaded, the ADD function will
pre-load the routine without modifying the existing host
command table entry.
'UPDATE' specifies that an existing host command table entry is to

be modified (only the routine name and/or the token can
change), and the associated routine name is to be
loaded into storage. If the old module was dynamically
pre-loaded, it is deleted from storage.
'QUERY' specifies that an entry with the name given in name is to

be searched for, and if found, its contents are to be
copied into special REXX variables (see "Returned
Information").
'DELETE' specifies that an entry is to be removed (actually

deleted), and if its module has been pre-loaded, the
module is to be deleted from storage.
name the name that will be used in REXX ADDRESS instructions to establish
the current host command environment. This name does not need to be
the same as the name of the module that implements the host command
environment.
routine the name of the load module that implements the host command
environment. RXSUBCOM (and REXX) must be able to load this module
using the LOAD SVC. If the module is in a private load library you may
use the ddname argument to specify the private load library.
For ADD requests only, the default value for routine is the value of the
name argument.

The names of the REXXTOOLS-supplied host command environment r
routines are:
name routine
REXXTOOL RXTARXT
SQL RXTASQL2
IDCAMS RXTIDCMS
token a sixteen byte field that can contain any value. If you supply fewer than
16 bytes, the value is left justified and blank padded.
For ADD requests only, the default value for token is 16 blanks.
ddname the ddname from which routine can be loaded. If not specified, routine
will be loaded from a library that is in the standard search sequence for
the LOAD SVC.
Note: The ddname argument is used solely by the RXSUBCOM routine.

There is no ddname field in the host command environment table entry.
Module Name:
RXTSUBCM
Component:
Basic Services, Dynamic and Static DB2/SQL Services
Environments:
The RXSUBCOM function is used to maintain entries in the current REXX environment's
host command environment table. Changes made using the RXSUBCOM function are in
effect only for the life of the environment, and do not affect the REXX parameters
modules residing on DASD. For ADD and UPDATE functions, RXSUBCOM also pre-
loads the routine associated with the host command environment. The routine remains
loaded until it is explicitly deleted with a DELETE, or until the task which issued the ADD
or UPDATE terminates.
The host command environment table is searched by REXX whenever it processes an

ADDRESS instruction (the ADDRESS instruction is used to establish the current host
command environment). Subsequently, when REXX encounters an expression that is not
a REXX instruction, it is interpreted to be a host command, and the routine associated
with the current host command environment is invoked with the expression as its primary
argument.

For more information regarding REXX host command environments refer to TSO/E
Version 2 MVS/REXX Reference, SC28-1883.
Search Order:
RXSUBCOM searches for host command environment entries using the same search
sequence that REXX uses when it attempts to find the entry associated with an
ADDRESS instruction: It starts the search with the last entry and works its way to the top.
If there are multiple entries with the same key (i.e., the same host command environment
name) the first one that is encountered in the search sequence is the one that is used.
The RXSUBCOM function returns a return code that indicates the success of the
operation. If you CALL the RXSUBCOM function, the returned value is contained in the
RESULT special variable. The RC special variable is set to contain the RXSUBCOM
return code. In addition, the REASON special variable contains a value indicating the
success of the routine pre-load operation.
The following RXSUBCOM RC values are possible:
4 For ADD functions only, an entry that matches the name argument already
exists. No modification takes place.
8 For UPDATE, DELETE, and QUERY functions, no entry was found that matches
the name argument.
20 An error occurred trying to load routine. Usually, a message indicating the

nature of the problem accompanies this return code.
The following RXSUBCOM REASON code values are possible:
0 The pre-load operation was successful.
4 The module was already pre-loaded.
8 The OPEN for ddname failed.
12 The LOAD for routine failed.
16 The CLOSE for ddname failed.
20 The module had unacceptable attributes. Modules must be link-edited

AMODE(31), and must be marked as reentrant.
24 Load service routine parameter list error. Call REXXTOOLS/MVS technical

support.
For successful QUERY function calls, the following REXX variables are set:
$RXTHCE_NAME Contains the REXX name of the host command environment

(identical to name).

$RXTHCE_ROUTINE Contains the name of the routine that implements the host
command environment.
$RXTHCE_TOKEN Contains the value of the token field associated with the host
command environment field.
Examples:
1. Create a host command environment entry named 'REXXTOOL' with a routine name
of RXTARXT:
call rxsubcom 'add','rexxtool','rxtarxt'
2. Create a host command environment entry named 'SQL' with a routine name of
RXTASQL2:
call rxsubcom 'add', 'sql', 'rxtasql2'
3. Display the token associated with the REXXTOOL host command environment:
call rxsubcom 'query', 'rexxtool'

say 'token='$rxthce_token

RXTTERM (Terminate REXXTOOLS)
Syntax:
RXTTERM()
Arguments:
None.
Module Name:
RXTTERM
Environments:
The RXTTERM function is used remove a REXXTOOLS/MVS environment from the

current MVS task. In addition to freeing REXXTOOLS/MVS data structures, the following
actions are performed:
• All files opened by the REXXTOOLS access method functions are closed.
• Any open connection to DB2 is terminated.
• Any global variables you may have defined are discarded.
In most cases, the RXTTERM function is not required (see note 1 below). Open Software
recommends that you use RXTTERM only if your execution environment requires you to
do so.
Notes:
1. A REXXTOOLS/MVS environment is established on the first call to a

REXXTOOLS/MVS function or host command. Certain data structures remain
allocated until task termination. In some environments the subpool used for
REXXTOOLS storage allocations may be shared with parent tasks. When the
subpool is shared, storage is not freed at task termination. Repeated use of
REXXTOOLS facilities in an environment of this type may cause storage to be
depleted. The RXTTERM function should be used in this situation to force all
REXXTOOLS-related storage to be freed.
2. Storage allocated by the GETMAIN function is not released by RXTTERM. You must
free this storage yourself (see FREEMAIN function).
3. At this time, the only environment that is known to require the use of RXTTERM is
Boole & Babbage's Auto Operator product.

The RXTTERM function returns a return code that indicates the success of the operation.
If you CALL the RXTTERM function, the returned value is contained in the RESULT
special variable. The RC special variable is unchanged.
The following RXTTERM return code values are possible:
0 The environment was found and successfully removed.
4 No REXXTOOLS/MVS environment was found. A message is issued.
16 The REXXTOOLS/MVS anchor block has been corrupted. Environment

termination is not possible. A message is issued.
Example:
1. Terminate the REXXTOOLS/MVS environment:
call rxtterm

STEMDISP (Stem Display)
Syntax:
STEMDISP('BROWSE',stemname[,startsub]
[,stemcount][,title][,panel])
Arguments:
'BROWSE' indicates that the browse service is to be used. This argument is not
optional and must always be coded with this value.
stemname the stem of the family of variables to display. The combined lengths of
the stemname argument and the largest subscript (plus the period, if
specified) cannot exceed the REXX maximum length for symbols (250
characters). If stemname is a true REXX stem, code a period (.) as the
last character. If you do not specify the period, the subscripts will be
assumed to abut the stem name without an intervening period. For
example, if you specify a stemname of "ABC.", STEMDISP will look for
stemname of "ABC" (no period), STEMDISP will look for variables of the
form "ABC1", "ABC2", "ABC3", etc.
startsub the element of the pseudo-array to begin the display on. The value for
startsub must be a REXX printable integer from 0 to 231-1. The default
value is element 1.
stemcount the number of elements to display. This argument must be a REXX

printable integer from 1 to 231-1. If you do not specify stemcount,
STEMDISP will display variables beginning with startsub, and
continuing until:
• an un-initialized variable is found (i.e., a variable which has its name

for a value).
• a variable with a null value is found.
• 100,000 variables have been retrieved.
title an arbitrary character string which identifies the data which is being
displayed. The maximum length of this string is 54 characters.
panel a 1 to 8 character name of the panel member to use for the display. The
default panel is ISRBROBF (supplied by IBM).
Note: If you want to use a customized panel, copy and customize the
IBM- supplied panel, ISRBROB. You may name the customized version
of this panel anything you want, as long as you specify this name for the
panel argument.
Module Name:
RXTSDISP

Environments:
ISPF.
The STEMDISP function is used to display the contents of REXX stem variables. The
STEMDISP function works in main memory only, and does not require the use of data
sets of any type. Since the ISPF/PDF Browse service is used to do the displaying, all
ISPF Browse commands are supported, including UP, DOWN, LEFT, RIGHT, FIND,
RFIND, ".labels", and recursive BROWSE.
The STEMDISP function returns a return code that indicates whether the display worked.
If you CALL the STEMDISP function, the returned value is contained in the RESULT
special variable. In addition, the REXX special variable, RC, is also set to contain the
STEMDISP return code.
The following STEMDISP return code values are possible:
0 The display was successful.
4 There were no stems matching the description given in stemname.
16 The display failed. This may have happened because:
• The stem variables exceed the ISPF Browse/Edit maximum width (32760).
• There is insufficient storage for your request.
Example:
1. Call the STEMDISP routine to display the output of the TSO "HELP ALLOC"
command. The variables to display begin with the characters "LINE.":
address tso
call outtrap 'line.'
"help alloc"
call stemdisp 'browse', 'line.',,, 'Help for ALLOC'

STEMSORT
Syntax:
STEMSORT(stemname[,startsub][,stemcount][,sortfields])
Arguments:
stemname the stem of the family of variables to sort. The combined lengths of the
stemname argument and the largest subscript (plus the period, if
specified) cannot exceed the REXX maximum length for symbols (250
characters). If stemname is a true REXX stem, code a period (.) as the
last character. If you do not specify the period, the subscripts will be
assumed to abut the stem name without an intervening period. For
example, if you specify a stemname of "ABC.", STEMSORT will look for
stemname of "ABC" (no period), STEMSORT will look for variables of
the form "ABC1", "ABC2", "ABC3", etc.
startsub the element of the pseudo-array to begin the sort on. The value for
startsub must be a REXX printable integer from 0 to 231-1. The default
value is element 1.
stemcount the number of elements to sort. This argument must be a REXX printable
integer from 2 to 231-1. If you do not specify stemcount, STEMSORT
will sort variables beginning with startsub, and continuing until:
• an un-initialized variable is found (i.e., a variable which has its name

for a value).
• a variable with a null value is found.
• 100,000 variables have been retrieved.
sortfields a character string which contains the sort specification. There are 3
possibilities:
'A' specifies that a "full length" sort with blank padding is to be

applied, with the elements sorted in character ascending order.
'D' specifies that a "full length" sort with blank padding is to be

applied, with the elements sorted in character descending order.
'(sortspec...)' See "Specifying Sort Fields."
Module Name:
RXTSSORT
Environments:

The STEMSORT function is used to sort the contents of REXX stem variables into a
desired order. STEMSORT assumes that the variables to be sorted have numeric
subscripts appended to the end. Other numbers are permitted in the stem names of the
variables to be sorted.
Note: The subscript numbers are assumed to contain only significant digits (i.e., leading
zeros are not permitted).
Specifying Sort Fields:
STEMSORT uses a sort fields specification format similar to the SORT FIELDS
statement for DFSORT (and "plug-compatible" competitors). When using the "sortspec"
format, the sortfields argument is a character string with the following components:
'(fldstart,fldlen,fldtype,flddir)'
Where:
fldstart is the starting position of the sort field. The value for this field must be a
positive REXX integer. This position must lie within the length of the
longest variable value or the sort will fail.
fldlen is the length of the sort field. The value for this field must be a positive
REXX integer. The sum of fldlen and fldstart must be less than or equal
to the length of the longest variable value or the sort will fail.
fldtype the type of data. Only character data can be sorted properly (negative
REXX numbers, binary, float and packed numbers will not sort correctly).
You must specify 'CH' for this sub-field. For this release of
REXXTOOLS, only character data sorts are supported.
flddir is the direction of the sort. The valid values are 'A' , for ascending, and
'D' , for descending.
Notes:
1. You may specify 1 to 5 sort fields.
2. As with all option fields, you must separate sub fields with commas, and there can be
no embedded blanks.
3. Although sortfields itself may be skipped, if you supply a value for this argument,
you are not permitted to skip any sub-fields. You must supply a value for every sub-
field.
4. You must place parentheses around the value for the sortspec format of sortfields or
it is an error.
5. If you do not specify sortfields, STEMSORT will sort using the 'A' format (full length
ascending sort).

The STEMSORT function returns a return code that indicates whether the sort was
successful. If you CALL the STEMSORT function, the returned value is contained in the
RESULT special variable. In addition, the REXX special variable, RC, is also set to
contain the STEMSORT return code.
The following STEMSORT return code values are possible:
0 The sort was successful.
4 There were no stems matching the description given in stemname.
16 The sort failed. This may have happened because you have specified sort fields
that do not fit all of the variables you want sorted.
Examples:
1. Call the STEMSORT routine to sort 100 variables in ascending order. The variables
to sort begin with the characters "LINE.":
call stemsort 'line.', , 100
We have not specified the sortfields argument, because we want to sort on the
entire width of each element, and we want the default order (ascending).
2. Call the STEMSORT routine to sort all of the variables with the stem "MYSTEM." .
Sort the data in columns 1 to 10 in ascending sequence; sort the data in columns 20
to 25 in descending sequence:
call stemsort 'mystem.', , ,'(1,10,CH,A,20,6,CH,D)'

STORAGEX
Syntax:
STORAGEX(address[,length][,data])
Arguments:
address a character string describing the starting address to be queried or

modified. See "Specifying the Address" for the exact syntax of this
argument.
length a REXX printable integer from 0 to 231-1 describing the number of bytes
of storage to retrieve. If zero is specified no storage locations are
retrieved or modified. If neither length nor data are specified (i.e.,
storage is to be retrieved only), a default length value of 1 is used. If data
is specified, its length is the controlling length and the value of length, if
specified, is ignored.
data the data to store at the storage location identified by address. The entire
length of data is stored, regardless of the value specified for length.
Module Name:
RXTSTORX
Environments:
All REXX/MVS environments
The STORAGEX function is used to retrieve and modify storage. If successful,

STORAGEX always first retrieves the storage located at address. In addition, if data is
specified, the storage locations starting at address are replaced with the bytes of data. If
data is not specified no storage locations are modified.
WARNING: Use the storage modification function of STORAGEX with great care.
Modification of certain REXX or TSO control blocks may make further execution in your
address space impossible. Please note though, that STORAGEX cannot modify
protected key storage or storage in another user's address space. It can only modify
storage that could be modified by any problem-state program written in PL/I, COBOL, or
assembler.
Specifying the Address:
The address argument of the STORAGEX function utilizes an indirect address notation.
The following definitions are essential to understanding the notation:
current location is the virtual address described by the address expression up to

the current operator. The address argument is assumed to start
at virtual address zero.

current operator is the most recently parsed operator. The address argument is
assumed to start with the plus operator.
The syntax of address is as follows:
addr-expr [{+|-}addr-expr...]
Where addr-expr is one of the following:
hex-off a one to 8 character printable hexadecimal offset, identifying the location

of the data. The offset is added to or subtracted from the current location
using the current operator.
hex-off% a one to 8 character printable hexadecimal offset, followed by a percent

sign. The offset is added to or subtracted from the current location using
the current operator. After this the current location is replaced with the
address pointed to by the current location using 24 bit addressing (the
low-order 3 bytes of the current location are used).
hex-off? a one to 8 character printable hexadecimal offset, followed by a question

mark. The offset is added to or subtracted from the current location using
the current operator. After this the current location is replaced with the
address pointed to by the current location using 31 bit addressing.
dec-offN a one to 10 digit printable integer offset, identifying the location of the
data. The number must immediately be followed with the letter "N". The
offset is added to or subtracted from the current location using the
current operator.
dec-offN% a one to 10 digit printable integer offset, followed by the letter "N" and a
percent sign. The offset is added to or subtracted from the current
location using the current operator. After this the current location is
replaced with the address pointed to by the current location using 24 bit
addressing (the low- order 3 bytes of the current location are used).
dec-offN? a one to 10 digit printable integer offset, followed by the letter "N" and a
question mark. The offset is added to or subtracted from the current
location using the current operator. After this the current location is
replaced with the address pointed to by the current location using 31 bit
addressing.
The STORAGEX function returns the storage located at address. If you CALL the
STORAGEX function, the returned value is contained in the RESULT special variable.
The $RXTSGAD special variable contains the printable hex address of the storage
location identified by address. The RC special variable is set to contain the STORAGEX
return code.
The following STORAGEX RC values are possible:
4 A zero length was specified. No storage was retrieved or modified.

8 The address argument was in error. Either the syntax of the argument was
incorrect, or one of the storage locations traversed was not accessible. Usually a
message describing the problem accompanies this return code.
12 Storage retrieval/modification protection exception. Usually a message

describing the problem accompanies this return code.
16 Storage modification not allowed. The current REXX environment's STORFL flag
indicates that STORAGE processing is not allowed.
Note: All storage modification attempts under NetView will result in this return
code
Examples:
1. Get the system SMF ID:
data = storagex('10?+c4?+10', 4)
say c2x(data) '>'data'<'
2. Get the REXX Parmblock eyecatcher:
data = storagex('224%+6c?+20n%+20?+30?+16n?', 8)
say c2x(data) '>'data'<'
3. Modify the storage located 4 bytes from the base address given in the variable
BASE:
olddata = storagex(base'+4', ,'New data string')

VERASE Command
Syntax:
VERASE (varname[,varname...]) [varpool]
Arguments:
varname The name of a variable to remove from the REXXTOOLS/MVS shared

variable pool. The REXX variable of the same name (whether or not it
exists) is unchanged. Only simple variables whose names are 1 to 8
characters in length are permitted. REXX stem variables are not
supported.
Note: You may use one or more blanks between syntactical elements in
the VERASE command. Also, you may use blanks instead of commas to
separate variable names.
varpool The name of the variable pool. At present, the only valid variable pool is
SHARED.
Module Name:
RXTARXT
Environments:
VERASE is a host command that is executed under the REXXTOOL host command
environment. VERASE is used to remove variables from the REXXTOOLS/MVS shared
variable pool. The shared variable pool is available to all REXX programs that execute
under the same MVS task. Shared variables are kept in main storage until they are
VERASEd or until the task terminates. For example, if you use the TSO EXEC command
to run your application, the "EXECed" program and any external REXX functions or
subroutines that it calls run under the same MVS task and share the same
REXXTOOLS/MVS variable pool.
Notes:

function.
2. REXXTOOLS/MVS shared variables are not in any way connected to ISPF shared
variables. If you are writing an ISPF-based application, you will want to use the ISPF
shared variable pool instead of the REXXTOOLS/MVS shared variable pool because
ISPF shared variables are shared between SELECTed programs (which run under
different MVS tasks).

The VERASE command returns a return code in the REXX RC variable. Some return
topic "ADDRESS REXXTOOL". In addition, the VERASE command produces the
following RC values:
0 Successful execution. All variable names were found in the REXXTOOLS/MVS

shared variable pool and removed.
8 At least one varname was not found in the REXXTOOLS/MVS shared variable
pool. Those variables that were found were removed.
Example:
1. Remove 2 variables from the REXXTOOLS/MVS shared variable pool:

address rexxtool "verase (name address)"
In this example note that the comma between NAME and ADDRESS is omitted, as is
the SHARED keyword.

VGET Command
Syntax:
VGET (varname [,varname...]) [varpool]
Arguments:
varname The name of a variable to copy from the REXXTOOLS/MVS shared

variable pool into the REXX variable pool. The REXXTOOLS/MVS
variable itself is unchanged. The name of the REXX variable created or
modified is identical to the name of the variable in the
REXXTOOLS/MVS variable pool. Only simple variables whose names
are 1 to 8 characters in length are permitted. REXX stem variables are
not supported.
Note: You may use one or more blanks between syntactical elements in
the VGET command. Also, you may use blanks instead of commas to
separate variable names.
SHARED.
Module Name:
RXTARXT
Environments:
VGET is a host command that is executed under the REXXTOOL host command
environment. VGET is used to copy the current values of REXXTOOLS/MVS shared
variables into the REXX variable pool. The shared variable pool is available to all REXX
programs that execute under the same MVS task. Shared variables are kept in main
storage until they are VERASEd or until the task terminates. For example, if you use the
TSO EXEC command to run your application, the "EXECed" program and any external
REXX functions or subroutines that it calls run under the same MVS task and share the
same REXXTOOLS/MVS variable pool.
Notes:

function.

The VGET command returns a return code in the REXX RC variable. Some return codes
are common to all REXXTOOL host commands. These are documented under the topic
"ADDRESS REXXTOOL". In addition, the VGET command produces the following RC
values:
0 Successful execution. All variable names were found in the REXXTOOLS/MVS

shared variable pool, and all REXX variables with the same names were created
or updated.
8 At least one varname was not found in the REXXTOOLS/MVS shared variable
pool. Variables that were not found did not cause updates to REXX variables with
the same names. Variables that were found had their values copied to REXX
variables with the same names.
Example:
1. In this example, the top-level program, TOP, calls an external subroutine, BOTTOM,
that VPUTs 3 variables into the shared variable pool. Upon return to TOP, a VGET is
issued to retrieve the contents of these variables:
/* REXX - TOP */
call bottom
address rexxtool "vget (v1,v2,v3) shared"
exit
/* REXX - BOTTOM */
v1 = 'one'
v2 = 'two'
v3 = 'three
address rexxtool
"vput (v1,v2,v3) shared"
exit

VPUT Command
Syntax:
VPUT (varname[,varname...]) [varpool]
Arguments:
varname The name (not the value) of a REXX simple variable to copy from the
REXX variable pool to the REXXTOOLS/MVS shared variable pool. The
REXX variable itself is unchanged. The name of the variable in the
REXXTOOLS/MVS shared variable pool is identical to the name of the
REXX variable. Only simple variables whose names are 1 to 8
characters in length are permitted. REXX stem variables are not
supported.
Notes:
1. Whenever an uninitialized REXX variable is encountered, the

variable's name is used for its value.
2. You may use one or more blanks between syntactical elements in

the VPUT command. Also, you may use blanks instead of commas
to separate variable names.
SHARED.
Module Name:
RXTARXT
Environments:
VPUT is a host command that is executed under the REXXTOOL host command
environment. VPUT is used to copy the current values of REXX variables into the
REXXTOOLS/MVS shared variable pool. The shared variable pool is available to all
REXX programs that execute under the same MVS task. Shared variables are kept in
main storage until they are VERASEd or until the task terminates. For example, if you
use the TSO EXEC command to run your application, the "EXECed" program and any
external REXX functions or subroutines that it calls run under the same MVS task and
share the same REXXTOOLS/MVS variable pool.
Notes:


function.
The VPUT command returns a return code in the REXX RC variable. Some return codes
"ADDRESS REXXTOOL". In the absence of any syntax errors, the VPUT command only
returns zero, which indicates successful execution.
Example:
1. VPUT 4 variables into the REXXTOOLS/MVS shared variable pool:

address rexxtool
"vput (name,address,phone,amount) shared"

WORDSORT
Syntax:
WORDSORT(string[,diropt])
Arguments:
string the character string that contains the blank-delimited words to be sorted.
The string may contain any number of words, and the words may be of
any size (up to the limits of the machine). The words may contain any
EBCDIC characters, including those in the unprintable range.
diropt the direction option. This string specifies direction of the sort. The valid
values are:
A the words are to be sorted in ascending collating sequence.

(e.g., a b c d...) This is the default.
D the words are to be sorted in descending collating sequence.

(e.g., ...d c b a)
Module Name:
RXTWSORT
Environments:
The WORDSORT function is used to sort the blank-delimited words of a string into either
ascending or descending collating sequence.
Notes:
1. The standard EBCDIC collating sequence is used for both ascending and
descending sorts.
2. WORDSORT performs only character sorts. It does not recognize special data types
such as packed decimal or floating point.
3. If string is null, the returned string will also be null. No sorting can be performed.
4. If string contains one or zero blank-delimited words, the returned string is an

identical copy of string. No sorting can be performed.
5. If string contains 2 or more blank-delimited words, the sort is performed. The

returned string will contain the sorted words with one blank between each word.

The WORDSORT function returns the sorted string. If you CALL the WORDSORT
function, the returned value is contained in the RESULT special variable. The RC special
variable is unchanged.
Example:
1. Call the WORDSORT function to sort the blank-delimited words, contained in

NAMES, into ascending sequence:
Names = 'zelnik yong xillery wilder'

Names = wordsort(Names)
/* Names = 'wilder xillary yong zelnik' */
Diropt is not coded in this example because the desired order, ascending, is the
default value for this argument.

Dynamic Allocation
Introduction
Dynamic allocation is the system facility that permits data sets to be allocated for use by
your program as they are required. When they are no longer needed, your program can
request that dynamic allocation routines "unallocate" or free the data sets. In contrast,
data sets allocated using JCL DD statements are allocated statically. That is, they are
allocated for your program's use possibly well before your program requires them; and
they may be held by your program long after the allocations are necessary, resulting in
loss of concurrent use.
Typically, when dynamic allocation is required by a REXX application, the TSO/E

commands that interface with the system dynamic allocation routines -- the ALLOCATE
and FREE commands -- are used. In both the on-line and batch environments, this
requires that your REXX programs be run under the TSO TMP (IKJEFT01).
Unfortunately, in the batch environment, where the preferred method for running REXX
programs is the IRXJCL interface, the performance penalty imposed by IKJEFT01 can be
considerable. Especially for short running batch programs, the use of IKJEFT01 can
significantly increase the CPU resources consumed by your application, due to the
overhead of TMP initialization and termination.
To alleviate this problem, REXXTOOLS/MVS provides TMP-independent

implementations of the ALLOCATE and FREE commands. These commands are
implemented under the REXXTOOL host command environment (address REXXTOOL).
Like their TSO counterparts, the REXXTOOLS/MVS ALLOCATE and FREE commands
are invoked by coding host command expressions in REXX programs. Unlike the TSO
commands, the REXXTOOLS/MVS commands are strictly for use under REXX programs
(TSO's ALLOCATE and FREE commands can be run outside of REXX programs).
Using the REXXTOOLS/MVS ALLOCATE command you can:
• Create new data sets. The data sets can be assigned attributes (e.g., DCB) directly
on the command, or indirectly by referring to model data sets or SMS classes.
• Associate a ddname with a data set. The ddname can be referenced by the
EXECIO command and by the REXXTOOLS/MVS VSAM functions.
• Concatenate several data sets. The data sets can be grouped together under one
ddname.
• Allocate SYSOUT data sets. The output can be routed to writers, printers, and other
systems.
Using the REXXTOOLS/MVS FREE command you can:
• Disassociate a data set with your program. The data set then becomes available
for other users in the system.
• Override the disposition and destination of data sets. The new values override
the values that were specified at data set allocation.
Dynamic Allocation 229

In addition, the REXXTOOLS/MVS ALLOCATE and FREE commands return extensive
diagnostic information to your REXX program, including the text of allocation messages.
You may use this information to drive conditional logic in your programs.
Differences from TSO/E Dynamic Allocation

The REXXTOOLS/MVS ALLOCATE command differs from the TSO/E ALLOCATE
command in the following respects:
• Generation data sets are supported by the REXXTOOLS ALLOCATE command.

They are not supported by TSO ALLOCATE.
• The ALTFILE and USING keywords are not supported by the REXXTOOLS
ALLOCATE command.
• The abbreviations for keywords are not always the same. In the service descriptions
that follow, the minimum acceptable abbreviation for a keyword is shown in bold and
underlined.
• The return codes are different and there are more of them. Refer to the section
"Returned Information" under the description for the ALLOCATE command.
• The handling of messages is different. Messages are returned in special variables,

and message printing is suppressed by the OPTIONS NOMSGS command.
• System prompting for additional information is not supported.
• The REUSE keyword always frees and reallocates the ddname.
• In some cases the TSO ALLOCATE command will assume keyword values. The
REXXTOOLS/MVS implementation assumes only the following:
o If you specify a data set status of NEW, a disposition of CATALOG will be

provided automatically.
o If you do not specify a status (OLD, NEW, SHR, MOD), but you do specify LIKE,
or any of the DCB or space-related keywords, a status of NEW is provided
automatically.
The REXXTOOLS/MVS FREE command differs from the TSO/E FREE command in the
following respects:
• The ATTRLIST and OUTDES keywords are not supported.
• The abbreviations for keywords are not always the same. In the service descriptions
that follow, the minimum acceptable abbreviation for a keyword is shown in bold and
underlined.
• The return codes are different and there are more of them. Refer to the section
"Returned Information" under the description for the FREE command.
• The handling of messages is different. Messages are returned in special variables,

and message printing is suppressed by the OPTIONS NOMSGS command.

• System prompting for additional information is not supported.
High-Level Language Support

REXXTOOLS includes a module called RXTDAIR that provides dynamic allocation
services to compiled languages such as PL/I, COBOL, and assembler.
Note: RXTDAIR is for use with compiled languages only. You cannot use RXTDAIR from
REXX.

The sections that follow describe the syntax and operation of the Dynamic Allocation
commands.
ALLOCATE Command
Syntax:
ALLOCATE keywords
Keywords:
ACCODE(code) specifies the accessibility code for an ANSI tape data set. code
may contain 1 to 8 characters (only the first character is
validated).
AVBLOCK(length) specifies the average byte length of the data sets records. This
keyword is used with the SPACE keyword to determine how
much space is to be set aside for the data set.
AVGREC(unit-type) used with the AVBLOCK and SPACE keywords to determine the
quantity and increment values. Unit-types are:
U byte units
K 1024 byte units
M 1,048,576 byte units
BFALN(alignment-type)
specifies buffer alignment. Alignment-types are:
F fullword boundary
D doubleword boundary
BFTEK(buffering-technique)
specifies the type of buffering. Buffering-techniques are:
S simple
E exchange
A automatic record area
R record
BLKSIZE(blocksize) specifies the data set's DCB (data control block) block size. The
number must be between 0 and 32,760. If you do not specify
BLKSIZE and SMS is active, a block size will be selected for
you. Also the model data set given on the LIKE keyword can
determine block size.

BLOCK(length) specifies the average block length of blocks written to the data
set. This value is used with the SPACE keyword to determine
how much space to allocate for the data set. length can range
from 1 to 65,535.
BUFL(length) specifies the length of buffers in the buffer pool. Length (in bytes)
ranges from 1 to 32,760.
BUFNO(number) specifies the number of DCB buffers. number ranges from 1 to

255.
BUFOFF(prefix-length)
specifies the block prefix length. If you code L, the prefix is 4
bytes that contain the length of the block. You can also code a
specific numeric prefix-length (range: 1 to 99).
BURST specifies that the burster-trimmer-stacker on a 3800 printer is to

be used. See NOBURST.
CATALOG specifies that the data set is to be cataloged after it is freed. See
KEEP, DELETE, and UNCATALOG.
CHARS(tablename-list)
specifies character arrangement table names for printing the
data set on a 3800 printer. You may specify 1 to 4 table names.
Each name can be 1 to 4 bytes long. This keyword is used with
the SYSOUT keyword.
COPIES(nnn[,group-value...])
specifies the number of copies of the data set to be printed
(nnn). You may also specify 1 to 8 group values that determine
how the copies are to be grouped. This keyword is used with the
SYSOUT keyword. You may not use the DATASET keyword with
COPIES.
CYLINDERS specifies that the unit of space is to be cylinders. This keyword is

used with the SPACE keyword to determine how much space to
set aside for the data set.
DATACLAS(class-name)
specifies the SMS data class name for the data set. This name
can be 1-8 characters long. Data class determines important
data set attributes such as RECFM, LRECL, RECORG, etc.
SMS must be active for this keyword to be honored.
DATASET({dsname | dsname-list | *})

specifies the data set or list of data sets to be allocated. If an
asterisk (*) is coded, the terminal is allocated. A fully qualified
data set name is enclosed in single quotes. If you omit the
quotes, the userid of the TSO user or batch job will be appended
to the front. Member names and generation numbers must be
enclosed in parentheses. DSNAME is an alias for this keyword.
DDNAME(name) specifies the 1 to 8 character name that your program will use to
access the data set(s). If you do not specify this keyword the

system generates a ddname for you (See S99DDN below). FILE
is an alias for this keyword.
DELETE specifies that the data set is to be deleted after it is freed. See
KEEP, CATALOG, and UNCATLOG keywords.
DEN(density-code) specifies the density of a magnetic tape. The valid values are:
0 7 track, 200 bytes per inch (bpi)
1 7 track, 556 bpi
2 7 or 9 track, 800 bpi
3 9 track, 1600 bpi
4 9 track, 6250 bpi
DEST(dest[.userid]) specifies the remote location to which a SYSOUT data set is to

be routed when the data set is freed. The optional userid
specifies the specific user at the remote location that is to
receive the data set.
DIAGNS(TRACE) specifies a module trace of Open/Close/EOV work area and your

DCB.
Note: This keyword must be coded exactly as shown.
DIR(integer) specifies the number of directory blocks to be allocated for a

partitioned data set. This number indirectly determines how
many members the data set can have. If DIR is coded, a
DSORG of PO (partitioned organization) is assumed.
DSNAME({dsname | dsname-list | *})

See DATASET keyword.
DSNTYPE({LIBRARY | PDS})
specifies the type of partitioned data set to be allocated.
LIBRARY indicates a partitioned data set extended (PDSE).
PDS indicates a standard partitioned data set.
DSORG(type) specifies the data set organization. The following values may be
coded:
DA direct access
DAU direct access unmovable
PO partitioned organization
POU partitioned organization unmovable
PS physical sequential
PSU physical sequential unmovable

If you do not specify DSORG, but you do specify DIR, a DSORG
of PO is assumed. If you specify neither DSORG nor DIR, a
DSORG of PS is assumed.
DUMMY specifies that a dummy data set is to be allocated.
EROPT({ACC | SKP | ABE})

specifies error handling for record read/write errors. ACC
indicates the block in error is to be accepted. SKP indicates the
block in error is to be skipped. ABE indicates that the task is to
be abended.
EXPDT({yyddd | yyyy/ddd})
specifies the data set expiration date. yy is the 2-digit year, yyyy
is the 4-digit year, and ddd is the day of the year. See the
RETPD keyword. Either this keyword or RETPD can be used,
but not both.
Note: Two special values indicate permanent retention. These

are 99365 and 1999/365.
FCB(image-id{,VERIFY | ,ALIGN})
specifies the 1 to 4 character forms control buffer image
identifier. VERIFY indicates that the operator is to visually verify
that image displayed is correct. ALIGN instructs the operator to
check forms alignment.
FILE(name) See DDNAME keyword.
FLASH(overlay-name[,copies])
specifies a forms overlay for a 3800 printer. Copies specifies the
number of copies on which the overlay is to be printed. This
keyword is used with the SYSOUT keyword.
FORMS(name) specifies the 1 to 4 character name of the form on which the

SYSOUT data set is to be printed.
HOLD specifies that the SYSOUT data set is to be
placed on the HOLD queue when the data set is freed. See
NOHOLD.
INPUT specifies input processing for BSAM and BDAM data sets.
KEEP specifies that the data set is to be kept by the system after it is
freed. See DELETE, CATALOG, and UNCATALOG keywords.
KEYLEN(length) specifies the length of the keys used to locate blocks of records
for DASD data sets. The length value ranges from 1 to 255.
KEYOFF(offset) specifies for VSAM KSDS data sets the offset of the key in each
record. This keyword is honored only if SMS is active.
LABEL(type) specifies the type of label processing. The valid types are:
NL no label.

SL standard label.
NSL non-standard label.
SUL standard and a user label.
BLP label processing to be bypassed.
LTM leading tape mark (DOS unlabeled tape).
AL American National Standard label.
AUL American National Standard label and American

National Standard user label.
LIKE(model-dsname) specifies the name of an existing data set, the attributes of which
are to be used in allocating the data set given in the DATA SET
keyword. You may override specific attributes (such as
BLKSIZE) simply by coding the attribute's keyword. This
keyword cannot be used with the REFDD keyword. However, the
DATA SET and NEW keywords must be specified.
Note: The operation of this keyword varies depending on

whether SMS is active or not. If SMS is not active, some
attributes may not be copied.
LIMCT(number) specifies the number of blocks (or tracks) to search. The number
ranges from 1 to 32,760.
LRECL({length | nnnnnK | X})

specifies the logical record length. The nnnnnK format specifies
the LRECL in 1024 bytes. The X format is used for variable
blocked data sets where the LRECL exceeds 32,756.
MAXVOL(count) specifies the maximum number of volumes for a data set. The
number can be 1 to 255.
MGMTCLAS(class-name)
specifies the SMS management class of the data set. The name
can be 1-8 characters long. Management class determines how
HSM handles data set migration and how often backups are
taken. SMS must be active for this keyword to be honored.
MOD specifies that data is to be added to the end of the data set, if it
exists.
MODIFY(module[,trc]) specifies a copy modification module name for a 3800 printer. trc
specifies which CHARS keyword character arrangement table to
use. The valid values for trc are 0-3. MODIFY is used with the
SYSOUT and FLASH keywords.
MSGLEVEL({INFO | WARN | SEVERE})

specifies the minimum desired severity level of allocation
messages to be returned to your program.

NCP(number) specifies the number of READ or WRITE macros that can be
issued before a CHECK macro is executed. number ranges
from 1 to 255 (or from 1-99 for MVS SP 4.2.2 and earlier).
NEW specifies that the data set does not exist, but is to be created. A
disposition of CATALOG is assumed. However, you may need to
specify additional keywords (such as DCB- related keywords or
SMS class keywords) to define the attributes of the data set.
NOBURST specifies that continuous forms are to be used on a 3800 printer.

See BURST.
NOHOLD specifies that the output processing for the data set is to be
determined by the SYSOUT class. See HOLD.
OLD specifies that the data set already exists and is to be allocated
for exclusive use.
OPTCD(option-list) specifies optional system services. The valid options are:
A device addresses are to be presented in READ and

WRITE macros.
B end-of-file recognition is to be ignored for tapes.
C chained scheduling is to be used.
E extended search for block or available space.
F READ or WRITE feedback should return device

addresses in the form used for the control program.
H check for and bypass.
J the character after carriage control is the table reference

character for the line.
Q requests ASCII-to-EBCDIC or EBCDIC- to-ASCII

translation for a tape.
R relative block addressing is to be used.
T the user totaling facility is to be used.
W a validity check is to be performed for data written to

DASD.
Z shortened error recovery on magnetic tapes is

requested.
OUTDES(descriptor-list)
specifies the list of output descriptors. Output descriptors are
created by OUTPUT JCL statements and the TSO/E OUTDES
command. Each descriptor name can be 1 to 8 characters long.
OUTPUT specifies output processing for a BSAM data set.

PARALLEL indicates that a device is to be mounted for each volume given
on the VOLUME keyword.
POSITION(seqno) specifies the position of the data set on a tape volume. The
number may be 1 to 9999.
PRIVATE specifies that the private volume use attribute is to be assigned.

Refer to the PRIVATE keyword in the JCL Reference for more
information.
PROTECT specifies that the data set is to be RACF protected. This keyword
is used with the DATA SET, NEW, MOD, KEEP, CATALOG, and
UNCATALOG keywords.
RECFM(format-list) specifies the format for the data set's records. The following one
byte codes may be used in combination:
A ASCII printer control characters
B blocked records
D variable length ASCII records
F fixed length records
M machine code control characters
S standard blocks (with F) or spanned records (with V)
T overflow tracks may be used
U undefined record lengths
V variable length records
This keyword cannot be used with the RECORG keyword.
RECORG(vsam-org) specifies the VSAM organization. The valid values are:
ES entry-sequenced data set
KS key-sequenced data set
LS linear space data set
RS relative record data set
This keyword is honored only if SMS is active. This keyword can

not be used with the RECFM keyword.
REFDD(ddname) specifies a previously allocated data set, the attributes of which

are to be used in allocating the data set given in the DATA SET
keyword (a status of NEW must also be coded). This keyword

cannot be used with the LIKE keyword. REFDD is honored only
if SMS is active.
RELEASE specifies that unused space is to be release to the system when

the data set is closed. This keyword is used with the BLOCK and
SPACE keywords.
RETPD(days) specifies the retention period for the data set in days. Days may
range from 1 to 9999. Either this keyword or the EXPDT keyword
may be used, but not both.
REUSE specifies that the ddname is to be freed and reallocated.
ROUND specifies that the allocated space is to be rounded up to an even

cylinder. This keyword is used with the BLOCK keyword.
SECMODEL(profile[,GENERIC])
specifies the name of a RACF data set profile to be copied to the
discrete profile for the data set given in the DATA SET keyword.
Code GENERIC to indicate that the profile is a generic data set
profile. This keyword is honored only if SMS is active.
SEGMENT(page-count)
specifies how many pages can be written to a SYSOUT data set
before it is spun off. Page-count can range from 1 to 99999.
SHR specifies that the data set already exists, and that other non-
exclusive users can also access the data set.
SPACE(quantity,increment)
along with the BLOCK, AVBLOCK, TRACKS, and CYLINDERS
keywords determines how much space to allocate for a data set.
Quantity indicates the number of units (blocks, tracks, etc.) to be
initially allocated. Increment indicates the number of units to be
added to the allocation, each time the previously allocated space
is filled.
SPIN({UNALLOC | NO})
specifies when a SYSOUT data set is available for printing.
UNALLOC indicates the data set can be printed after the file is
freed. NO indicates that the data set can be printed at the end of
the current step.
STORCLAS(class) specifies the SMS storage class name. The name can be 1-8
characters long. The storage class determines where the data
set is to reside (i.e., UNIT and VOLUME). SMS must be active
for this keyword to be honored.
SYSOUT[(class)] specifies that the data set is a system output data set. You may
also specify the one character class identifier. Output will be sent
to the job entry subsystem. You can control how this data set will
be processed by specifying additional SYSOUT-related
keywords such as HOLD, SPIN, DEST, FORMS, etc.

TRACKS specifies that the unit of space is to be tracks. This keyword is
used with the SPACE keyword to determine how much space to
set aside for the data set.
TRTCH(code) specifies the 7 track tape recording technique:
C data conversion (no translation) with odd parity
E no conversion and even parity
ET same as E plus BCD-to-EBCDIC translation on reads

and EBCDIC-to-BCD on writes
T no conversion and odd parity
COMP compression
NOCOMP no compression
UCOUNT(count) specifies the maximum number of devices that can be allocated

for this request. 59 is the largest value that can be coded.
UCS(name) specifies the universal character set name to be used to print a

SYSOUT data set. The name can be 1 to 4 bytes long.
UNCATALOG specifies that the data set is to be removed from the catalog after
it is freed. The system will, however, still keep the data set. See
KEEP, DELETE, and CATALOG keywords.
UNIT(unit) specifies the unit type to use for the data set. Unit can be a
group name, a generic device type (such as TAPE), or a device
address.
VOLUME(serial-list) specifies the volume serial numbers that identify where the data
set exists or where it is to be created.
Note: The system allocation routines do not always honor the

volume specification, depending on whether other software, such
as SMS, intervenes.
VSEQ(seqno) specifies the volume in a multi-volume data set with which

processing is to begin (for cataloged data sets only). Seqno can
range from 1 to 255.
WRITER(prog-name) specifies an installation written program to be used in writing a

SYSOUT data set.
Module Name:
RXTARXT, RXTDYNA
Environments:
All REXX/MVS environments. However, under NetView you should use the NetView
ALLOCATE command.

ALLOCATE is a host command that is executed under the REXXTOOL host command
environment. This command is used to:
• Allocate a new data set.
• Allocate one or more existing data sets and associate them with a ddname.
• Allocate the terminal as a data set.
• Allocate a SYSOUT data set.
• Allocate a dummy data set
Notes:
function.
2. Keywords must be separated by one or more blanks (do not use commas!).
3. Some ALLOCATE keywords accept lists of values (this is indicated in each keyword's
description). When a list is coded, the values must be separated by blanks, commas,
or both.
The ALLOCATE command returns a return code in the REXX RC variable. Some return
topic "ADDRESS REXXTOOL". Positive RC values are returned from the dynamic
allocation routines. These are:
0 Execution successful.
4 The error was due to the unavailability of a resource, a problem with the current
environment, or a routine failure. The S99INFO variable will contain additional
information.
8 An installation routine denied the request.
12 Invalid parameter list error. This error can occur when you specify keywords that
are mutually exclusive or when a required keyword is missing.
Other REXX variables are created that return information from the dynamic allocation
routines. These are:
S99ERROR An error reason code in printable hexadecimal format. The values this
variable can take, and their meanings are documented in MVS/ESA
Authorized Assembler Programming Guide, GC28-1645.

S99INFO An error information code in printable hexadecimal format. The values
this variable can take, and their meanings are documented in MVS/ESA
S99ERSN An SMS reason code in printable hexadecimal format. The values this
S99DDN The ddname used for the allocation. If you coded a ddname, it will
appear here. If you did not code a ddname, the system generated
ddname will be placed in this variable.
S99DSN The data set name used for the allocation. If you coded more than one
data set name, only the first will appear in this variable. If you did not
code a data set name, the system generated data set name will be
placed in this variable.
S99MSG. An array that contains dynamic allocation messages. S99MSG.0

contains the number of messages returned. S99MSG.1 contains the first
message and S99MSG.n contains the nth message. Note that messages
are always returned, even if OPTIONS NOMSGS is in effect. The
severity level of the messages returned is controlled by the MSGLEVEL
keyword.
Examples:
1. Add the REXXTOOL host command environment and allocate an existing data set to
a ddname of INDATA:

address rexxtool
"alloc fi(indata) da(olddata) shr reus"
2. Allocate a new data set that has 80 byte fixed block records:
address rexxtool
"alloc da(newdata) new sp(1 1) tracks lrecl(80)",
"recfm(f,b) blksize(800) unit(sysda)"
3. Allocate a ddname of OUTFILE to a SYSOUT class of X:
address rexxtool
"alloc dd(outfile) sysout(x)"
4. Allocate a dummy data set:
address rexxtool
"alloc fi(sysprint) dummy reuse"
5. Allocate a new partitioned data set using a model data set:
address rexxtool
"alloc dsn('user1.newpds.data')",
"like('user2.oldpds.data')"

6. Allocate a member of a PDS:
address rexxtool
"alloc fi(sysprint)",
"da(mypds.data(member1)) reuse"
FREE Command
Syntax:
FREE keyword [keyword...]
Keywords:
ALL specifies that all data set and ddname allocations are to be freed.
Reserved ddnames (such as STEPLIB) and data sets that are open will
not be freed.
CATALOG specifies that the data set is to be cataloged after it is freed. See KEEP,
DELETE, and UNCATALOG.
DATASET(dsname-list)
specifies the data set or list of data sets to be freed. A fully qualified data
set name is enclosed in single quotes. If you omit the quotes, the userid
of the TSO user or batch job will be appended to the front. Member
names and generation numbers must be enclosed in parentheses.
DSNAME is an alias for this keyword.
DDNAME(name-list)
specifies the list of 1 to 8 character names that are to be freed. FILE is
an alias for this keyword.
DELETE specifies that the data set is to be deleted after it is freed. See KEEP,
CATALOG, and UNCATLOG keywords.
DSNAME(dsname-list)
See DATASET keyword.
FILE(name-list)
See DDNAME keyword.
HOLD specifies that the SYSOUT data set is to be placed on the HOLD queue
when the data set is freed. See NOHOLD.
KEEP specifies that the data set is to be kept by the system after it is freed.
See DELETE, CATALOG, and UNCATALOG keywords.
NOHOLD specifies that the SYSOUT data set is not to be place on the HOLD
queue when it is freed. See HOLD.
SPIN({UNALLOC | NO})
specifies when a SYSOUT data set is available for printing. UNALLOC
indicates the data set can be printed after the file is freed. NO indicates
that the data set can be printed at the end of the current step.

SYSOUT(class)
overrides the SYSOUT class specified at allocation. You must specify
the one letter class identifier. Output will be sent to the job entry
subsystem. You can control how this data set will be processed by
specifying additional SYSOUT-related keywords such as HOLD or SPIN.
UNCATALOG specifies that the data set is to be removed from the catalog after it is
freed. The system will, however, still keep the data set. See KEEP,
DELETE, and CATALOG keywords.
Module Name:
RXTARXT, RXTDYNF
Environments:
All REXX/MVS environments. However, under NetView you should use the NetView
FREE command.
FREE is a host command that is executed under the REXXTOOL host command
environment. This command is used to:
• Unallocate data sets and ddnames. Data sets and/or ddnames can be freed
individually, or you can request that all eligible data sets and files be freed.
• Change certain allocation attributes such as SYSOUT class and HOLD status.
Notes:

function.
2. Keywords must be separated by one or more blanks (do not use commas!).
3. Some FREE keywords accept lists of values (this is indicated in each keyword's
description). When a list is coded, the values must be separated by blanks, commas,
or both.
The FREE command returns a return code in the REXX RC variable. Some return codes
"ADDRESS REXXTOOL".
The specific positive RC values returned by the FREE command are:

information.
In addition, the following REXX variables are created by the FREE command:
S99ERROR An error reason code in printable hexadecimal format. The values this
Authorized Assembler Programming Guide, GC28-1645 .
S99INFO An error information code in printable hexadecimal format. The values

this variable can take, and their meanings are documented in MVS/ESA
S99ERSN An SMS reason code in printable hexadecimal format. The values this
S99MSG. An array that contains dynamic allocation messages. S99MSG.0

contains the number of messages returned. S99MSG.1 contains the first
message and S99MSG.n contains the nth message. Note that messages
are always returned, even if OPTIONS NOMSGS is in effect. The
severity level of the messages returned is controlled by the MSGLEVEL
keyword.
Examples:
1. Add the REXXTOOL host command environment and free an existing allocation for
ddname INDATA:

address rexxtool
"free fi(indata)"
2. Free a SYSOUT data set and route it to a different SYSOUT class:
address rexxtool
"free fi(out) sysout(a)"

RXTDAIR (COBOL) Subroutine
Syntax:
RXTDAIR(cmdstr,rc,reason,info,msgind)
Arguments:
cmdstr a varying length character string that contains the ALLOCATE or FREE
command to execute. For assembler and COBOL, a halfword length field
must immediately precede the string. This halfword length field must
contain a value that reflects the number of characters in the string that
follows it. The length field's length must not be included in the length field
value. For PL/I, a declaration of CHAR(length) VARYING will
automatically provide the length field.
rc A full word integer containing the dynamic allocation return code. The
values that can be returned in this argument are documented in
MVS/ESA Authorized Assembler Programming Guide, GC28-1645 . This
argument corresponds to the SVC 99 R15 return value.
reason A full word integer containing the dynamic allocation reason code. The
values that can be returned in this argument are documented in
argument corresponds to the S99ERROR field of the SVC 99 request
block.
info A full word integer containing the dynamic allocation information code.
The values that can be returned in this argument are documented in
argument corresponds to the S99INFO field of the SVC 99 request block.
msgind An 8 byte fixed length character string (blank padded as required) that
contains one of the following values:
'MSGS' indicates that any pending messages are to be

displayed.
'NOMSGS' indicates that no messages are to be displayed.
Module Name:
RXTDAIR
Environments:
COBOL, PL/I, and Assembler programming environments. This module is not a REXX
subroutine.
Note:You should not use this service under CICS or IMS unless approved by your
systems programmer. SVC 99 can make the current task wait and can cause
changes to the TIOT.

The RXTDAIR module is used by assembler, COBOL, and PL/I programs to allocate and
free files. Linkage to RXTDAIR must follow standard MVS conventions:
R0 Undefined.
R1 Address of the parameter list. The parameter list consists of 5 fullword addresses
each of which points to a parameter. The last fullword in the array must have the
high order bit set to "1".
In assembler, use the CALL macro to create the parameter list. In COBOL, use the BY
REFERENCE keyword on each parameter to force "call-by-reference". In PL/I declare the
RXTDAIR entry point using the OPTIONS(INTER ASM RETCODE) clause.
R2-R12 Undefined.
R13 Address of a 72 byte register save area.
R14 Return address.
R15 RXTDAIR entry point address.
Very Important: Open Software recommends that you dynamically load and execute
RXTDAIR where possible. This will eliminate the need for you to re-link your programs as
future releases of REXXTOOLS/MVS become available. In assembler programs use the
LOAD macro. In PL/I programs use the FETCH statement, and in COBOL programs use
the CALL identifier format of the CALL statement.
The RXTDAIR program returns a return code (rc) that indicates the success of the
operation.
The following RXTDAIR return code values are possible:
information.
Examples:
1. Call RXTDAIR from PL/I to allocate a file (see SAMPLIB member PLIDAIR):
PLIDAIR: PROC OPTIONS(MAIN);

DCL RXTDAIR ENTRY OPTIONS(INTER ASM RETCODE),

CMD CHAR(34) VARYING
INIT('ALLOC FI(XX) DA(USER.DATA) SHR REU'),
RC FIXED BIN(31) INIT(0),
REASON FIXED BIN(31) INIT(0),
INFO FIXED BIN(31) INIT(0),
SYSPRINT FILE STREAM OUTPUT PRINT,
PLIRETV BUILTIN;
FETCH RXTDAIR;
CALL RXTDAIR(CMD,RC,REASON,INFO,'MSGS');
PUT DATA(CMD,RC,REASON,INFO);
END;
2. Call RXTDAIR from COBOL to allocate a file (See SAMPLIB member COBDAIR):
IDENTIFICATION DIVISION.
PROGRAM-ID COBDAIR.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 ALLOC.
02 CMD-LEN PIC S9(4) VALUE 34 BINARY.
02 CMD-DATA PIC X(34) VALUE 'ALLOC FI(XX)
DA(USER.DATA) SHR R
- 'EU'.
01 RC PIC S9(9) BINARY.
01 REASON PIC S9(9) BINARY.
01 INFO PIC S9(9) BINARY.
01 MSGIND PIC X(8) VALUE 'NOMSGS'.
PROCEDURE DIVISION.
0000-MAINLINE.
CALL 'RXTDAIR' USING
BY REFERENCE ALLOC
BY REFERENCE RC
BY REFERENCE REASON
BY REFERENCE INFO
BY REFERENCE MSGIND.
DISPLAY RC UPON CONSOLE.
DISPLAY REASON UPON CONSOLE.
DISPLAY INFO UPON CONSOLE.
GOBACK.

3. Call RXTDAIR from assembler to free a file (this example is taken from SAMPLIB
member ASMDAIR):
Program set up
.
.
.
*
* LOAD AND CALL THE RXTDAIR MODULE.
*
LOAD EP=RXTDAIR LOAD THE MODULE
LR R15,R0 GET THE MODULE ENTRY POINT
CALL (15), CALL RXTDAIR +
(FREECMD, THE COMMAND TO EXECUTE +
RC, THE RETURN CODE +
REASON, THE REASON CODE +
INFO, THE INFORMATION CODE +
=CL8'MSGS'),VL, WE WANT MESSAGES PRINTED +
MF=(E,CLPALS) USE REENTRANT FORM OF CALL
LTR R15,R15 RC OK?
.
.
.
Program break down
*
* MAINLINE STATIC STORAGE
*
FREECMD DC H'11',C'FREE FI(XX)'
LTORG BUILD LITERAL POOL
*
* DYNAMIC STORAGE
*
DYST DSECT DYNAMIC STORAGE AREA
#RGSVAR DS 18F STANDARD OS REGISTER SAVEAREA
CLPALS DS 20F CALL PARMLIST AREA
RC DS F RETURN CODE
REASON DS F REASON CODE
INFO DS F INFO CODE
DYSTSZ EQU *-DYST LENGTH OF DYNAMIC STORAGE AREA

The Interpretive Compiler
The REXXTOOLS/MVS interpretive REXX compiler is used to create load modules from
REXX source code. The compiler-generated load modules are in standard OS format,
and can be link-edited and invoked in the same manner as load modules produced from
other high level language compilers.
Why Compile?
Compiled REXX programs have significant advantages over source REXX programs:
• Source code can be hidden from end users. Load modules are stored in "U"
format data sets that cannot be viewed or modified by the ISPF/PDF Editor. In
addition, the source can be encoded in order to prevent a user of ISPF/PDF Browse
from viewing the source.
• Load modules are loaded into memory faster. For many REXX programs, the
major obstacle to better performance is load time, not execution time. Thus, by
compiling highly used REXX-based functions, you may be able to achieve your
performance objectives without rewriting your application in one of the traditionally
compiled languages such as PL/I, COBOL, or assembler. Compiled REXX programs
permit other optimizations, including the placement of highly used modules in REXX
function packages, or the system link pack area (LPA).
• Greater flexibility. Compiled REXX programs can be invoked directly from batch
jobs (EXEC PGM=rexxpgm), and under TSO can be invoked as command
processors, or using the TSO CALL command. You can even call compiled REXX
programs directly from High Level Languages and assembler.
• Program listings and symbol cross-references are provided. The additional

documentation provided by a source listing can make application support easier.
The REXXTOOLS/MVS interpretive compiler supports the complete REXX language

(including the INTERPRET instruction), as well as all of the published interfaces
described in the IBM publication TSO/E Version 2 REXX Reference, SC28-1883.
Note: While you must have a license for REXXTOOLS/MVS in order to use the
interpretive compiler, a REXXTOOLS/MVS license is not required to run compiled REXX
programs, unless the compiled programs utilize other REXXTOOLS/MVS services.
Interpretive Compiler 251

The Compilation Process
The process by which a program is converted from a source module to a load module is
described by the following figure:
RXTRXPRE
run-time
module
|
|
v
REXX ------> REXXTOOLS ------> Object ------> Linkage ------>
Load
source COMPILER module Editor
Module
|
|
v
Source
Listing
First, a REXX source module is processed by the interpretive compiler to produce an OS

object module and, optionally, a source listing. The object module consists of:
• Executable S/370 instructions.
• Data structures that describe the REXX program, and the run-time pre-processing
required.
• The source of the REXX program. The source may be "compressed" (i.e., all
comments and blanks are removed), and/or encoded. If encoding has been
specified, the source will be unreadable.
The compiler listing, if requested, has several components, some of which are
optional. At a minimum, the listing contains:
• A banner page indicating the date and time of compilation; the data set and volume
from which the REXX source was read; the user ID under which the compilation was
performed; and the compiler options that were specified.
• The source lines that were read. The lines are sequentially numbered.
• A statistics page giving the elapsed and CPU time for the compilation; compression
statistics if the COMPRESS option was specified; the number of source records read,
the number of object records written, and the number of listing records written.
Next, the object module is combined with the run-time prefix module, RXTRXPRE, by the
system linkage editor. This program is responsible for preparing the compiled REXX
program for execution by the system interpreter (IRXEXEC). All parameter list
conversions and decoding of source statements are performed by RXTRXPRE. In
addition, RXTRXPRE handles any conversions that may be required for data returned
from the compiled EXEC.

Running Compiled Programs
The relationship between a compiled REXX program and the system interpreter
(IRXEXEC) is shown in the following figure:
REXX Load Module

1. Decode REXX
source program.
2. Convert parm list. REXX
3. Build REXX BALR 14, 15 Interpreter
environment. (IRXEEXEC)
4. Call system
interpreter. BR 14
5. Convert returned
value.
6. Return to caller.
The RXTRXPRE CSECT of the compiled REXX program, after performing any required
pre-processing (parmlist conversions, decoding of REXX source lines), builds an in-
storage control block (INSTBLK) and branches (BALR 14,15) to the system interpreter
which resides in LPA.
The system interpreter processes the in-storage control block to run the REXX program.
After it is finished, IRXEXEC returns via a BR 14 instruction to the RXTRXPRE CSECT of
the compiled program. RXTRXPRE converts the REXX program's returned value, if
required, and returns control to its caller.
As with REXX source programs, compiled REXX programs must execute under a
language processor environment (i.e., the environment block and its associated control
blocks). IRXEXEC will attempt to find an existing language processor environment under
which to run the compiled program. In TSO address spaces the current task and its
parent task are searched. In non-TSO address spaces only the current task is checked. If
a language processor environment is not found, IRXEXEC automatically calls IRXINIT to
initialize an environment. Your compiled REXX programs do not need to be aware of the
address space or task under which they are running unless, of course, they utilize
environment-specific functions. For more information regarding language processor
environments and how they are located and/or initialized, see the IBM publication TSO/E
Version 2 REXX/MVS Reference, SC28-1883.
How a Compiled Program is Found
The data sets associated with the SYSPROC and SYSEXEC ddnames are used by the
system interpreter when searching for REXX source programs. You cannot place
compiled REXX programs in libraries associated with either of these ddnames.
Compiled REXX programs must be placed in libraries that can be reached by the MVS
LOAD macro instruction. The standard search order is as follows:
1. The job pack area
2. The task library
3. The step library

4. The link pack area (LPA)
5. The link library
For convenience, you may also place compiled REXX programs in the data sets
associated with the ISPLLIB ddname. This ddname is used as a kind-of steplib for
programs running under ISPF. ISPLLIB is not searched under native TSO (TSO READY).
Notes:
1. If you have installed any product that changes the search order for the MVS LOAD
macro, refer to the vendor's documentation for information regarding the new search
order.
2. If you link-edit a compiled REXX program into a library that is allocated to the
ISPLLIB ddname, you may have to exit and reenter ISPF in order for the program to
be found.
How to Call a Compiled Program
In general, a compiled REXX program may be called using the same syntax as was used
before compilation. For example, if prior to compilation a REXX program was invoked
using the function call syntax, after compilation it may still be invoked as a function.
Furthermore, in the same manner that REXX source programs can be alternately invoked
as functions, subroutines, or commands, so too, can compiled REXX programs be
variously called.
In most situations, the change from calling a REXX source program to calling a compiled
REXX program is completely transparent to both the calling program (or end-user, in the
case of commands) and the compiled program. The only exceptions to the "rule of
transparent replacement," are programs (or manual procedures) that use one of the
"explicit" types of command invocation. These are:
• The TSO/E EXEC command. The EXEC command only searches for REXX source
programs associated with the SYSPROC or SYSEXEC libraries.
• The "%" command invocation. "%" commands are always retrieved from the CLIST
or EXEC libraries first.
If you compile a program that is invoked via either of these methods, you must modify the
programs that call it to use either the "implicit" TSO command format (command name
followed by arguments), or one of the REXX formats (the REXX CALL instruction, or the
REXX function call).
Very Important: Compiling REXX programs that use IPCS facilities is specifically not
supported. In addition, there are limitations on the compiler's support for programs that
use ISPF services. See the next section for more details.

Alternative Invocation Methods
In addition to the standard methods for calling REXX programs, any of the following
techniques may be used to run a compiled REXX program:
EXEC PGM=REXXPGM
A compiled REXX program can be called using the JCL EXEC statement. You must use
the optional PARM keyword to pass an argument string, if one is to be supplied. You
must also supply Data Definition (DD) cards for SYSTSPRT (standard output for SAY,
and run-time messages) and SYSTSIN (standard input for PULL). The following example
shows how to run a compiled REXX program in batch:
//STEP1 EXEC PGM=MYRXXPGM,PARM='ARG1 ARG2'

//STEPLIB DD DISP=SHR,DSN=SOMEGUY.USER.LOAD
//SYSTSIN DD DUMMY
This batch step runs a compiled REXX program named MYREXXPGM. The program will
be searched for in the load library associated with the STEPLIB DD statement. Any
attempt to read from the standard input file will raise the end-of-file condition. Any lines
written to the standard output file will go to the default sysout class for the job.
Note: If your compiled REXX program utilizes any TSO service, you must run it under
IKJEFT01 (the batch TMP).
TSO CALL COMMAND
The TSO CALL command is used to invoke programs that expect an OS parmlist. From
the perspective of the compiled REXX program there is no difference between being
invoked as a command processor and being invoked as an OS program. The
RXTRXPRE CSECT converts both the TSO CPPL and the OS parmlist to a single
character string argument (you can use ARG(1) or PARSE ARG to retrieve this
information). For example, both:
READY
call 'someguy.user.load(myrxxpgm)' 'arg1 arg2'
and:
READY
myrxxpgm arg1 arg2
are equivalent.

ISPEXEC SELECT CMD(%CEXEC pgm)
Compiled REXX programs that are part of an ISPF Dialog Manager-based application,
can be invoked using the "ISPEXEC SELECT" command. To force ISPF to handle the
compiled REXX program's variables correctly, you must invoke your compiled program
using the CEXEC exec which is supplied in the REXXTOOL.EXEC library. CEXEC, which
must be placed in your SYSPROC or SYSEXEC data set concatenation, uses the
following syntax:
%CEXEC pgmname arg1 arg2 arg3... argn
Where pgmname is the name of the compiled REXX program and arg1-argn are the
arguments to be passed.
Notes:
1. If you use the "ISPEXEC SELECT CMD(%pgm)" method, TSO will search for a
source program before a compiled program.
2. Compiling REXX programs that use ISPF services may actually increase execution
times. For this reason, compiling this type of program is not recommended.
3. ISPF 4.1 and later releases support a LANG keyword that eliminates the need for
CEXEC. If you are using a version of ISPF that supports this feature, you can code:
address ispexec
"select cmd(cmpldpgm arg1 arg2) lang(crex)"
NETVIEW COMMAND LINE USING CNEXEC
Compiled REXX programs can be invoked from the NCCF command line using the
CNEXEC exec. CNEXEC, which must be placed in your DSICLD data set concatenation,
uses the following syntax:
CNEXEC pgmname arg1 arg2 arg3... argn
You should note however, that compiled programs run using the CNEXEC method will
run more slowly than their interpreted counterparts. For this reason, compiling this type of
program is not recommended.
FROM HIGH LEVEL LANGUAGES AND ASSEMBLER
Assembler programs and High Level Languages such as PL/I can directly call compiled
REXX programs. From the perspective of the calling program, the compiled REXX
program is an assembler-based module. 26 The calling program must supply a standard
OS parameter list, and must follow standard OS linkage conventions.
On entry to a compiled REXX program, the general registers must be set as follows:
R0 Undefined.
R1 Address of a parameter list passed by the caller. The parameter list consists of a
single full-word address that points to a parameter string. The high-order bit of
the full-word must be on (VL=1) to indicate the end of the parameter list.

The parameter string is a variable length character string (maximum length, 100 bytes)
prefixed with a two byte length field. The length field value does not include the 2 bytes
for the length field.
Note: You must pass a parameter string, even if it is null (i.e., the length field is zero).
R2-R12 Undefined.
R13 Address of a register save area.
R14 Return address
R15 Entry address
On return from a compiled REXX program, all registers will be restored to their pre-call
values, except for register 15. Register 15 contains the return code (if the called program
does not explicitly return a return code, R15 will contain zero).
The following is an example of a PL/I program invoking a REXX program:
TTZ: PROC OPTIONS (MAIN);

DCL TZ ENTRY OPTIONS(INTER ASM RETCODE),
ARGSTR CHAR(25) VARYING INIT('CALLED FROM PL/I'),
RC FIXED BIN(31) INIT(0),
SYSPRINT FILE STREAM OUTPUT PRINT,
PLIRETV BUILTIN;
CALL TZ(ARGSTR);
RC = PLIRETV;
PUT DATA (RC);
END;
In this figure, TZ is the name of the compiled EXEC. Notice that the PL/I CHARACTER
VARYING data type provides the right format for the parm string. The PLIRETV function
call returns the value of R15 as it was set by the TZ program.
RETURNING DATA FROM COMPILED REXX PROGRAMS
A special prefix module, RXTRXPRC, is provided to permit a compiled REXX program to

modify its arguments. The calling program must ensure that a standard OS parmlist is
generated, using "call-by-reference" parameter passing. The REXX program receives
arguments (obtainable via the ARG() function), that contain the printable hexadecimal
addresses of each of the calling program's parameters. The compiled REXX program can
use these addresses along with the STORAGE or STORAGEX functions to modify the
parameters in the calling program's storage. Example programs showing the use of this
facility can be found in members COB2REXX and RXXFMCOB of the sample library (the
JCL to compile and linkedit these samples is in the sample library member
COB2REXXJ).
OTHER PARAMETER LISTS
If the RXTRXPRE prefix module cannot recognize the passed parameter list as either a
TSO CPPL, a REXX EFPL, or an OS parameter list, it will attempt to format a printable
hexadecimal representation of th0e value contained in general purpose register 1, and

pass that to the program. The compiled program can use the ARG function in conjunction
with the STORAGE (or STORAGEX) function to obtain the program's arguments.
WARNING: Due to the wide variety of parameter lists that can be constructed, and the
equally wide number of environments that programs can run under, we recommend that
you carefully test programs that use the "other parameter list" format. Not all parmlists will
work. There are many circumstances under which the RXTRXPRE module will
erroneously classify the parameter list, resulting in abends. For best results when using
the "other parameter list" format, ensure that R0 does not point to a REXX environment
block.
Compiler Options
The REXXTOOLS/MVS interpretive compiler can be called using either of two facilities:
The RXC TSO Command

The RXC command can be invoked from TSO "READY" or from within ISPF. This
command provides a "front-end" to the batch compiler, RXTCOMP.
The RXTCL Batch Procedure

This JCL library member may be used to compile and link-edit REXX programs.
At the bottom of both methods is the batch compiler, RXTCOMP. Both RXC and RXTCL
accept as arguments compile-time options which are passed to RXTCOMP. These
options may be used to control the output of the compiler. For example, using a compiler
option you can create a version code "eyecatcher" in the object module.
The following table describes each of the batch compiler options and what effect they
have on the compiler's processing. The underlined letters indicate the minimum
abbreviation of an option's name:

Compiler Option Default Value Description
COMPRESS Compression is turned If specified, comments and extraneous blanks are
off removed from the copy of the source that is placed in the
object module. Compression is generally recommended,
since it results in faster loading and faster running
programs.
ENCODE Encoding is turned off This option is used to "hide" the REXX source lines
contained within the object (and load) module. If you
specify ENCODE, the source lines are encrypted in such
a manner as to render them unreadable.
NAME(pgmname) The member name of The name option is used to name the generated CSECT
the source data set, or and to provide data for the PARSE SOURCE instruction.
the next-to-last qualifier
of a sequential data set.
PAGESIZE(n) 55 lines Use this option to specify the number of print lines per
page of the listing.
VERSION(verstr) '00.00.00' You can use this parameter to supply an 8 byte
"eyecatcher" for the object module. The value can contain
any characters.
XREF No cross-reference is This option is used to create a symbol cross-reference at
produced. the end of the listing. All symbols, including REXX
keywords, are recorded.
PREFIX RXTRXPRE This option is used to specify the module prefix that will
handle program initialization. There are 2 prefix modules
supplied with REXXTOOLS:
RXTRXPRE
is used when the compiled module will be invoked as a
TSO command, a REXX subroutine, from JCL, or the
TSO CALL command.
RXTRXPRC
is used when the compiled module will be invoked from
assembler or one of the high-level languages such as
COBOL. RXTRXPRC also permits bi-directional argument
passing.
NONAMES Names are produced. This option is used to suppress the placement of names
in the object module. As a result, PARSE SOURCE will
not work correctly. Note: OST does not recommend using
this option as it makes debugging certain problems
harder.

Compiler Data sets
The interpretive compiler reads REXX source programs using the SYSIN ddname. The
object module is written to the SYSLIN ddname, and the source listing is written to the
SYSPRINT ddname. The characteristics of these data sets are described by the following
table:
Standard Data Set Contents RECFM LRECL BLKSIZE

DDNAME
SYSIN Input to the compiler. This data set contains FB or VB 80 or
the source REXX program. 255
SYSLIN The object module produced by the FB 80 800
compiler. This data set becomes input to
the linkage-editor.
SYSPRINT The source listing, including the FBA 133 13300
compressed listing, and the cross-reference
listing, if they are requested.
Notes:
1. You may use different block sizes for the source, object, and listing data sets to
conform to installation standards. The values listed are the defaults used by the RXC
command.
2. The batch compiler, RXTCOMP, verifies the allocation of the SYSPRINT and SYSLIN
ddnames before writing to them. If you do not allocate these data sets, neither a
listing nor an object module will be produced.
Linking Compiled REXX Programs

The object modules produced by the interpretive compiler must be link-edited with the
RXTRXPRE (or RXTRXPRC) object module before they can be executed. The system
linkage-editor must be used for this purpose. When link-editing a compiled REXX
program, use the following linkage-editor options:
Option Description
AMODE(31) This specifies that the addressing mode of the resulting load module will be the
extended addressing mode. If you do not specify AMODE(31), the compiled
program will switch to the 31 bit addressing mode upon entry, and switch back to
the 24 bit addressing mode before returning to its caller.
RMODE(ANY) This specifies that the load module may be loaded anywhere in virtual storage
(i.e., either above or below the 16-megabyte line).
You may also want to specify the RENT and REUS options (these options mark the load
module as reentrant and reusable) since the code generated by the compiler is not self-
modifying, and the RXTRXPRE module with which the compiled code is linked is, itself,
reentrant and reusable.
Note: Modules that you wish to load into LPA must always be link-edited using the RENT
option.

To include the RXTRXPRE module, allocate the REXXTOOLS/MVS load library to the
SYSLIB DD statement.
Using PUNCH Cards
The interpretive compiler supports the use of "PUNCH" cards. These may be used to
specify linkage-editor control cards within the source of a REXX program. The punch
card is a special type of REXX comment statement, and has the following format:
/* PUNCH linkage-editor-control-card */
The comment should be on a line by itself and must contain only uppercase letters. For
example, if you want to specify the AMODE/RMODE of a compiled REXX program you
would code:
/* PUNCH MODE AMODE(31),RMODE(ANY) */
Punch cards are always placed at the top of the object module. The linkage-editor control
statements you supply are not validated. Incorrect specification of these statements can
produce unpredictable results.
Syntax Checking
The REXXTOOLS/MVS interpretive compiler performs very limited syntax checking. In
fact, unless you specify COMPRESS or XREF, no syntax checking whatsoever is
performed. If you do specify one of these options, syntax checking is limited to
identifying:
• Incomplete literals (i.e., missing quotes or double quotes), and
• Incomplete comments (missing '*/').
As a consequence, programs that are not executable can be compiled successfully.

Errors other than the two listed above will not be apparent until execution time.
Ideally, you should not compile untested REXX programs. Since REXX source programs
can be transparently replaced with compiled REXX programs, you can easily test execs
using the system interpreter, prior to compiling them. Once your programs have "checked
out," you can compile them for production use.
Note: If you require static syntax checking, code a TRACE S statement at the beginning
of your REXX program and call it using the EXEC command. This will cause the system
interpreter to scan your program for syntax errors without actually executing any of its
statements.
Compiler Listings
The interpretive compiler produces a source listing whenever it detects that the
SYSPRINT data set is allocated. The listing always contains a banner page which
describes the data set being compiled and the options used to compile it; a sequential
listing of the source statements; and a statistics page.

There are three compiler options which affect the contents of the listing. These are:
COMPRESS This option produces a listing of the source post-compression. The

compressed source listing immediately follows the source listing.
XREF This option produces a listing of all the symbols contained in the source
program. The line numbers associated with each symbol show the
locations where the symbol is used. These numbers refer to the LINE
column numbers of the source listing, not the line numbers of the
compressed source listing.
Note: The cross-reference listing encompasses all program symbols, including REXX
keywords. It does not include any information contained within literals or comments.
PAGESIZE This options determines the number of print lines per page. The default
is 55.
Controlling the Listing
Each page of the listing begins with a heading line that contains the version of the
compiler, a listing title, and the date and time of the compilation. By default the listing title
contains the source data set name and the value of the NAME option. You can create
your own listing title by adding a title comment line to the top of your source data set. The
title comment line is an extension to the REXX comment used by the EXEC command to
distinguish REXX programs from CLISTs. The format is as follows:
/* REXX the title of the listing */
The title string can be up to 80 characters long. If you exceed this amount the value is
truncated on the right. There must be no other statements on this line.
Another type of special comment statement which you may use to control the listing is the
EJECT comment. The EJECT comment is used to force the compiler to start printing a
new page. It is coded:
/* EJECT */
The EJECT comment itself will not appear in the listing, so no other statements should be
coded on this line.
Optimizing Performance
While compiling a REXX program will significantly reduce its load time, and to a limited
extent its execution time, there are two other optimizations, available only to compiled
REXX programs, that can provide even greater gains in performance. These are:
• placing compiled REXX programs in function packages, and
• placing compiled REXX programs in the system link pack area.
Both methods essentially involve pre-loading programs to eliminate repetitive loading at

run-time. The following paragraphs describe each technique.

Function Packages
The first optimization you should consider is to place your compiled REXX functions and
subroutines in function packages. When resolving a reference to an external function,
IRXEXEC searches the available function packages prior to searching any other source
(including VLF). Moreover, IRXEXEC branches (i.e., BALRs) directly to programs
contained in function packages, thereby avoiding the use of expensive LOADs, EXEC
Loads, ATTACHes or LINKs.
A REXX function package consists of a function package directory and a collection of

load modules which implement the functions. For best performance the directory and the
individual functions can be link-edited together. A function package is identified to the
language processor by placing an entry in one or all of the REXX parameters modules.
Special authorization is not required to build a function package. Function packages may
be created by application programmers as well as systems programmers. In contrast,
other REXX optimization techniques, such as placing REXX source programs in the
Virtual Lookaside Facility (VLF), or placing compiled REXX programs in the link pack
area require very high levels of authorization.
Note: REXXTOOLS/MVS includes an IRXFUSER function package, which contains 20

empty entries. You can use the RXFUNC function (see "General REXX Extensions") to
dynamically add your compiled REXX programs to this function package.
For more information regarding the creation of REXX function packages, refer to the topic
"Function Packages" in the IBM manual TSO/E Version 2 REXX/MVS Reference, SC28-
1883.
Link Pack Area
Compiled REXX programs that are used as TSO commands can be placed in the system
link pack area. Since loading a module into LPA involves using storage common to all
address spaces, you should weigh the advantages of having faster access to a module
against the reduction in common storage available for other uses.
While anyone can build a function package, the loading of modules into LPA requires
high levels of authorization. Only specially authorized systems programmers are
permitted to modify the contents of LPA.

The sections that follow describe the syntax and operation of the REXXTOOLS
interpretive compiler.
RXC TSO Command
The RXC TSO command is used to invoke the REXXTOOLS/MVS interpretive compiler
from TSO. You may use the RXC command both interactively and from batch TSO. The
RXC command dynamically allocates the data sets required by the compiler, and passes
along any options you specify. The syntax of the RXC command is:
RXC sourcedsn [OBJECT(objdsn)]

[LIST(listdsn)]
[UNIT(unit)]
[copts]
Where:
sourcedsn is the name of the data set that contains the REXX program to be
compiled. If sourcedsn is partitioned, a member name must be supplied.
If sourcedsn is sequential you must specify the NAME option. Only FB
80 and VB 255 data sets are supported.
Note: The interpretive compiler uses the same rules that the REXX
interpreter uses for handling numbered records. If the data set is VB and
the first 8 columns of the first record are numeric, or if the data set is FB
and the last 8 columns are numeric, the data set is considered to be
numbered. In either case, the numbers are internally discarded.
objdsn is the name of the data set to which the object code is to be written. This
data set, if previously allocated, must be FB 80. If not previously
allocated, RXC will allocate the data set. If a member name is specified,
a PDS will be allocated. Otherwise, a sequential data set is created.
listdsn is the name of the data set to which the listing is to be written. The listing
data set, if previously allocated, must be FB 133. If not previously
allocated, RXC will allocate the data set. If a member name is specified,
a PDS will be allocated. Otherwise, a sequential data set is created.
unit specifies the type of device RXC is to use for allocating new data sets.
Only a DASD device type may be given. The default value is 'SYSDA'.
copts specifies the batch compiler options.
The RXC command returns a return code to indicate the success or failure of the
operation. A zero return code indicates successful compilation. Any other return code
indicates some sort of error. The listing will contain error messages indicating the nature
of the problem.

RXTCL Batch Procedure
The RXTCL batch procedure may be used to compile and link-edit your REXX programs
in batch. By default, RXTCL allocates a temporary data set for SYSLIN (the object data
set), and routes SYSPRINT (the listing data set) to the dummy data set. You must supply
a SYSIN DD statement to identify the REXX source data set, and a SYSLMOD DD to
identify the load data set.
The RXTCL JCL procedure accepts two parameters:
RXCPARM The string of blank-delimited batch compilation options. The RXC

keywords are not valid in this context.
LNKLIB The name of the data set containing the RXTRXPRE module.
In the example below, the RXTCL batch procedure is called to compile a program using
the COMPRESS, XREF, and NAME options. The LNKLIB parameter will use whatever
default the REXXTOOLS/MVS installer supplied:
//STEP1 EXEC RXTCL,RXCPARM='COMPRESS XREF'

//C.SYSIN DD DSN=SOMEGUY.USER.EXEC(T2000),DISP=SHR
//C.SYSPRINT DD DSN=SOMEGUY.USER.RXLIST(T2000),DISP=SHR
//L.SYSLMOD DD DSN=SOMEGUY.USER.LOAD(T2000),DISP=SHR
If you desire to keep the object module produced by the "C" step of RXTCL, you must
code an override DD statement for the SYSLIN data set.

CICS External Interface
The REXXTOOLS/MVS EXCI interface gives REXX programmers access to CICS
transactions written to the Distributed Program Link (DPL) specification. The
REXXTOOLS function, REXCI is implemented over the IBM-supplied EXCI "call"
interface. Before using REXCI, you should read the section entitled "External CICS
Interface" in the IBM manual CICS External Interfaces Guide. The External Interfaces
Guide covers many topics not described here, such as resource definition and security
issues.
Notes:
1. EXCI requires CICS Interregion Communications (IRC) and Multiregion Option

(MRO). Please refer to your system's CICS Installation Guide and External Interfaces
Guide for more information.
2. Before you use the REXXTOOLS interface, you should verify that EXCI is
operational on your system. IBM supplies a suite of EXCI sample programs in the
CICS sample library, as well as resource definitions in the DFH$EXCI group (the
DFH$FILA group is also required). The External Interfaces Guide documents these
programs.
3. After you have run IBM's EXCI sample programs, you should run the REXXTOOLS
sample client program, REXCI01, with IBM'S sample server program, DFH$AXCS.
REXCI Call Types

The REXCI function supports 6 different types of calls. These are:
1. Initialize_User
2. Allocate_Pipe
3. Open_Pipe
4. DPL_Request
5. Close_Pipe
6. Deallocate_Pipe
The calls must be issued in the order shown.
CICS External Interface 267

Initialize_User
The Initialize_User call establishes an Interregion Communication (IRC) environment for

the task. This environment remains in effect for the life of the task. There is no
Terminate_User function.
Initialize_User must be the first call that you issue, and you must issue it only once per
task. Multiple Initialize_User calls appear to be tolerated, but IBM's documentation does
not recommend it.
The input parameter for this call, user_name, identifies the client program to CICS.
However, if a specific pipe is to be used, user_name must be the same as the NETNAME
of attribute of the CONNECTION.
A user token is returned by a successful call. This token must be specified in all other
REXCI calls.
Allocate_Pipe
The Allocate_Pipe REXCI call allocates a session to a specific CICS region. The generic
applid of the CICS region is specified on the call. If the applid is not specified it must be
supplied by the user-replaceable module, DFHXCURM (Refer to IBM's External
Interfaces Guide for how this is done). According to IBM's documentation, up to 100
pipes per address space can be open at any one time.
Upon return, the Allocate_Pipe call returns a pipe token that must be supplied in the
Open_Pipe, DPL_Request, and Close_Pipe calls.
Open_Pipe
The Open_Pipe call opens a session to the CICS region specified in the Allocate_Pipe
call. This call does not return anything.
After the Open_Pipe has been executed, the client program is ready to communicate with
the server program.
Note: Pipes should not be left open when not in use. Open pipes can cause CICS
shutdown to hang.
DPL_Request
The DPL_Request call sends an application-defined string to a server application. To the

server program, the request appears as a normal EXEC CICS LINK invocation. The
server application can modify the string and return it to the program making the
DPL_Request call. There is no limit as to the number of DPL_Request calls that can be
made over an open pipe.

Close_Pipe
The Close_Pipe call closes the session with the CICS that was specified on the
Allocate_Pipe call. The pipe can be reused, however, provided that another Open_Pipe
call is made using the same pipe token.
Note: Pipes should not be left open when not in use. Open pipes can cause CICS
shutdown to hang.
Deallocate_Pipe
The Deallocate_Pipe call frees the session with the CICS. After this call the pipe token is
invalid and must not be used again.
Running EXCI Execs

REXX programs that use the REXCI function can run under TSO (interactive and batch),
batch REXX (IRXJCL), and as a started task (IRXJCL or IKJEFT01). In addition to the
REXXTOOLS load library, your job must be able to access the modules in the
CICS.SDFHEXCI load library. The SDFHEXCI library contains the DFHXCIS module that
implements the EXCI call interface.
Example JCL for running the REXXTOOLS sample exec, REXCI01, is shown below:
//REXCI01 EXEC PGM=IRXJCL,PARM='REXCI01 CICS'

// DD DISP=SHR,DSN=CICS.SDFHEXCI
//SYSEXEC DD DISP=SHR,DSN=REXXTOOL.SAMPLIB
//SYSTSIN DD DUMMY
CICS External Interface 269

REXX External Writer Facility
Overview
The REXXTOOLS/MVS REXX external writer facility is a program and a collection of
REXX functions that permit the development of external writers in REXX. An external
writer is a program, external to the Job Entry Subsystem (JES), that processes JES spool
data sets (also called SYSOUT data sets). External writers can examine, copy, and/or
delete data sets from the JES spool. The actual processing performed is left to the
discretion of the application programmer.
The writer facility is implemented over MVS's SYSOUT Application Programming

Interface (SAPI). Because of this, it can be used with either JES2 or JES3.
The REXX external writer facility program is RXTWTR. This program can be run from
JCL either within a batch job or a started task. RXTWTR is not designed for use under
TSO or other environments.
Functions
REXX programs that execute under RXTWTR have special functions available to them:
SDSALLOC Allocates a selected spool data set.
SDSCLOSE Closes an open spool data set.
SDSFREE Frees a selected spool data set.
SDSGET Gets a record from an open spool data set.
SDSINFO Retrieves information about a selected spool data set.
SDSOPEN Opens a selected spool data set.
SDSPARM Changes selection parameters.
WTREVENT Returns a writer event, such as an available spool data set or a console
command.
WTRMSG Writes a message to the console.
Your program uses these functions, and possibly other REXXTOOLS functions and host
commands, to accomplish the desired task.
Note: A complete writer demonstration program is contained in member RXWTR of the

REXXTOOLS sample library.
REXX External Writer Facility 271

Structure of a Writer
The REXX writer facility processes spool data sets using an "event" architecture. That is,
programs process various types of events in a loop. The 2 main types of event are:
• A spool data set (SDS) is ready to be processed.
• An MVS STOP command has been issued for the task.
To handle these and other events, all REXX programs run under RXTWTR must have
the following basic structure:
1. Initialize and set selection parameters
2. Get an Event
3. If the event is a STOP command go to "Terminate."
4. If the event is a spool data set is ready, process the data set.
5. If it is another type of event, process it.
6. Go back to "Get an Event".
7. Terminate
The "Get an Event" step uses a REXX function WTREVENT to get the next event. If no
event is immediately available, WTREVENT waits for one.
In pseudocode, the event loop looks like this:
Initialize and set selection parameters

Get an Event
Do while not a STOP event
if SDS event, process it
if other event, process it
Get an Event
end
Terminate
The processing of STOP events is fairly obvious: the application cleans-up any resources
it has allocated and terminates. If you have some other way of terminating your
application you do not need to process STOP events. For example, you could create a
writer that processes a specific number of spool data sets and then terminates.
When handling an SDS event there are several actions the application could take. For
example it could:
• Read the SDS and copy all or part of the information to another data store such as
an MVS data set.
• Get information about the SDS. A REXX function, SDSINFO provides meta-
information about the SDS, such as the name of the STEP that created it.

• Change the disposition of the data set. The data set can be kept on the spool, moved
to a new class or queue, or deleted.
The exact course of action is left to the application programmer. Any, all, or none of the
above actions could be taken. However, everything you want to do with the SDS must be
done before you ask for the next event. At that time any new disposition you have
specified -- which could be delete -- takes place. Depending on disposition options, you
may not be able to select the data set again.
There is a reverse problem to guard against: selecting the same SDS multiple times. If
you keep the data set on the spool and do not change any of its characteristics, you
could re-select the data set on another WTREVENT call. If this happens your program
could enter an endless loop. If you do not specify DELETE for the DISP parameter (see
SDSPARM), you should specify NORADDR to "try" and prevent JES from handing you
the same SDS again. Note that NORADDR (and NORTHRD) do not guarantee that you
won't select the same SDS again, so you might have to implement an application-specific
solution, such as a table of processed SDSs.
Security Issues
SAPI uses JESSPOOL class security. To access spool data sets, your writer program
must execute with a user ID that has UPDATE authority to profiles in the JESSPOOL
class. Failure to provide appropriate authority will result in spool data sets not being
selected for processing.
Refer to the RACF Security Administrator's Guide for more information on JESSPOOL
and SAPI security. If you are using another security product, look for JESSPOOL security
in their documentation.
REXX External Writer Facility 273

REXX MQSERIES Interface
The REXXTOOLS/MVS MQSERIES interface is embodied in a REXX function called
RXMQ (see the file “RXMQ.HTM” located in \OST\RXT\V070101\HTML). This function
has many sub-functions, which are discussed in following sections. Using this interface
you can connect to queue managers; open and close objects, such as queues; put and
get messages to and from queues; and inquire and set certain queue attributes.
Design Philosophy
The REXXTOOLS MQSERIES interface is written over the assembler language API for
MQ. Every attempt has been made to give the interface as little "personality" as possible
and let the underlying API shine through. For this reason, detail questions as to the
behavior of the interface should be directed to the Websphere MQ Application
Programming Reference, SC34-6062.
Functions
REXX programs that use RXMQ have many sub-functions available to them. They are
listed in roughly the order in which they are used:
CONS
Creates all of the REXX constants for your program to use.
MQCONN
Connects to a queue manager.
MQOPEN
Opens an object such as a queue.
MQGET
Retrieves a message from a queue if one is available.
MQPUT
Places a message on a queue.
MQSET
Sets an object (possibly a queue) attribute.
MQINQ
Retrieves the value of an object's attribute.
MQCLOSE
Closes an object such as a queue.
MQDISC
Disconnects from a queue manager.
Your program uses these sub-functions, and possibly other REXXTOOLS functions and
host commands, to accomplish the desired task.
REXX MQSERIES Interface 275

Note: A complete demonstration program is contained in member MQGET of the
REXXTOOLS sample library (see the file “MQGET.TXT” located in
\OST\RXT\V070101\HTML).
A Word about Stems

In many cases, stem variables are used as arguments to the RXMQ function. When you
pass the stem variable you pass the name of the stem NOT the stem itself. The suffixes
are fixed and known to the program. Prior to executing the sub-function, it will search for
the stem's values, convert numbers to binary where necessary, and stuff them into a real
data structure for a call (an MQOPEN, for example). Then after the call, but before
returning to your REXX program, it will run through the fields of the data structure
creating or updating stem variables (and converting binary data where it needs to). Not all
of the fields will have been updated by MQ by the call, though. Refer to the API
Reference for which fields are taken as input and which are output (in some cases fields
are both).
Putting Messages
To put messages onto a queue, you must perform the following steps:
1. Connect to the queue manager using the MQCONN subfunction.

2. Open the queue using the MQOPEN subfunction. You must use the
MQOO_OUTPUT option.
3. Put one or more messages onto the queue using the MQPUT subfunction.
4. Close the queue using the MQCLOSE subfunction.
5. Disconnect from the queue manager using the MQDISC subfunction.
Steps 1 and 2 are normally performed during program initialization and steps 4 and 5 are
generally performed during termination. Step 3 is usually in a loop of some sort.
Getting Messages
To get messages from a queue, you must perform the following steps:

2. Open the queue using the MQOPEN subfunction. You must use one of the input
options such as MQOO_INPUT_EXCLUSIVE.
3. Get one or more messages from the queue using the MQGET subfunction. When
there are no more messages to get, a reason code of MQRC_NO_MSG_AVAILABLE
will be returned.
Steps 1 and 2 are normally performed during program initialization and steps 4 and 5 are
generally performed during termination. Step 3 is usually in a loop of some sort.
Sometimes you will want to wait on messages to come to an empty queue. You can do
this by specifying WGMO_WAIT and giving a non-zero wait interval. When the MQGET
returns it will either indicate that the wait has expired and no message has returned or it
will return a message.

Inquiring about Attributes
To inquire about queue or other object attributes perform the following steps:

2. Open the queue using the MQOPEN subfunction. You must use the
MQOO_INQUIRE option.
3. Inquire on one or more attributes using the MQINQ subfunction.
Setting Attributes
To set queue or other object attributes perform the following steps:

2. Open the queue using the MQOPEN subfunction. You must use the MQOO_SET
option.
3. Set one or more attributes using the MQSET subfunction.
REXX MQSERIES Interface 277

Appendix A: Working with Record
Fields
The access method interfaces supplied by REXX and REXXTOOLS do not support direct
access to specific fields within a record. Yet most applications require field-level access.
In many high-level languages, such as PL/I and COBOL, declared record definitions
perform this function. While REXX does not support the notion of a record structure, the
language does contain several constructs that work just as well. Moreover, REXX gives
you the ability to dynamically change your program's view of the data, a capability that is
poorly implemented in many other high-level languages, when it is supported at all.
Parsing Records With REXX

Most programmers who are new to REXX parse records using the SUBSTR (substring)
function. For example, to parse a record with 3 fields you could code:
name = substr(record,1,10)
ssn = substr(record,11,9)
balance = substr(record,20,5)
While this method translates easily from other languages (most of which support some
form of substring), it suffers from several defects:
• It tends to perform poorly as the number of fields increases.
• It is difficult to program, since the absolute offsets of fields must be calculated by

hand.
Experienced REXX programmers use other techniques to parse records. The most
flexible and by far the best performing method for breaking apart records is the REXX
PARSE instruction.
The REXX PARSE instruction has several distinct advantages over other methods:
• PARSE is efficient. PARSE permits you to separate all of the fields in a record with
a single REXX instruction. And because PARSE is a REXX instruction -- as opposed
to a function or host command -- it receives preferential treatment by the interpreter
(this statement is doubly true for programs compiled with the REXX/370 compiler).
PARSE also allows your programs to avoid unnecessary work. If you want to access
only one or two fields in a record, PARSE lets you extract just the relevant data.
• PARSE is flexible. PARSE permits record splitting that is sensitive to the data within
the record. Unlike traditional record structures, PARSE allows (indeed, encourages)
the use of pattern matching to break apart highly variable data.
• PARSE is portable. The PARSE instruction is a part of the REXX language, proper.
Because of this, PARSE can be used with any access method and on any platform.
In contrast, proprietary parsing facilities generally are not available in all
environments.
Appendix A: Working with Record Fields 279

The next two sections provide a brief review of PARSE VAR and PARSE VALUE, the two
forms of PARSE that are particularly useful for handling record fields.
Note: The TSO/E Version 2 MVS/REXX Reference, SC28-1883 contains an excellent

chapter on REXX parsing (in the TSO/E 2.4 level of this manual, see "Chapter 5.
Parsing"). This chapter describes all of the uses of PARSE, and contains a flow chart
which documents, precisely, the behavior of the instruction. This chapter should be
required reading for anyone interested in using the PARSE instruction.
PARSE VAR
PARSE VAR is used to split a record contained within a REXX variable. The general
format for the PARSE VAR instruction is:
PARSE VAR varname template
where varname is the name of the REXX variable that contains the data to parse, and
template is the set of instructions for executing the parse (templates are discussed
below). Varname can specify either a simple symbol or a REXX stem variable.
PARSE VALUE
PARSE VALUE is used to parse a record that is the result of a REXX expression. The
general format for the PARSE VALUE instruction is only slightly different from that of
PARSE VAR. It is:
PARSE VALUE expression WITH template
where expression is any arbitrarily complex REXX expression, and template is, again,
the instructions for conducting the parse.
In the context of file access, PARSE VALUE is of special importance because it can be
combined with the REXXTOOLS GET function, which returns a retrieved record. The
following REXX instruction demonstrates how this works:
parse value get('indd',keyvar,'(key,dir)') with,

name +10 ssn +9 address +30 salary +5
As you can see, with one REXX instruction you can both read a record and separate its
fields.

Basic Parsing
All forms of PARSE use templates to specify the parsing action of the instruction. There
are two formats for templates:
String patterns which specify patterns for extracting data, and
Positional patterns which use absolute or relative offsets to extract data.
A string pattern specifies data which the PARSE instruction is to search for in order to
split out fields. For example, in the following PARSE VAR instruction, the patterns
"SSN=", "NAME=" and "ZIP=" are used to find where the record is to be divided:
/* Assume record contains:
'SSN=123456789 NAME=FRED ZIP=12345' */
parse var record 'SSN=' ssn 'NAME=' name 'ZIP=' zip
/* This yields:
ssn = '123456789'
name = 'FRED'
zip = '12345'
*/
Positional patterns are used to indicate the absolute or relative positions at which the
record is to be split. Parsing by absolute position is equivalent to SUBSTR parsing
(except that you can substring many fields in one instruction). In the following example,
absolute positions are used to extract three fields:
/* Positions:----+----1----+----2----+ */
parse value 'Richard Travis 01' with,
firstname 11 lastname 21 empno
/* This yields:
firstname = 'Richard '
lastname = 'Travis '
empno = '01'
*/
Relative positions are indicated by coding a plus sign (+) or a minus sign (-) in front of the
number. Parsing by relative position is frequently much easier than parsing by absolute
position, because you don't need to manually calculate field offsets. You only need to
know how long a field is. For example, the PARSE in the previous example re-coded for
relative positions would look like this:
parse value 'Richard Travis 01' with,

firstname +10 lastname +10 empno

Advanced Parsing Problems
This section describes solutions to commonly encountered parsing problems:
Handling Conversions
If you are designing a new application, you may want to consider storing all fields of a
record -- including numeric fields -- in the REXX printable format. This strategy will allow
you to avoid all conversions. If you are processing "legacy" files containing binary and
packed numeric data, you probably will need to convert some field values to the REXX
decimal format in order to use them in computations.
The following table describes the conversion functions you will need:
Data Type Conversion After GET Conversion Before Build and PUT
and PARSE
2 byte binary C2D(fieldvalue) D2C(fieldvalue,2)
integer (halfword)
4 byte binary C2D(fieldvalue) D2C(fieldvalue,4)
integer (fullword)
packed decimal P2D(fieldvalue,s) where D2P(fieldvalue,p,s) where p is the total
s is the number of number of digits and s is the number of
fractional digits. fractional digits.
short floating F2D(fieldvalue) D2F(fieldvalue,'SHORT')
point
long floating point F2D(fieldvalue) D2F(fieldvalue,'LONG')
printable numeric PIC2D(fieldvalue) D2PIC(fieldvalue,picstr) where picstr is
edited the picture specification.
Note: The C2D and D2C functions are documented in the REXX/MVS Reference. All of
the other functions are documented in the "General REXX Extensions" chapter of this
manual.
Parsing Records with Multiple Formats
PARSE permits a record to be broken-up in several ways -- all in one PARSE instruction.
To parse a record more than once, you separate the various formats with an absolute
position. In the following example, we parse the entire contents of a record into a variable
called 'record', then we back up and break the record into 3 fields:
parse value 'Abraham Lincoln President ' with,

record 1 firstname +10 lastname +10 job
/* Results in the following:

record = 'Abraham Lincoln President'
firstname = 'Abraham '
lastname = 'Lincoln '
job = 'President '
*/

You can also use relative positioning to "back up" to an earlier position, and parse
forward from there. This technique is demonstrated in the following example:
parse value get('indd') with rectype +2,

fname +10 lname +10 -20, /* rectype=1 */
Address +30 -30, /* rectype=2 */
salary +5 bonus +5 /* rectype=3 */
Using In-line Parse Routines
If your templates are long, or if you simply want to keep all of the parsing information for a
record in one place, you may want to use the in-line routine technique demonstrated by
the following code segment:
GetEmpRec = "parse value get('indd') with",

"firstname +10 lastname +10 empno +4",
"salary +5; empno=c2d(empno);",
"salary=p2d(salary,2)"
interpret GetEmpRec
do while rc = 0
salary = salary * 1.10
say firstname"'s new salary:"d2pic(salary,'$$$,$$9.99')
interpret GetEmpRec
end
Note that GetEmpRec contains all of the instructions for reading, parsing and converting
fields in a record. Each REXX instruction is separated by a semicolon (;). The REXX
INTERPRET instruction is used to run this in-line parse routine (which can be as complex
as you need) whenever another record is required.
Another way to handle this problem is to place all of the statements for reading (or
writing) a record into a conventional internal subroutine. Be aware, though, that internal
subroutines cannot be shared among separate REXX source files, whereas strings, such
as GetEmpRec can be shared (see "A Simple Methodology for Sharing Record
Definitions"). An external routine could also be used, but then you would need to use
global variables to pass field values between the called and calling routines (not an
elegant solution).

Building Records With REXX
New records or records whose fields have been changed must be reassembled before
they are written to a file. Using the REXX concatenation operator (||), an entire record can
be built with a single REXX instruction. For example:
EmpRec = left(firstname,10)||,
left(lastname,10)||,
d2c(empno,4)||,
d2p(salary,9,2)
In this example the REXX LEFT function is used to left justify and truncate or pad the
character fields (FIRSTNAME and LASTNAME) to their desired lengths (in this case, 10
bytes). The D2C function is used to convert the EMPNO field from a REXX decimal
number to a full-word binary integer. And, the REXXTOOLS D2P function is used to
convert SALARY from a REXX decimal number to a packed decimal number.
Advanced Record Building
As we saw with record parsing, it is often desirable to keep all of the information for
manipulating a record in one place. The in-line routine technique (see "Advanced Parsing
Problems" above) can also be applied to record building, as the following code segment
demonstrates:
PutEmpRec = "EmpRec=left(firstname,10)||",
"left(lastname,10)||",
"d2c(empno,4)||",
"d2p(salary,9,2);",
"call put('outdd',EmpRec)"
parse pull firstname lastname empno salary

do while firstname <> ''
interpret PutEmpRec
parse pull firstname lastname empno salary
end
In-line routines like PutEmpRec can be as simple or as complex as you need them to be.
They can contain entire programs, including IF, SELECT, and iterative DO instructions.

A Simple Methodology for Sharing Record Definitions
In the previous examples we assumed that just one REXX source program would be
accessing a file. However, in many applications, several components (separate source
programs) may need to access the same file. To handle this problem, you could replicate
record-handling code in all of the programs that need to process the file. Unfortunately,
the replicated code would present a severe maintenance problem: any time you needed
to change a record definition, you would have to modify all of the copies of the code.
REXX provides an elegant solution to this problem that is based on the "in-line" routine
method, presented earlier. This solution allows all of the logic for handling a record to be
placed in one external source program, called a record definition function. The record
definition function does not perform any operations on a record directly. Instead, it returns
the logic for performing an operation, encapsulated in an in-line procedure. The following
example shows how this works.
First, we construct a record definition function for parsing and building the records in the
employee file:
/* REXX EmpRDef */
function = translate(arg(1))
recvname = arg(2)
select
when function = 'PARSE' then
return "parse var" recvname,
"firstname +10 ",
"lastname +10 ",
"empno +04 ",
"salary +05;",
"empno = c2d(empno);",
"salary = p2d(salary,2)"
when function = 'BUILD' then
return recvname "=",
"left(firstname,10)||",
"left(lastname,10)||",
"d2c(empno,4)||",
"d2p(salary,9,2)"
otherwise
return "*ERROR*"
end
The EmpRDef function takes two arguments. The first argument, function, indicates what
type of in-line routine EmpRDef is to generate. The second argument gives the name of
the variable that contains or will contain the employee record. When a value of "PARSE"
is specified for the function argument, EmpRDef returns an in-line routine to parse and
convert the fields of the record. If "BUILD" is specified, the code for converting the fields
and constructing a record is returned.

Now let's look at how a program uses EmpRDef. The following program sequentially
reads the employee file:
ParseEmpRec = EmpRDef('PARSE','EmpRec')
EmpRec = get('indd')
do while rc = 0
interpret ParseEmpRec
say firstname lastname empno d2pic(salary,'$$$,$$9.99')
EmpRec = get('indd')
end
Notice that all of the information related to field positions and data types is hidden from
EmpRDef's caller. The calling program needs to know only the names of the fields.
This method is very flexible, and can be expanded to encompass much more of the
process. A logical extension of this technique is the file definition function, a function that
encapsulates I/O-related tasks as well as record definitions. A file definition function
might, for example, accept a "GETALL" function code that would return all of the logic
needed to:
1. Open the file
2. Read and parse all of the records into a family of stem arrays, and
3. Close the file.
Depending on how much information you want to hide in the file definition function, the
calling program's file logic could be as simple as:
interpret EmpFDef('getall', 'indd')
Other processes that you may want to include in this type of function are:
• Automatic record locking using the REXXTOOLS ENQ and DEQ functions.
• A function code that returns the names and data types of the fields in the record. In
other words, a record descriptor.
Self-defining VSAM Files
If you are defining new VSAM files, you may want to consider making them self-defining
files. A self-defining file is one that contains both data and the instructions for accessing
the data. One way to make a KSDS self-defining is to store in-line subroutines for parsing
and building records in the "high-values" record (many KSDSes are initialized with a
record containing X'FFFFF...' in the key field). Any program that wants to process the
self-defining file, opens the data set and reads the high-values record. The program then
has all of the logic needed to parse and build the other records in the file.

Appendix B: REXX Development Tools
REXXTOOLS/MVS includes a collection of REXX-based application development
utilities. These REXX programs also are an excellent source of REXX programming
techniques. The following sections describe each utility in detail.
CC (Concatenate Command)
The CC exec can be used to extend the data set concatenation of any ddname that is not
currently open. The CC command can be used from TSO READY-mode (on-line or
batch) and from within ISPF. The syntax of the CC command is:
CC ddname dsname
where ddname is the ddname you want to add to, and dsname is the data set you want
to add. The optional SHOW operand causes CC to display the allocations after the
concatenation is performed.
For example, to add data set 'TSOUSER.EXEC' to ddname SYSEXEC (and show the
resulting concatenation) you would enter:
cc sysexec 'tsouser.exec' sh
DCC (Deconcatenate Command)

The DCC exec can be used to remove a data set from a data set concatenation. The
ddname cannot be open when the DCC command is run. The DCC command can be
used from TSO READY-mode (on-line or batch) and from within ISPF. The syntax of the
DCC command is:
DCC ddname dsname
where ddname is the ddname you want to remove from, and dsname is the data set you
want to remove. The optional SHOW operand causes DCC to display the allocations after
the deconcatenation is performed.
For example, to remove data set 'TSOUSER.EXEC' from ddname SYSEXEC (and show
the resulting concatenation) you would enter:
dcc sysexec 'tsouser.exec' sh
Appendix B: REXX Development Tools 287

DDL (DDNAME List Command)
The DDL exec can be used to display one or all data set concatenations. The DDL
command can be used from TSO READY-mode (on-line or batch) and from within ISPF.
The syntax of the DDL command is:
DDL
where ddname is the ddname you want to display. If the ddname operand is not
supplied, all currently allocated ddnames are displayed.
For example, to display the data sets concatenated to the SYSEXEC ddname you would
enter:
ddl sysexec
DDS (DDNAME Scan Command)

The DDS exec can be used to find a member in one or all data set concatenations. The
DDS command can be used from TSO READY-mode (on-line or batch) and from within
ISPF. The syntax of the DDS command is:
DDS {ddname| *} member
where ddname is the ddname you want to display. If the "*" is used, all currently
allocated ddnames are scanned. The member operand specifies the member name to
be scanned for.
For example, to search for member MYEXEC in the SYSEXEC data set concatenation
you would enter:
dds sysexec myexec
DDS indicates a found member by placing asterisks (*) around the data set(s) containing
the member name. It also reports the number of times the member name is found.
LLS (Link List Scan Command)

The LLS exec can be used to find a member in the link list data sets. The LLS command
can be used from TSO READY-mode (on-line or batch) and from within ISPF. The syntax
of the LLS command is:
LLS member ieasys-suffix
where member is the member name to search for, and ieasys-suffix is the suffix of the
SYS1.PARMLIB(IEASYSxx) member that is currently in effect (the member that was
used for the latest IPL).
For example, to search the link list for member IRXFLOC you would enter:
lls irxfloc 01

where '01' indicates that member IEASYS01 of SYS1.PARMLIB should be used to derive
the list of link list data sets.
Note: Your TSO user ID must have sufficient authority to open link list data sets for read
access. If it does not, errors will result.
OSENVIR (Display OS Environment)

The OSENVIR exec can be used to determine the level of operating system, the level of
TSO/E, and the hardware serial numbers of your system. The OSENVIR command can
be used from TSO READY-mode (on-line or batch) and from within ISPF. The syntax of
the OSENVIR command is:
OSENVIR
There are no operands for this command.
RF (Edit Macro)
The RF program is an ISPF EDIT macro. You must place RF in your SYSPROC or
SYSEXEC data set concatenation. To use RF, you enter the RF primary command while
editing a REXX program in ISPF/PDF Edit (option 2). You may optionally pass a number
between 1 and 3 that indicates the number of spaces RF is to indent between levels of
logic.
RF is a very simplistic formatter, which is both its strength and its weakness. Its simplicity
is a strength in that it does not attempt to force a particular coding style on you. It merely
aligns statements on the line they are on. RF will not move data between lines. However,
because it "understands" very little about the structure of REXX, it can easily be confused
and can produce results which are actually worse than what you started with. For this
reason always save your work before using RF, or at least make sure you have turned
recovery processing on.
RF has the following limitations:
1. Only all upper case data sets can be formatted.
2. No comment formatting is performed.
3. Labels that are coded on the same line as other REXX clauses are not supported.
4. The program is unaware of literals.
5. Multiple statements per line are not recognized.
6. Most continuations are not recognized.

RL (REXX Listing Program)
The RL listing program reads REXX source programs and produces printed listings with
page headings. The user can control page breaks by placing special comments in the
source program.
The RL program expects the following arguments:
1. The name of the data set to format. If you fully qualify the data set name, place it in
quotes. If you do not place the data set name in quotes, a first level qualifier
consisting of the user's TSO ID will be used.
2. The destination of the listing. This is the name of the printer to which the listing is
to be sent.
3. The SYSOUT class. Indicates the appropriate SYSOUT class for your printer.
By default RL will place a title at the top of each page of the listing. The title is of the form
"LISTING OF: dsn" where dsn is the name of the data set being formatted. You can
create your own title by placing the following comment statement at the top of your data
set:
/* REXX your title goes here */
To force a page eject, you can use the following REXX comment statement:
/* EJECT */
When coding the special comment statements, be sure to enter the words REXX and
EJECT in uppercase letters, and do not place any other statements on these lines. The
special comment lines will not appear in the listing.
RXTDFUNC (Display Functions Command)

The RXTDFUNC exec can be used to display a list of all currently available function
packages and the functions within them. The RXTDFUNC command can be used in any
REXX environment. The syntax of the RXTDFUNC command is:
RXTDFUNC
This command takes no operands.
RXTDHOST (Display Host Command Environments

Command)
The RXTDHOST exec can be used to display a list of all currently available host
command environments. The RXTDHOST command can be used in any REXX
environment. The syntax of the RXTDHOST command is:
RXTDHOST

RXTDRXTE (Display REXXTOOLS Environment
Command)
The RXTDRXTE exec is no longer shipped with REXXTOOLS. Its function has been
replaced by the RXTENVIR command. See the Installation Guide for more information on
RXTENVIR.
RXTLJPQ (List Job Pack Queue Command)

The RXTLJPQ exec can be used to display the contents (module names only) of the
user's job pack queue area. This list shows all of the modules that are currently loaded in
the user's address space. The RXTLJPQ command can be used in any REXX
environment. The syntax of the RXTLJPQ command is:
RXTLJPQ
RXTLLLE (List Load List Elements Command)

The RXTLLLE exec can be used to display the names of modules that have been loaded
by the current MVS task. The RXTLLLE command can be used in any REXX
environment. The syntax of the RXTLLLE command is:
RXTLLLE
RXTTCBT (TCB Tree Command)

The RXTTCBT exec can be used to display the Task Control Block (TCB) tree for the
current address space. The RXTTCBT command can be used in any REXX environment.
The syntax of the RXTTCBT command is:
RXTTCBT

Appendix C: Messages
General JCL DD statement to allocate the SYSIN ddname,
then re-run the job.
RXT0000S REXXTOOLS AUTHCODE MISSING, RXT0002S SOURCE RECORDS TOO LONG TO

INVALID, OR EXPIRED BE COMPILED
Explanation: Either you have mis-entered the Explanation: The LRECL of the SYSIN data set is
authorization code, or your license to use the product greater than 32767.
(or feature) has expired.
Response: You cannot compile a program with
Response: Verify that you have entered the records this long. Try copying the program to a data
authorization code correctly. If the code is correct, set with a shorter LRECL, and re-compile.
contact Open Software Technologies.
RXT0003S SYSIN data set information error
RXT0001W YOUR LICENSE TO USE A
REXXTOOLS PRODUCT FEATURE WILL EXPIRE
IN count DAYS Explanation: The compiler is unable to determine
DCB characteristics for the SYSIN data set.
Explanation: A temporary authorization code for one

or more REXXTOOLS features is about to expire. Response: Make sure that DCB characteristics are
defined. If using a temporary data set, specify DCB
parameters. The compiler will read FB 80 and VB
Response: Contact Open Software Technologies, or 255 source data sets.
your distributor.
RXT0003S SYSIN dcbparm cannot be determined.
RXT0050S THE AUTHCODE IS NOT EXACTLY 12 Specify DCB parameters on DD statement or
HEX DIGITS ALLOCATE command
Explanation: RXTJCL was unable to use the Explanation: The compiler is unable to determine
authcode parameter you passed. DCB characteristics for the SYSIN data set.
Response: Verify that you have entered the Response: Make sure that DCB characteristics are
authorization code correctly. defined. If using a temporary data set, specify DCB
parameters. The compiler will read FB 80 and VB
RXT0051S IRXINIT FAILED WITH RC=rc 255 source data sets.
REASON=reason
RXT0004S ERROR READING SYSIN
Explanation: RXTJCL was unable to initialize a
REXX environment. Explanation: RXTCOMP was unable to read the
data set that is allocated to the SYSIN ddname.
Response: Try re-running the program. If the
problem persists, contact Open Software Response: Only DASD data sets, either FB 80 or VB
Technologies. 255 are supported. If your data set has these
characteristics, try re-compiling.
Batch Compiler RXT0005S NO RECORDS IN SYSIN

(RXTCOMP)
Explanation: The SYSIN data set is empty.
RXT0001S SYSIN allocation information error
Response: There are no records to compile. Make
sure you have specified the correct data set.
Explanation: You may not have allocated the SYSIN
ddname. This message is followed by more
diagnostic information. RXT0006S SYSIN RECFM=recfm is invalid. Only
FB and VB are supported
Response: If the problem is a missing SYSIN
allocation, use the TSO ALLOCATE command or
Appendix C: Messages 293

Explanation: The SYSIN data set is neither FB or Explanation: RXTCOMP encountered a keyword it
VB. did not recognize.
Response: You cannot compile this data set. Copy Response: Correct the error and rerun.
the program to an FB 80 or VB 255 data set and re-
compile it.
RXT0014S keyname KEYWORD VALUE IS NOT
TERMINATED WITH ')'
RXT0007S SOURCE FILE CONTAINS ONLY ZERO
LENGTH RECORDS
Explanation: The keyword named is missing a
closing parenthesis.
Explanation: The total length of all the records read
is zero.
Response: Correct the problem and rerun.
Response: Make sure you have specified the correct

RXT0015S NAME PARAMETER MUST BE
data set.
SPECIFIED
RXT0008S END OF SOURCE REACHED BEFORE

Explanation: The NAME parameter (option) is
END OF COMMENT
missing.
Explanation: The parser was in the middle of a

Response: You must supply a name for the CSECT.
comment when end-of-file was reached.
The name must be 1 to 8 characters long and the
first character must be alphabetic.
Response: Look for a missing */. Re-compile after
you have fixed the problem.
RXT0016S RXTCOMP FAILURE. RC=rc
REASON=reason
RXT0009S END OF SOURCE REACHED BEFORE
END OF LITERAL
Explanation: The batch compiler experienced some
type of internal error.
Explanation: The parser was in the middle of a
literal when end-of-file was reached.
Response: Report the problem to Open Software
Technologies.
Response: Look for a missing quote or double
quote. Re- compile the program after you have fixed
the problem. Run-Time Module
RXT0010S VERSION KEYWORD HAS NO VALUE (RXTRXPRE)
Explanation: The VERSION keyword was specified, RXT0101S ZERO LENGTH PROGRAM. pgm
but no value was supplied. CONTAINS NO SOURCE RECORDS.
Response: Correct the error and rerun. Explanation: One of the internal control blocks
indicated that the source is missing.
RXT0011S NAME KEYWORD HAS NO VALUE

Response: You have probably link-edited
RXTRXPRE with a program that was not created by
Explanation: The NAME keyword was specified but RXTCOMP.
no value was supplied.
RXT0102S PARMLIST TYPE INVALID. pgm
Response: Correct the error and rerun. INVOKED WITH AN INVALID PARMLIST
RXT0012S PAGESIZE KEYWORD HAS NO VALUE Explanation: The prefix module could not identify
the parmlist.
Explanation: The PAGESIZE keyword was specified
but no value was supplied. Response: Verify that the parmlist passed is a valid
OS parmlist.
Response: Correct the error and rerun.
RXT0110S VERSION MISMATCH. RXTRXPRE
RXT0013S KEYWORD keyword IS VERSION=vv.rr.mm. pgm VERSION=vv.rr.mm
UNRECOGNIZED

Explanation: The program, pgm, was compiled with RXT0206S keyname KEYWORD VALUE IS NOT
a version of RXTCOMP that is not supported by this TERMINATED WITH ')'
version of RXTRXPRE.
Explanation: A keyword that requires a value was
Response: This problem happens when an old found, but no value was supplied.
version of RXTRXPRE is link-edited with a program
compiled with a new version of RXTCOMP.
Response: Supply the value and rerun.
RXC TSO Command RXT0207S dsn IS PARTITIONED, BUT NO

MEMBER WAS GIVEN
RXT0200S SOURCE DSN NOT SPECIFIED. RXC

TERMINATING. Explanation: Member names must be supplied
when specifying the name of a partitioned data set.
Explanation: The RXC was not passed the source

data set name Response: Supply a member name and rerun.
Response: The source data set name is required. RXT0208S dsn IS SEQUENTIAL, BUT A MEMBER
Supply the name when you rerun RXC. WAS GIVEN
RXT0201S OBJECT KEYWORD HAS NO VALUE Explanation: A sequential data set cannot have a
member name.
Explanation: The OBJECT keyword was specified,

but no value was supplied. Response: Remove the member name and rerun.
Response: Supply a value and rerun. RXT0209S dsn ERROR. UNSUPPORTED DSORG
RXT0202S LIST KEYWORD HAS NO VALUE Explanation: The data set listed cannot be
processed. Only PO and PS organizations are
supported.
Explanation: The LIST keyword was specified, but
no value was supplied.
Response: Switch to a data set that is either PO or
PS.
Response: Supply a value and rerun.
RXT0210S RXC FAILURE. RC=rc
RXT0203S keyname KEYWORD HAS NO VALUE REASON=reason
Explanation: The keyname keyword was specified, Explanation: The RXC command experienced some
but no value was supplied. type of internal error.
Response: Supply a value and rerun. Response: Report the problem to Open Software
Technologies.
RXT0204S dsn ALLOCATION FAILED. RC=rc
Explanation: RXC failed in its attempt to allocate the

STORAGEX Function
specified data set. (RXTSTORX)
Response: Allocation messages should accompany RXT0240E STORAGEX ADDRESS IN ERROR AT
this message. Refer to these messages to determine xxxxxxxx
the cause of the problem.
Explanation: The address argument has an invalid

RXT0205S dsn ERROR. msg component.
Explanation: There is a problem with the specified Response: Correct the address argument and retry
data set. Processing is terminated. the function call.
Response: The msg field should indicate what the RXT0241E STORAGE AT 'xxxxxxxx'X COULD
problem is. NOT BE ACCESSED

Explanation: Either the storage at the indicated RXT0263E DIRECTORY dirname CANNOT BE
location has not been allocated or is fetch protected. LOCATED
Response: Correct the problem and retry the Explanation: A directory listed in the function
function call. package table cannot be located.
RXT0242E STORAGE AT 'xxxxxxxx'X COULD Response: Verify that your REXX parameters
NOT BE MODIFIED module's function package table is correct, and that
the directories listed in the parameters module are
accessible.
Explanation: The storage at the indicated location is
protected, and cannot be modified by a problem
state program in user key.
EXECSQL Command
Response: Correct the problem and retry the
function call. RXT0280S EXECSQL FAILURE. RC=rc.
REASON=reason
RXT0243E STORAGE MODIFICATION IS
CURRENTLY DISABLED Explanation: The EXECSQL command encountered
an internal error.
Explanation: The STORFL of the current
environment block indicates that use of the Response: Try re-running the command. If the
STORAGE function is invalid. STORAGEX interprets problem persists. Contact your Open Software
this bit setting as disallowing storage modification representative.
only.
RXT0281S RXSUBCOM failed with RC=rc
Response: Use another REXX environment or do REASON=reason. EXECSQL Terminating
not attempt to modify storage.
Explanation: The EXECSQL command was unable
REXX Module Load

to dynamically install the RXTASQL2 host command
environment.
(RXTCRRLD)
Response: Usually other messages will accompany
this message. Ensure that the RXTASQL2 module
RXT0260E MODULE module IS NOT AMODE 31 can be located by the MVS LOAD macro.
Explanation: Modules that are to be LINKed to by RXT0282S DB2INFO call failed. RC=rc
REXX must run AMODE(31).
Explanation: The EXECSQL was unable to
Response: Re-linkedit the indicated module. determine DB2 default values.
RXT0261E MODULE module IS NOT REENTRANT Response: This probably means that the DB2 load
library is unavailable to your program. Make sure that
Explanation: Modules that are to be LINKed to by an MVS LOAD macro instruction can locate the
REXX must be reentrant in order to not be reloaded DSNHDECP module.
with each LINK.
RXT0283S DSNALI OPEN failed with RC=rc.
Response: Re-link-edit the indicated module. EXECSQL Terminating.
Explanation: The EXECSQL command was unable

RXFUNC (RXTFUNC) to open the RXTCS plan.
RXT0262E DIRECTORY dirname CANNOT BE Response: Verify that you have bound the RXTCS
MODIFIED plan and that the DB2 subsystem is active
Explanation: The indicated directory is in protected RXT0284S ADDRESS OSTSQL failed with RC=rc.
storage. EXECSQL Terminating.
Response: You cannot modify the directory. Explanation: The SQL statement that you passed to
EXECSQL encountered some sort of problem.

Response: Correct the SQL statement and rerun the chapters. Specifically, spanned records are not
command. supported.
QSAM, BPAM, and Response: Do not open the failing data set.
VSAM Interfaces RXT0306E DATASET BLKSIZE IS INVALID
RXT0300E DDNAME ddname IS ALREADY IN USE Explanation: BLKSIZE cannot exceed 32760. For
variable length records the block size must be at
least 8, and must always be at least 4 bytes longer
Explanation: This ddname has already been than the LRECL.
opened.
Response: Correct the block size and retry the

Response: You must close a ddname before you operation.
can reopen it.
RXT0307E DATASET LRECL IS INVALID

RXT0301E DDNAME ddname IS NOT IN USE
Explanation: LRECL must be greater than zero and

Explanation: This ddname has not yet been opened. less than or equal to the block size. If RECFM=F is
used, LRECL must be identical to BLKSIZE. If
Response: Open the ddname before you attempt RECFM=FB is used, BLKSIZE must be an even
any other VSAM operation. multiple of LRECL. If variable length records are
used, the LRECL must be at least 4.
RXT0302E INVALID OPTION SPECIFIED

Response: Correct the LRECL or BLKSIZE
(whichever is appropriate) and retry the operation.
Explanation: The MACRF option you specified was
invalid.
RXT0308E GET IS INVALID IN THIS CONTEXT.
CHECK OPEN OPTIONS
Response: Correct the options argument and retry
the open.
Explanation: The GET function has been used with
incompatible open options.
RXT0303E synadmsg
Response: Verify that the file is open for input or

Explanation: The SYNAD exit was invoked for an update. GET cannot be used with a file that is open
I/O operation. The text of the message describes the for output.
operation attempted.
RXT0309E RETRIEVED RECORD'S LRECL IS

Response: This message is caused by various INVALID
problems. If reading a sequential file, verify that the
file is not empty. If you have specified DCB
parameters for an existing file, verify that these are Explanation: The detected logical record length is
consistent with the information in the VTOC. Use the either zero, longer than the indicated LRECL
TSO LISTD command to obtain data set DCB parameter, or longer than the block size.
characteristics.
Response: This could happen if you read an empty
RXT0304E DATASET DSORG IS INVALID FOR sequential data set, or if you specify DCB
SELECTED ACCESS METHOD characteristics that are incompatible with the
characteristics defined in the VTOC. Correct the
problem and re-run the job.
Explanation: You have tried to open a file using the
wrong access method.
RXT0310E FINDM MUST BE PERFORMED
BEFORE GET
Response: Verify the access method argument of
the OPEN function. QSAM and BPAM can be used
with sequential files and PDSs. VSAM can be used Explanation: A FINDM function call did not precede
with VSAM files only. the failing GET.
RXT0305E DATASET RECFM IS NOT Response: When using BPAM, you must establish
SUPPORTED position using the FINDM function prior to reading a
member. Correct the problem and re-run the job.
Explanation: The BPAM and QSAM interfaces

support only those RECFMs listed in their respective

RXT0311E RETRIEVED BLOCK'S LENGTH IS RXT0316E STOWM IS INVALID IN THIS
INVALID CONTEXT. CHECK OPEN OPTIONS
Explanation: The indicated length of the retrieved Explanation: STOWM was used with a file that was
block was either zero, or longer than the value given opened with incompatible options.
by BLKSIZE parameter.
Response: STOWM may be used only with files that
Response: This could happen if you read an empty are open for output or update.
sequential data set, or if you specify DCB
characteristics that are incompatible with the
RXT0317E FINDM IS INVALID IN THIS CONTEXT.
characteristics defined in the VTOC. Correct the
CHECK OPEN OPTIONS
problem and re-run the job.
Explanation: FINDM was used with a file that was

RXT0312E CURRENT RECORD LIES OUTSIDE
opened with incompatible options.
THE RETRIEVED BLOCK
Response: FINDM may be used only with files that

Explanation: The retrieved record is not entirely
contained within the current block. are open for input or update.
Response: This could be caused by an invalid

record descriptor word (RDW). Dump the file to
Static SQL
determine the cause of the problem. If no problem is
found, call OST technical support. RXT0500W varname HAS BEEN TRUNCATED
RXT0313E PUT IS INVALID IN THIS CONTEXT. Explanation: The variable's data has been truncated
CHECK OPEN OPTIONS to fit its declared length. Execution continues.
Explanation: A PUT was issued for a file that was Response: Either change the declaration, or ensure
opened with incompatible options. that the data does not exceed the declared length.
Response: PUT may be used only with files that are RXT0501S varname CONVERSION ERROR
open for output or update. It may not be used with a
file that is open for input. Correct the open options
and rerun the job. Explanation: The variable's data did not fit the
declared type.
RXT0314E NO RECORD TO UPDATE. A GET

MUST PRECEDE A PUT FOR UPDATE Response: Either change the declaration, or ensure
that the data is of the proper type.
Explanation: A PUT for update was executed

without a preceding GET for update. Dynamic SQL
Response: A record must be read with GET prior to
RXT0600I sqlcommand
PUTting it back. You must do this even if you plan to
ignore the read record. Correct the problem and re-
run the job. Explanation: This is an informational message that
shows the current SQL command. Usually the
sqlcommand displayed is the "processed string", not
RXT0315E THIS OPERATION IS INCOMPATIBLE
the input command string. However, in some cases
WITH THE CURRENT ACCESS METHOD
the unprocessed command string is displayed.
Explanation: A function has been used that is not

Response: If this message is accompanied by error
proper for the access method in use.
messages, correct the problem and rerun the exec.
Response: This problem has several forms. You

RXT0601W DECLARE STATEMENT IS
may not, for example, use the FINDM function with a
UNSUPPORTED
file that was opened using QSAM. If you intended to
use another access method, correct the access
method argument of the OPEN function, and retry Explanation: The DECLARE STATEMENT
the operation. command is not supported.
Response: Remove the DECLARE STATEMENT

command.

RXT0602W DECLARE STATEMENT IS RXT0608E DECLARE STATEMENT SYNTAX
UNRECOGNIZED ERROR
Explanation: The DECLARE type is not recognized. Explanation: The DECLARE command cannot be
used due to syntax errors.
Response: Only DECLARE CURSOR, DECLARE
VARIABLE, and DECLARE TABLE, are supported. Response: Correct any errors and rerun the
Check for spelling or syntax errors. program.
RXT0603E CURSOR NAME csrname IS INVALID RXT0609E FREE STATEMENT IS UNUSABLE

OR RESERVED
Explanation: The FREE command is in error.
Explanation: The cursor name cannot be used.
Response: Check for syntax errors, correct these,
Response: Cursor names must be valid REXX and rerun the program.
variable symbols 1 to 8 bytes long. $RXTCSR$ is a
reserved name.
RXT0610E FREE STATEMENT IS
UNRECOGNIZED
RXT0604E MAXIMUM NUMBER OF DECLARED
CURSORS EXCEEDED
Explanation: The FREE type is unrecognized.
Explanation: More cursors were declared than are

Response: Only FREE CURSOR and FREE
available in the pool of static cursors.
VARIABLE commands are supported. Check for
spelling errors.
Response: You must free a cursor in order to
declare another one.
RXT0611E CURSOR NAME csrname IS OPEN
RXT0605E CUSOR NAME csrname IS ALREADY

Explanation: The operation on the cursor cannot be
IN USE
performed because the cursor is open.
Explanation: You have tried to re-declare a cursor

Response: Close the cursor before attempting the
that has already been declared.
operation.
Response: Free the cursor before trying to re-

RXT0612E CURSOR NAME csrname NOT FOUND
declare it.
Explanation: You have attempted to use a cursor

RXT0606E DECLARE CURSOR STATEMENT IS
before you have declared it.
UNUSABLE
Response: Use the DECLARE CURSOR command

Explanation: The DECLARE CURSOR cannot be
to declare the cursor before using its name. If you
used.
thought you did, check for logic or spelling errors.
Response: Check for syntax errors, and rerun the

RXT0613E VARIABLE NAME varname NOT
program.
FOUND
RXT0607E VARIABLE NAME varname IS INVALID

Explanation: You have attempted an operation on a
variable that is not declared.
Explanation: The host variable name not a valid
REXX variable name.
Response: You either did not declare the variable,
or you have already freed it.
Response: Check for coding errors. Refer to the
REXX Reference for information regarding valid
RXT0614E NO VARIABLES FOR PROGRAM
REXX variable names. Note though, that the "?"
progname
cannot be used, even though it is permitted in REXX
symbols.
Explanation: You have attempted to free variables
for the program, but no variables were found.
Response: Check to make sure that you have not

already freed the variables.

RXT0615I db2message RXT0622E NO. OF INTO VARS DOES NOT
MATCH NO. OF SELECTED COLS
Explanation: A non-zero SQLCODE has been
returned by DB2. The message explains the Explanation: The INTO clause of a SELECT or
problem. FETCH statement does not have the same number
of variables as there are columns to be retrieved.
Response: Refer to DB2 Messages and Codes,
SC26-4379 for problem resolution. Response: Correct the problem and retry the
request.
RXT0616E SQL STATEMENT STRING IS EMPTY
RXT0623E CONNECT STATEMENT SYNTAX
ERROR
Explanation: The host command was zero-length or
all blanks.
Explanation: The CONNECT statement is not
useable due to syntax errors.
Response: You must pass a non-blank host
command expression. Use the TRACE C REXX
instruction to trace host command execution. Response: Correct the problem and retry the
request.
RXT0617E token IS NOT A RECOGNIZED SQL
VERB RXT0624E SET STATEMENT SYNTAX ERROR
Explanation: The SQL command could not be Explanation: The SET statement is not useable due
executed because the first word was not a to syntax errors.
recognized SQL command.
Response: Check for spelling errors in your host request.
command.
RXT0625E DESCRIBE STATEMENT SYNTAX
RXT0618E token IS NOT A RECOGNIZED OPTION ERROR
Explanation: The token in the OPTIONS command Explanation: The DESCRIBE statement is not
is not a valid option. useable due to syntax errors.
Response: Check for spelling errors. Response: Correct the problem and retry the
request.
RXT0619E NO OPTIONS SPECIFIED
RXT0626E TABLE/VIEW NAME IS TOO LONG
Explanation: No options followed the OPTIONS
verb. Explanation: The table or view name is longer than
254 bytes.
Response: You must code at least one option.
request.
RXT0620E OPTIONS STATEMENT SYNTAX
ERROR
RXT0627E VARIABLE NAME varname IS INVALID
OR TOO LONG
Explanation: The OPTIONS command could not be
executed due to syntax errors.
Explanation: The variable name is not a valid REXX
variable name.
Response: Check for spelling errors. Also note that
options must be separated by one or more blanks.
request. Refer to REXX Reference for the definition
RXT0621E DB2 DID NOT COMPLETE SQLCA
of valid variable names.
Explanation: A DB2 request did not result in the

RXT0628E CLOSE STATEMENT SYNTAX ERROR
SQLCA being filled in.
Explanation: The CLOSE statement is not usable

Response: Verify that you connected to a DB2
due to syntax errors.
subsystem prior to executing the command.

Response: Correct the problem and retry the RXT0635E END OF STATEMENT FOUND BEFORE
request. END OF LITERAL
RXT0629E CURSOR NAME csrname HAS BEEN Explanation: The parser ran out of tokens before a
USED BEFORE IT HAS BEEN DECLARED closing quote mark was found.
Explanation: The cursor that has been OPENed, Response: Correct the problem and retry the
FETCHed, or CLOSEd, or used in a WHERE request.
CURRENT OF clause has not been declared.
RXT0636E STATEMENT CONTAINS A TOKEN
Response: Execute a DECLARE CURSOR LARGER THAN 250 BYTES
statement prior to using the csrname in any other
statement.
Explanation: The parser encountered a token larger
than the maximum.
RXT0630E OPEN STATEMENT SYNTAX ERROR
Response: Neither DB2 nor REXX require tokens
Explanation: The OPEN statement is not useable larger than 250 bytes. Correct the problem and retry
due to syntax errors. the request. Check for missing blank delimiters.
Response: Correct the problem and retry the RXT0637E 'EXEC SQL' OR TERMINATING
request. SEMICOLON SYNTAX ERROR
RXT0631E FETCH STATEMENT SYNTAX ERROR Explanation: The EXEC SQL or terminating
semicolon were mis-coded.
Explanation: The FETCH statement is not useable
due to syntax errors. Response: Check for spelling and punctuation
errors. Correct the problem and retry the request.
request. RXT0638E INTO CLAUSE SYNTAX ERROR
RXT0632E BEGIN/END DECLARE SECTION Explanation: The INTO clause could not be
SYNTAX ERROR processed.
Explanation: The BEGIN or END DECLARE Response: Verify that your host variables are all
SECTION statement is not useable due to syntax prefixed with colons, and that host variable
errors. expression are separated by commas.
Response: Correct the problem and retry the RXT0639E varname IS AN INVALID DATA
request. VARIABLE NAME
RXT0633E STATEMENT CONTAINED AN INVALID Explanation: The variable named in this message is
OUTPUT VARIABLE not a valid REXX variable name.
Explanation: One of the output variables in the Response: Correct the problem and retry the
statement was not a valid REXX variable name. request. Refer to REXX Reference for the definition
of valid variable names.
request. Refer to REXX Reference for the definition RXT0640E varname IS AN INVALID INDICATOR
of valid variable names. VARIABLE NAME
RXT0634E STATEMENT CONTAINS A QUESTION Explanation: The variable named in this message is
MARK. QUESTION MARKS ARE NOT not a valid REXX variable name.
PERMITTED.
Explanation: A question mark was found in the host request. Refer to REXX Reference for the definition
command expression. of valid variable names.
Response: Question marks are not permitted and

must be removed.

RXT0641E INPUT INDICATOR VARIABLE
varname CONTAINS A VALUE THAT CANNOT BE Dynamic Allocation
CONVERTED TO A SMALLINT NUMBER
RXT0800E token IS NOT A RECOGNIZED
Explanation: The indicator variable contains a non- ALLOCATE KEYWORD
numeric value.
Explanation: The token listed is not a valid
Response: Use TRACE I to find the problem. ALLOCATE or FREE keyword.
Indicator variables must contain numeric values
between -32768 and +32767. Response: Check for spelling errors, errors in
abbreviation, and punctuation errors.
RXT0642E IRXEXCOM DETECTED INVALID
VARIABLE NAME RXT0801E A STATUS OF 'NEW' IS
INCOMPATIBLE WITH A DATA SET
Explanation: The REXX variable access routine CONCATENATION REQUEST
indicated that a variable name in the request is
invalid. Explanation: The request tried to allocate more than
one data set with a status of NEW.
request. Refer to REXX Reference for the definition Response: You can only allocate NEW data sets
of valid variable names. one at a time.
RXT0643E A COLON WAS NOT IMMEDIATELY RXT0800E keyword KEYWORD SYNTAX ERROR
FOLLOWED BY A VARIABLE NAME
Explanation: The keyword listed was not followed by

Explanation: A colon that was not immediately a correct value expression.
followed by another token was found.
Response: Keyword values must be enclosed in

Response: You may have coded a blank between parentheses. In addition, each keyword has specific
the colon and the variable name. Correct the problem value coding requirements.
and retry the request.
RXT0644E VARIABLE varname CONTAINS A Internal

VALUE THAT IS MORE THAN 32767 BYTES
LONG
RXT0900S REXXTOOLS STACK OVERFLOW
Explanation: A value larger than the maximum

accepted by DB2 was found. Explanation: The product's storage stack pointer
has exceeded one of its bounds.
Response: DB2 will not accept a value larger than

this. Correct the problem and retry the request. Response: Contact Open Software Technologies.
RXT0645E VARIABLE varname COULD NOT BE RXT0901S REXXTOOLS STACK UNDERFLOW

CONVERTED TO TYPE db2type
Explanation: The product's storage stack pointer
Explanation: The variable listed could not be has exceeded one of its bounds.
converted from the REXX printable data type to the
target DB2 data type. Response: Contact Open Software Technologies.
Response: Usually this happens when a variable RXT9002S INVALID ANCHOR BLOCK
declaration is missing. Check for spelling errors.
Explanation: The RXTANCHR module has been

RXT0646E RELEASE STATEMENT SYNTAX corrupted.
ERROR
Response: Try logging off and logging back on. If

Explanation: The RELEASE statement could not be that does not correct the problem, obtain a dump of
used due to syntax errors. the RXTANCHR module, and contact Open Software
Technologies.
request.

RXTWTR RXT1351S REXX PROGRAM NAME IS INVALID
Explanation: The REXX program name is

OST0002S PROGRAM NOT APF AUTHORIZED syntactically invalid.
Explanation: The RXTWTR program is not APF- Response: REXX program names must be valid
authorized and cannot function. Execution MVS PDS member names.
terminates.
RXT1352S FATAL IRXEXEC ERROR
Response: RXTWTR is link-edited AC=1, but must
be placed in an APF-authorized library to complete
system authorization requirements. Verify that the Explanation: The REXX program could not be
REXXTOOLS load library is in the APF list or is in the executed due to some type of internal REXX error.
link list with the LNKAUTH=LNKLST parameter
specified in the IEASYSxx member of Response: Try rerunning the transaction. If the
SYS1.PARMLIB. problem persists, contact Open Software
Technologies.
RXTAMT (APPC/MVS RXT1353S CANNOT LOAD REXX PROGRAM

Transaction Program)
Explanation: The REXX program could not be
loaded.
RXT1350S REXX PROGRAM NAME IS MISSING
Response: Make sure you have coded the REXX

Explanation: The REXX program cannot be
program name correctly (check spelling). Also verify
executed.
that the REXX program can be found in the
SYSEXEC data set concatenation.
Response: You must specify the name of the REXX
program on the PARM= JCL parameter. The syntax
RXT1354S CANNOT INIT REXX ENVIRONMENT
for this parameter is identical to the one used for
IRXJCL (see the REXX Reference).
Explanation: The IRXINIT routine could not initialize
a REXX environment.
Response: Try rerunning the transaction. If the

problem persists, contact Open Software
Technologies.

Glossary
The following list is compilation of some of the terms you will find used in this document.
If you do not find the term you are looking for, the best reference to turn to is the IBM
publication, Dictionary of Computing, SC20-1699. You may also want to check the
glossaries of the publications listed in "Related Publications."
3270 Data Stream

A protocol for communicating with 3270 display devices.
ACB
Access method Control Block. An area in main storage, used by VSAM and VTAM. In the
case of VSAM the ACB is used to describe the data set being accessed, and certain
processing options.
bind
The process by which the Database Request Module, produced by the pre-compiler is
translated to an application plan.
BLKSIZE
Block Size. The length, in bytes, of a physical record.
BPAM
Basic Partitioned Access Method. An access method for reading members of partitioned
data sets.
CAF
Call Attachment Facility. Facilitates access to DB2 from TSO and batch address spaces.
clause
A part of an SQL statement.
column
In a DB2 table, a specific type of data that is named and whose values are contained in
zero or more rows.
commit
A DB2 operation that terminates a unit of work and makes any changes that have been
made permanent.
control area
(CA) A grouping of control intervals, used by VSAM for managing the space allocated to
a VSAM data set.
control interval
(CI) a grouping of records. The minimum number of records transmitted between main
storage and auxiliary storage in a single operation.
cursor
A DB2 control structure used to retrieve rows from a result set.
DCB
Data Control Block. This control block contains information pertaining to the structure of
records and blocks a file.
Glossary 305
ddname
Data Definition name. The name associated with a data set by a JCL DD statement or
the TSO allocate command.
dequeue
Relinquishing a reservation for a system resource.
direct access
In VSAM, the accessing of individual records directly. Using direct access, the records
preceding the record you want are not read (or written).
DFP
Data Facility Products. A group of IBM supplied access methods and utilities.
DFSMS
Data Facility System Managed Storage. A group of IBM- supplied access methods and
utilities. DFSMS supercedes DFP.
DFSORT
A DFP program for sorting data sets into user specified order.
enqueue
A reservation for a system resource.
ESDS
Entry-sequenced Data Set. One of the data set organizations supported by VSAM. The
data is organized by the order it is entered.
EXEC
(1) a TSO command for running REXX programs. (2) A REXX program.
full-screen mode
A method for displaying information on a terminal where the unit of display is the entire
display surface.
function
A subprogram called by a REXX exec that returns a value. A function call in an
expression can be thought of as being replaced by its value.
host variable
A DB2 term for a program variable in an application program. Host variables are used in
SQL commands.
KSDS
Key-sequenced Data Set. One of the data set organizations supported by VSAM. The
data is organized by the collating sequence of the key field.
LDS
Linear Data Set. One of the VSAM data set organizations. Supports the MVS Data-In-
Virtual (DIV) facility.
line-mode
A way of presenting information on a terminal where the unit of display is a single line.

LRECL
Logical Record Length.
orders
Hexadecimal codes in 3270 data streams which direct the control unit's actions.
packed decimal
A binary-encoded format for decimal numbers in the 360/370/390 hardware architectures.
Each decimal digit occupies a half byte (nibble). The sign of the number is in the right-
most nibble.
PDS
Partitioned Data Set. A data set organization for holding collections of related records in
groups called "members".
PDSE
Partitioned Data Set Extended. The PDSE is identical to the PDS organization, but has
additional sharing and space management capabilities.
predicate
In SQL, a comparison operation that is used in a query.
QSAM
Queued Sequential Access Method. A file access method for reading, writing and
updating sequential data sets and partitioned data set members.
REXX
Restructured EXtended eXecutor. A programming language for SAA environments.
rollback
A DB2 operation that terminates a unit of work and backs out all changes that have been
made.
row
In a DB2 table, a sequence of values, one for each column in the table.
RPL
Request Parameter List. An area in main storage which describes a request for services
to VSAM.
RRDS
Relative Record Data Set. One of the organizations supported by VSAM. The data is
organized by record number.
SAA
Systems Application Architecture. A set of software interfaces for building portable
applications.
SAF
System Authorization Facility. An MVS facility for routing authorization requests to RACF
or equivalent system security packages.
SQL
Structured Query Language. The collection of commands used to create, modify, query,
and delete DB2 objects.
Glossary 307
stem
(1) A type of REXX program variable that permits the construction of pseudo-array data
structures; (2) the part of a stem variable that lies to the left of the first dot (.). The simple
symbol which makes up the stem is never replaced by its value.
table
A DB2 object that contains data in row/column format.
thread
A DB2 structure that describes the connection between an MVS task and the DB2
address space.
TTR
Track Track Record. An address (3 bytes in length) that describes a location within a file
relative to the beginning of the file. The distance is given in tracks and records.
unit of work
In DB2, a recoverable sequence of commands within an application.
virtual storage
An operating system technique for providing more addressable storage to programs than
is actually available on the hardware.
VSAM
Virtual Storage Access Method. VSAM data sets may be accessed sequentially and
randomly.
VRDS
Variable Length Relative Record Data set.
Wild Card
A character in a pattern that may match against any character in a target string. Some
wild card characters may match against many target string characters.

REXXTOOLS V7 Basic Services

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

REXXTOOLS V7 Basic Services

Загружено:

Авторское право:

Доступные форматы

REXXTOOLS/MVS TM

Basic Services Manual

Open Software Technologies, Inc.

IBM, MVS/ESA, MVS/XA, MVS/DFPR, NetView, CICS, DB2, MVS/SP, DFS/MVS,

© Copyright 2005 by Open Software Technologies, Inc. All rights reserved.

P.O. Box 162652

Phone: (407) 788-7173

REXXTOOLS/MVS Basic Services User’s Guide

REXXTOOLS/MVS Basic Services User’s Guide

REXXTOOLS/MVS Basic Services User’s Guide

REXXTOOLS/MVS Basic Services User’s Guide

What REXXTOOLS/MVS Basic Services Is

• access to VSAM, sequential, and partitioned data sets.

• access to MVS/ESA and OS/390 operating system services.

• access to SMS and DFP information.

• general enhancements to REXX data conversion, string manipulation, array handling,

In addition, REXXTOOLS/MVS Basic Services includes a pseudo-compiler for converting

REXX and REXXTOOLS/MVS can be used to perform many common programming

Create REXXTOOLS can be used in client/server environments such

Create System REXXTOOLS is used in conjunction with MVS automation

2 REXXTOOLS/MVS Basic Services User’s Guide

• REXXTOOLS/MVS General Information

REXXTOOLS/MVS documentation is available in a variety of formats, electronic and

Publication Title Order Number

REXXTOOLS/MVS Basic Services provides numerous interfaces to MVS system

Publication Title Order Number

Publication Title Order Number

MVS/Quick-Ref is a trademark of Chicago-Soft, Ltd.

The following names are trademarks of Computer Associates:

ACF2, TOP Secret, OPS/MVS

AutoOperator is a trademark of Boole and Babbage.

AF-Operator is a trademark of Candle Corporation.

TCPaccess is a trademark of Interlink Computer Sciences, Inc.

What’s New in Version 7 Release 1

4 REXXTOOLS/MVS Basic Services User’s Guide

Dynamic and Static SQL Services:

The following improvements have been made:

1. The REXXTOOLS load library is no longer shipped. 2 jobs, RXTALLOC and

2. The restriction of 20 authcodes per copy of REXXTOOLS has been removed. It is

QSAM: Queued Sequential Access Method support has been added.

LISTA lists current allocation information, including DSNAMEs, DSORGs,

IDCAMS: A new host command environment is supplied as well as 2 IDCAMS-based

6 REXXTOOLS/MVS Basic Services User’s Guide

MVS Services: Improvements have been made to the following functions:

ENQ More accurate reporting of return and reason codes.

DEQ More accurate reporting of return and reason codes.

Static SQL: The following improvements have been made:

3. High-level assembler support has been added.

Architectural Improvements: The following improvements have been made:

REXXTOOLS documentation has been reorganized into 4 publications:

1. REXXTOOLS/MVS General Information

VSAM: The following improvements have been made:

Dynamic Allocation: The following improvements have been made:

2. The ALLOCATE command now supports BLKSIZE(0). This permits SMS

General REXX Extensions: Several new functions have been added:

D2F converts REXX decimal numbers to binary floating point numbers.

F2D converts binary floating point numbers to REXX decimal numbers.

D2PIC converts REXX decimal numbers to COBOL-style numeric picture

PIC2D converts numbers containing currency symbols and other editing

8 REXXTOOLS/MVS Basic Services User’s Guide

Dynamic SQL: The following improvements have been made:

5. Documentation for the "compatibility" interface has been moved to an appendix.

Static SQL: The following improvements have been made: