rexxtools v7 basic services

REXXTOOLS/MVSTM

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: [email protected] 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 What's New in Version 2 Release 1 .............................................................................................. 12 What's New in Version 1 Release 2 .............................................................................................. 13 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 Reading, Writing, and Updating Records ...................................................................................... 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 Service Descriptions...................................................................................................................... 52

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 Reading, Writing, and Updating Records ...................................................................................... 73

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 Service Descriptions...................................................................................................................... 83

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 Service Descriptions.................................................................................................................... 123

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

Service Descriptions.................................................................................................................... 144 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 Service Descriptions.................................................................................................................... 166

SBA (Set Buffer Address) ................................................................................................... 166 TGET................................................................................................................................... 167 TPUT................................................................................................................................... 170

General REXX Extensions ........................................................................................................ 175 Service Descriptions.................................................................................................................... 176

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 Service Descriptions.................................................................................................................... 232

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

Service Descriptions.................................................................................................................... 264 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 Applications.

REXX and REXXTOOLS are fully integrated into ISPF. REXXTOOLS lets you build applications to display and share VSAM and DB2-hosted data in hours instead of weeks.

Create Client/Server Applications.

REXXTOOLS can be used in client/server environments such as APPC/MVS, IBM TCP/IP, and DB2's Distributed and Remote Units of Work.

Create Web-based Applications.

REXXTOOLS has been tested in several popular MVS web servers, including IBM's HTTP Server.

Create Custom Utilities.

Many customers have found that REXXTOOLS can be used to 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 Automation Applications.

REXXTOOLS is used in conjunction with MVS automation packages to develop robust applications. Automated trouble ticketing, exception logging, and data sharing applications have been developed using REXXTOOLS.

Write Batch Reports.

Using the REXX batch interface, IRXJCL, you can quickly 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 Reports.

Often the source to older report writing programs has been lost 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 one format to another.

REXXTOOLS contains many conversion functions and access methods that allow you to create custom conversion utilities. For example, you can use REXXTOOLS to convert 2 byte packed date fields to 4 byte packed fields, or to binary.

REXXTOOLS/MVS Basic Services User’s Guide 2

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:

Publication Title Order Number 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:

Publication Title Order Number 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' //STEPLIB DD DISP=SHR,DSN=REXXTOOL.LOAD //SYSEXEC DD DISP=SHR,DSN=TSOUSER.EXEC //SYSTSPRT DD SYSOUT=* //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' //STEPLIB DD DISP=SHR,DSN=REXXTOOL.LOAD //SYSEXEC DD DISP=SHR,DSN=TSOUSER.EXEC //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:

[email protected]

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 timerec = get('indd') 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 say 'OPEN failed with RC='rc 'REASON='reason 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 record = get('iodd') 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 say 'CLOSE failed with RC='rc 'REASON='reason exit 8 end

GET (QSAM)

Syntax:

GET(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:

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.


Returned Information:

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) record = get('indd') 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.

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. 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 operation was completed successfully.

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 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. You should treat these variables as "read only" and make no attempt to modify any of them. The variables are:

RC Contains the QSAM PUT return code. An RC of zero means the operation was completed successfully.

REASON Contains the QSAM PUT reason code. Examples:

1. Sequentially retrieve and update all of a data set's records:

record = get('iodd') 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 do while record <> '' call put 'moddd', record say 'Enter a new record:'; parse pull 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.

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 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 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 BPAM 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.


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 say 'OPEN failed with RC='rc 'REASON='reason exit 8 end if findm('indd','timecard') <> 0 then do say 'TIMECARD member not found.' exit 8 end timerec = get('indd') do while rc = 0 parse var timerec lname +10 fname +10 timein +8 timeout +8 timerec = get('indd') 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 do while record <> '' call put 'outdd', 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' call open 'bpam', 'outdd', 'output' /* Next, copy the existing records */ call findm 'indd', 'member1' record = get('indd') do while rc = 0 call put 'outdd', record record = get('indd') 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 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 BPAM 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('bpam','indd','input') "RC="rc "REASON="reason

Unless otherwise noted, the values for RC and REASON are taken directly from the 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 functions are all decimal (not hexadecimal) values.

BPAM Functions 51


The sections that follow describe the syntax and operation of the BPAM-related functions.

CLOSE (BPAM)

Syntax:

CLOSE(ddname) Arguments:


Module Name:



CLOSE completes I/O operations, updates VTOC information, and disconnects your program from the data set. Returned Information:

The CLOSE function returns the BPAM CLOSE macro return code. If you CALL the CLOSE function, the returned value is contained in the RESULT special variable.


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:


if close('indd') = 0 then say 'Data set closed.' 2. Close a data set using CALL:

call close 'outdd' if rc <> 0 then do say 'CLOSE failed with RC='rc 'REASON='reason 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 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 FIND or BLDL return code. An RC of zero means the operation was completed successfully.

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 /* read the member */ 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 /* read the member */ 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 /* read the member */ end


GET (BPAM)

Syntax:

GET(ddname) Arguments:


Module Name:



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.



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 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' 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) record = get('indd') 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. This argument must be coded as shown.

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. If you try to open a ddname that is already open, the request is ignored and no error indication is given.


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:


All REXX/MVS environments.


Service Description:

OPEN is used to "connect" your program to a data set. You must open a data set before 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

operation was completed successfully. 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:



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.

If you are using PUT to update a record, you must first retrieve the record using the GET 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 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. You should treat these variables as "read only" and make no attempt to modify any of them. The variables are:

RC Contains the BPAM PUT return code. An RC of zero means the operation was completed successfully.

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 open 'bpam', 'iodd', 'update' call findm 'iodd', 'payroll' record = get('iodd') 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. Create a new member:

"alloc fi(outdd) da(mypds.data) old" call open 'bpam', 'outdd', 'output' say 'Enter a new record:'; parse pull record do while record <> '' call put 'outdd', record say 'Enter a new record:'; parse pull record 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 open 'bpam', 'outdd', 'output' call put 'outdd', 'this is a record' call stowm 'outdd', 'earl' call close 'outdd'

2. Create an alias for a member:

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


3. Rename a member:

call open 'bpam', 'iodd', 'update' 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):

call open 'bpam', 'iodd', 'update' 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 open 'bpam', 'outdd', 'output' 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.

call open 'bpam', 'outdd', 'output' 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 open 'bpam', 'outdd', 'output' 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.

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. 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 associated with the task under which the OPEN function was executed. The information

VSAM Functions 69

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 VSAM 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. 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:

/* Allocate and open the indd file */ 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 /* Close and free the indd file */


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:

/* Allocate and open the indd file */ call get 'indd', 0, '(adr,dir)' /* Close and free the indd file */

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' //STEPLIB DD DISP=SHR,DSN=REXXTOOL.LOAD //SYSEXEC DD DISP=SHR,DSN=USER.VSAM.EXEC //SYSTSPRT DD SYSOUT=* //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 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 VSAM functions return the return code as their value. For example, the following code will display the 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 Unless otherwise noted, the values for RC and REASON are taken directly from the 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 functions are all decimal (not hexadecimal) values.



The sections that follow describe the syntax and operation of the VSAM-related functions.

CLOSE (VSAM)

Syntax:

CLOSE(ddname[,'T']) Arguments:


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:



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 CLOSE function, the returned value is contained in the RESULT special variable.

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:


if close('indd') = 0 then say 'Data set closed.' 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. Returned Information:

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 */ call put 'iodd', newrec 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. Returned Information:

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 completed successfully.

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:



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.



After completion of a GET 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 GET return code. Zero means the operation was completed successfully.

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. This argument must be coded as shown.

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.


options a character string describing the processing options for the data set. You may specify the options in any order. If multiple options are coded, they must be enclosed in parentheses and separated by commas. The 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:



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.

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 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. 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 OPEN return code. Zero means the operation was completed successfully.

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.

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" 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" . 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.



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.


The POINT function returns the VSAM POINT macro return code. If you CALL the POINT function, the returned value is contained in the RESULT special variable.

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 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 POINT return code. Zero means the operation was completed successfully.

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.

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" 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 option 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:





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.

If you are using PUT to update a record, you must first retrieve the record using the GET function (with the UPD option). All other PUT requests are treated as insertion requests.


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 keyin 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) 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

completed successfully. 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 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

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 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 VERIFY return code. Zero means the operation was completed successfully.

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 RACROUTE UCBSCAN

MVS/ESA Authorized Assembler Services Reference (various volumes)

MVS/ESA Authorized Assembler Services Guide

DEVTYPE IGWASMS LOCATE OBTAIN TRKCALC

MVS/DFP System Programming Reference

DFSMS/MVS Using Advanced Services Data Sets

CLOSE OPEN

MVS/DFP Macro Instructions for Data Sets

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):

Word Data Item Description 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.

If a data item is unavailable, the interface supplies a single question mark (?) as a 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:

Word Data Item Description 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.

If a data item is unavailable, the interface supplies a single question mark (?) as a 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.

Word Data Item Description 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.

If a data item is unavailable, the interface supplies a single question mark (?) as a 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:

Word Data Item Description 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. Returned Information:

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 returned value is contained in the RESULT special variable. In addition, the REXX 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. Returned Information:

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. Returned Information:

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. Service Description:

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. Returned Information:

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. Returned Information:

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. Service Description:

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. Service Description:

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'). Returned Information:

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. Returned Information:

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 returned value is contained in the RESULT special variable. In addition, the REXX 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:


TSO, TSO Batch. Service Description:

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:

0 The operation was successful. 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. Returned Information:

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:

picstr rexxnum Result 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:

picstr rexxnum Result 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:

picstr rexxnum Result $$$$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:

picstr rexxnum Result 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. This is the default.

NOMSGS Indicates that messages are not to be produced. Module Name:



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:

call rxsubcom 'add', 'rexxtool', 'rxtarxt' 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.

This is the default.

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. This is the default.

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:

0 The operation was successful. 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. Returned Information:

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:

0 The operation was successful. 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 variables of the form "ABC.1", "ABC.2", "ABC.3", etc. If you specify a 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. Service Description:

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. Returned Information:

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 variables of the form "ABC.1", "ABC.2", "ABC.3", etc. If you specify a 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. This is the default.

'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 Service Description:

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:

0 The operation was successful. 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:



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:

1. 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.

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 codes are common to all REXXTOOL host commands. These are documented under the 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:

call rxsubcom 'add', 'rexxtool', 'rxtarxt' 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.


Module Name:



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:


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 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 rxsubcom 'add', 'rexxtool', 'rxtarxt' 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.


Module Name:



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:

1. 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.

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 VPUT 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 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:

call rxsubcom 'add', 'rexxtool', 'rxtarxt' 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: 1. 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.

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 codes are common to all REXXTOOL host commands. These are documented under the 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 Authorized Assembler Programming Guide, GC28-1645.

S99ERSN An SMS 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.

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:

call rxsubcom 'add', 'rexxtool', 'rxtarxt' 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. Service Description:

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:


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 are common to all REXXTOOL host commands. These are documented under the topic "ADDRESS REXXTOOL".

The specific positive RC values returned by the FREE command 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.



In addition, the following REXX variables are created by the FREE command:

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 Authorized Assembler Programming Guide, GC28-1645 .

S99ERSN An SMS 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 .

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:

call rxsubcom 'add', 'rexxtool', 'rxtarxt' 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 MVS/ESA Authorized Assembler Programming Guide, GC28-1645 . This 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 MVS/ESA Authorized Assembler Programming Guide, GC28-1645 . This 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:

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.



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:

BALR 14, 15

REXX Interpreter (IRXEEXEC)

REXX Load Module 1. Decode REXX

source program. 2. Convert parm list. 3. Build REXX

environment. 4. Call system

interpreter. 5. Convert returned

value. 6. Return to caller.

BR 14

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 //SYSTSPRT DD SYSOUT=* //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

off If specified, comments and extraneous blanks are 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 source data set, or the next-to-last qualifier of a sequential data set.

The name option is used to name the generated CSECT and to provide data for the PARSE SOURCE instruction.

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 produced.

This option is used to create a symbol cross-reference at 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 DDNAME

Data Set Contents RECFM LRECL BLKSIZE

SYSIN Input to the compiler. This data set contains the source REXX program.

FB or VB 80 or 255

SYSLIN The object module produced by the compiler. This data set becomes input to the linkage-editor.

FB 80 800

SYSPRINT The source listing, including the compressed listing, and the cross-reference listing, if they are requested.

FBA 133 13300

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' //STEPLIB DD DISP=SHR,DSN=REXXTOOL.LOAD // DD DISP=SHR,DSN=CICS.SDFHEXCI //SYSEXEC DD DISP=SHR,DSN=REXXTOOL.SAMPLIB //SYSTSIN DD DUMMY //SYSTSPRT DD SYSOUT=*

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

Amanda Baird

Note

Accepted set by Amanda Baird

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: 1. Connect to the queue manager using the MQCONN subfunction. 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.

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.

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: 1. Connect to the queue manager using the MQCONN subfunction. 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. 4. Close the queue using the MQCLOSE subfunction. 5. Disconnect from the queue manager using the MQDISC subfunction.

Setting Attributes

To set queue or other object attributes 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_SET

option. 3. Set one or more attributes using the MQSET subfunction. 4. Close the queue using the MQCLOSE subfunction. 5. Disconnect from the queue manager using the MQDISC 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:

record = get('indd') /* 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 and PARSE

Conversion Before Build and PUT

2 byte binary integer (halfword)

C2D(fieldvalue) D2C(fieldvalue,2)

4 byte binary integer (fullword)

C2D(fieldvalue) D2C(fieldvalue,4)

packed decimal P2D(fieldvalue,s) where s is the number of fractional digits.

D2P(fieldvalue,p,s) where p is the total number of digits and s is the number of fractional digits.

short floating point

F2D(fieldvalue) D2F(fieldvalue,'SHORT')

long floating point F2D(fieldvalue) D2F(fieldvalue,'LONG') printable numeric edited

PIC2D(fieldvalue) D2PIC(fieldvalue,picstr) where picstr is 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 This command takes no operands.


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 This command takes no operands.

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 This command takes no operands.

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 This command takes no operands.


Appendix C: Messages

General

RXT0000S REXXTOOLS AUTHCODE MISSING, INVALID, OR EXPIRED

Explanation: Either you have mis-entered the authorization code, or your license to use the product (or feature) has expired.

Response: Verify that you have entered the authorization code correctly. If the code is correct, contact Open Software Technologies.

RXT0001W YOUR LICENSE TO USE A REXXTOOLS PRODUCT FEATURE WILL EXPIRE IN count DAYS

Explanation: A temporary authorization code for one or more REXXTOOLS features is about to expire.

Response: Contact Open Software Technologies, or your distributor.

RXT0050S THE AUTHCODE IS NOT EXACTLY 12 HEX DIGITS

Explanation: RXTJCL was unable to use the authcode parameter you passed.

Response: Verify that you have entered the authorization code correctly.

RXT0051S IRXINIT FAILED WITH RC=rc REASON=reason

Explanation: RXTJCL was unable to initialize a REXX environment.

Response: Try re-running the program. If the problem persists, contact Open Software Technologies.

Batch Compiler (RXTCOMP)

RXT0001S SYSIN allocation information error

Explanation: You may not have allocated the SYSIN ddname. This message is followed by more diagnostic information.

Response: If the problem is a missing SYSIN allocation, use the TSO ALLOCATE command or

JCL DD statement to allocate the SYSIN ddname, then re-run the job.

RXT0002S SOURCE RECORDS TOO LONG TO BE COMPILED

Explanation: The LRECL of the SYSIN data set is greater than 32767.

Response: You cannot compile a program with records this long. Try copying the program to a data set with a shorter LRECL, and re-compile.

RXT0003S SYSIN data set information error

Explanation: The compiler is unable to determine DCB characteristics for the SYSIN data set.

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 255 source data sets.

RXT0003S SYSIN dcbparm cannot be determined. Specify DCB parameters on DD statement or ALLOCATE command

Explanation: The compiler is unable to determine DCB characteristics for the SYSIN data set.

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 255 source data sets.

RXT0004S ERROR READING SYSIN

Explanation: RXTCOMP was unable to read the data set that is allocated to the SYSIN ddname.

Response: Only DASD data sets, either FB 80 or VB 255 are supported. If your data set has these characteristics, try re-compiling.

RXT0005S NO RECORDS IN SYSIN

Explanation: The SYSIN data set is empty.

Response: There are no records to compile. Make sure you have specified the correct data set.

RXT0006S SYSIN RECFM=recfm is invalid. Only FB and VB are supported

Appendix C: Messages 293

Explanation: The SYSIN data set is neither FB or VB.

Response: You cannot compile this data set. Copy the program to an FB 80 or VB 255 data set and re-compile it.

RXT0007S SOURCE FILE CONTAINS ONLY ZERO LENGTH RECORDS

Explanation: The total length of all the records read is zero.

Response: Make sure you have specified the correct data set.

RXT0008S END OF SOURCE REACHED BEFORE END OF COMMENT

Explanation: The parser was in the middle of a comment when end-of-file was reached.

Response: Look for a missing */. Re-compile after you have fixed the problem.

RXT0009S END OF SOURCE REACHED BEFORE END OF LITERAL

Explanation: The parser was in the middle of a literal when end-of-file was reached.

Response: Look for a missing quote or double quote. Re- compile the program after you have fixed the problem.

RXT0010S VERSION KEYWORD HAS NO VALUE

Explanation: The VERSION keyword was specified, but no value was supplied.

Response: Correct the error and rerun.

RXT0011S NAME KEYWORD HAS NO VALUE

Explanation: The NAME keyword was specified but no value was supplied.


RXT0012S PAGESIZE KEYWORD HAS NO VALUE

Explanation: The PAGESIZE keyword was specified but no value was supplied.


RXT0013S KEYWORD keyword IS UNRECOGNIZED

Explanation: RXTCOMP encountered a keyword it did not recognize.


RXT0014S keyname KEYWORD VALUE IS NOT TERMINATED WITH ')'

Explanation: The keyword named is missing a closing parenthesis.

Response: Correct the problem and rerun.

RXT0015S NAME PARAMETER MUST BE SPECIFIED

Explanation: The NAME parameter (option) is missing.

Response: You must supply a name for the CSECT. The name must be 1 to 8 characters long and the first character must be alphabetic.

RXT0016S RXTCOMP FAILURE. RC=rc REASON=reason

Explanation: The batch compiler experienced some type of internal error.

Response: Report the problem to Open Software Technologies.

Run-Time Module (RXTRXPRE)

RXT0101S ZERO LENGTH PROGRAM. pgm CONTAINS NO SOURCE RECORDS.

Explanation: One of the internal control blocks indicated that the source is missing.

Response: You have probably link-edited RXTRXPRE with a program that was not created by RXTCOMP.

RXT0102S PARMLIST TYPE INVALID. pgm INVOKED WITH AN INVALID PARMLIST

Explanation: The prefix module could not identify the parmlist.

Response: Verify that the parmlist passed is a valid OS parmlist.

RXT0110S VERSION MISMATCH. RXTRXPRE VERSION=vv.rr.mm. pgm VERSION=vv.rr.mm


Explanation: The program, pgm, was compiled with a version of RXTCOMP that is not supported by this version of RXTRXPRE.

Response: This problem happens when an old version of RXTRXPRE is link-edited with a program compiled with a new version of RXTCOMP.

RXC TSO Command

RXT0200S SOURCE DSN NOT SPECIFIED. RXC TERMINATING.

Explanation: The RXC was not passed the source data set name

Response: The source data set name is required. Supply the name when you rerun RXC.

RXT0201S OBJECT KEYWORD HAS NO VALUE

Explanation: The OBJECT keyword was specified, but no value was supplied.

Response: Supply a value and rerun.

RXT0202S LIST KEYWORD HAS NO VALUE

Explanation: The LIST keyword was specified, but no value was supplied.


RXT0203S keyname KEYWORD HAS NO VALUE

Explanation: The keyname keyword was specified, but no value was supplied.


RXT0204S dsn ALLOCATION FAILED. RC=rc

Explanation: RXC failed in its attempt to allocate the specified data set.

Response: Allocation messages should accompany this message. Refer to these messages to determine the cause of the problem.

RXT0205S dsn ERROR. msg

Explanation: There is a problem with the specified data set. Processing is terminated.

Response: The msg field should indicate what the problem is.

RXT0206S keyname KEYWORD VALUE IS NOT TERMINATED WITH ')'

Explanation: A keyword that requires a value was found, but no value was supplied.

Response: Supply the value and rerun.

RXT0207S dsn IS PARTITIONED, BUT NO MEMBER WAS GIVEN

Explanation: Member names must be supplied when specifying the name of a partitioned data set.

Response: Supply a member name and rerun.

RXT0208S dsn IS SEQUENTIAL, BUT A MEMBER WAS GIVEN

Explanation: A sequential data set cannot have a member name.

Response: Remove the member name and rerun.

RXT0209S dsn ERROR. UNSUPPORTED DSORG

Explanation: The data set listed cannot be processed. Only PO and PS organizations are supported.

Response: Switch to a data set that is either PO or PS.

RXT0210S RXC FAILURE. RC=rc REASON=reason

Explanation: The RXC command experienced some type of internal error.

Response: Report the problem to Open Software Technologies.

STORAGEX Function (RXTSTORX)

RXT0240E STORAGEX ADDRESS IN ERROR AT xxxxxxxx

Explanation: The address argument has an invalid component.

Response: Correct the address argument and retry the function call.

RXT0241E STORAGE AT 'xxxxxxxx'X COULD NOT BE ACCESSED


Explanation: Either the storage at the indicated location has not been allocated or is fetch protected.

Response: Correct the problem and retry the function call.

RXT0242E STORAGE AT 'xxxxxxxx'X COULD NOT BE MODIFIED

Explanation: The storage at the indicated location is protected, and cannot be modified by a problem state program in user key.

Response: Correct the problem and retry the function call.

RXT0243E STORAGE MODIFICATION IS CURRENTLY DISABLED

Explanation: The STORFL of the current environment block indicates that use of the STORAGE function is invalid. STORAGEX interprets this bit setting as disallowing storage modification only.

Response: Use another REXX environment or do not attempt to modify storage.

REXX Module Load (RXTCRRLD)

RXT0260E MODULE module IS NOT AMODE 31

Explanation: Modules that are to be LINKed to by REXX must run AMODE(31).

Response: Re-linkedit the indicated module.

RXT0261E MODULE module IS NOT REENTRANT

Explanation: Modules that are to be LINKed to by REXX must be reentrant in order to not be reloaded with each LINK.

Response: Re-link-edit the indicated module.

RXFUNC (RXTFUNC)

RXT0262E DIRECTORY dirname CANNOT BE MODIFIED

Explanation: The indicated directory is in protected storage.

Response: You cannot modify the directory.

RXT0263E DIRECTORY dirname CANNOT BE LOCATED

Explanation: A directory listed in the function package table cannot be located.

Response: Verify that your REXX parameters module's function package table is correct, and that the directories listed in the parameters module are accessible.

EXECSQL Command

RXT0280S EXECSQL FAILURE. RC=rc. REASON=reason

Explanation: The EXECSQL command encountered an internal error.

Response: Try re-running the command. If the problem persists. Contact your Open Software representative.

RXT0281S RXSUBCOM failed with RC=rc REASON=reason. EXECSQL Terminating

Explanation: The EXECSQL command was unable to dynamically install the RXTASQL2 host command environment.

Response: Usually other messages will accompany this message. Ensure that the RXTASQL2 module can be located by the MVS LOAD macro.

RXT0282S DB2INFO call failed. RC=rc

Explanation: The EXECSQL was unable to determine DB2 default values.

Response: This probably means that the DB2 load library is unavailable to your program. Make sure that an MVS LOAD macro instruction can locate the DSNHDECP module.

RXT0283S DSNALI OPEN failed with RC=rc. EXECSQL Terminating.

Explanation: The EXECSQL command was unable to open the RXTCS plan.

Response: Verify that you have bound the RXTCS plan and that the DB2 subsystem is active

RXT0284S ADDRESS OSTSQL failed with RC=rc. EXECSQL Terminating.

Explanation: The SQL statement that you passed to EXECSQL encountered some sort of problem.


Response: Correct the SQL statement and rerun the command.

QSAM, BPAM, and VSAM Interfaces

RXT0300E DDNAME ddname IS ALREADY IN USE

Explanation: This ddname has already been opened.

Response: You must close a ddname before you can reopen it.

RXT0301E DDNAME ddname IS NOT IN USE

Explanation: This ddname has not yet been opened.

Response: Open the ddname before you attempt any other VSAM operation.

RXT0302E INVALID OPTION SPECIFIED

Explanation: The MACRF option you specified was invalid.

Response: Correct the options argument and retry the open.

RXT0303E synadmsg

Explanation: The SYNAD exit was invoked for an I/O operation. The text of the message describes the operation attempted.

Response: This message is caused by various 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 consistent with the information in the VTOC. Use the TSO LISTD command to obtain data set DCB characteristics.

RXT0304E DATASET DSORG IS INVALID FOR SELECTED ACCESS METHOD

Explanation: You have tried to open a file using the wrong access method.

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 with VSAM files only.

RXT0305E DATASET RECFM IS NOT SUPPORTED

Explanation: The BPAM and QSAM interfaces support only those RECFMs listed in their respective

chapters. Specifically, spanned records are not supported.

Response: Do not open the failing data set.

RXT0306E DATASET BLKSIZE IS INVALID

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 than the LRECL.

Response: Correct the block size and retry the operation.

RXT0307E DATASET LRECL IS INVALID

Explanation: LRECL must be greater than zero and less than or equal to the block size. If RECFM=F is used, LRECL must be identical to BLKSIZE. If RECFM=FB is used, BLKSIZE must be an even multiple of LRECL. If variable length records are used, the LRECL must be at least 4.

Response: Correct the LRECL or BLKSIZE (whichever is appropriate) and retry the operation.

RXT0308E GET IS INVALID IN THIS CONTEXT. CHECK OPEN OPTIONS

Explanation: The GET function has been used with incompatible open options.

Response: Verify that the file is open for input or update. GET cannot be used with a file that is open for output.

RXT0309E RETRIEVED RECORD'S LRECL IS INVALID

Explanation: The detected logical record length is either zero, longer than the indicated LRECL parameter, or longer than the block size.

Response: This could happen if you read an empty sequential data set, or if you specify DCB characteristics that are incompatible with the characteristics defined in the VTOC. Correct the problem and re-run the job.

RXT0310E FINDM MUST BE PERFORMED BEFORE GET

Explanation: A FINDM function call did not precede the failing GET.

Response: When using BPAM, you must establish position using the FINDM function prior to reading a member. Correct the problem and re-run the job.


RXT0311E RETRIEVED BLOCK'S LENGTH IS INVALID

Explanation: The indicated length of the retrieved block was either zero, or longer than the value given by BLKSIZE parameter.

Response: This could happen if you read an empty sequential data set, or if you specify DCB characteristics that are incompatible with the characteristics defined in the VTOC. Correct the problem and re-run the job.

RXT0312E CURRENT RECORD LIES OUTSIDE THE RETRIEVED BLOCK

Explanation: The retrieved record is not entirely contained within the current block.

Response: This could be caused by an invalid record descriptor word (RDW). Dump the file to determine the cause of the problem. If no problem is found, call OST technical support.

RXT0313E PUT IS INVALID IN THIS CONTEXT. CHECK OPEN OPTIONS

Explanation: A PUT was issued for a file that was opened with incompatible options.

Response: PUT may be used only with files that are 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.

RXT0314E NO RECORD TO UPDATE. A GET MUST PRECEDE A PUT FOR UPDATE

Explanation: A PUT for update was executed without a preceding GET for update.

Response: A record must be read with GET prior to PUTting it back. You must do this even if you plan to ignore the read record. Correct the problem and re-run the job.

RXT0315E THIS OPERATION IS INCOMPATIBLE WITH THE CURRENT ACCESS METHOD

Explanation: A function has been used that is not proper for the access method in use.

Response: This problem has several forms. You may not, for example, use the FINDM function with a 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 the operation.

RXT0316E STOWM IS INVALID IN THIS CONTEXT. CHECK OPEN OPTIONS

Explanation: STOWM was used with a file that was opened with incompatible options.

Response: STOWM may be used only with files that are open for output or update.

RXT0317E FINDM IS INVALID IN THIS CONTEXT. CHECK OPEN OPTIONS

Explanation: FINDM was used with a file that was opened with incompatible options.

Response: FINDM may be used only with files that are open for input or update.

Static SQL

RXT0500W varname HAS BEEN TRUNCATED

Explanation: The variable's data has been truncated to fit its declared length. Execution continues.

Response: Either change the declaration, or ensure that the data does not exceed the declared length.

RXT0501S varname CONVERSION ERROR

Explanation: The variable's data did not fit the declared type.

Response: Either change the declaration, or ensure that the data is of the proper type.

Dynamic SQL

RXT0600I sqlcommand

Explanation: This is an informational message that shows the current SQL command. Usually the sqlcommand displayed is the "processed string", not the input command string. However, in some cases the unprocessed command string is displayed.

Response: If this message is accompanied by error messages, correct the problem and rerun the exec.

RXT0601W DECLARE STATEMENT IS UNSUPPORTED

Explanation: The DECLARE STATEMENT command is not supported.

Response: Remove the DECLARE STATEMENT command.


RXT0602W DECLARE STATEMENT IS UNRECOGNIZED

Explanation: The DECLARE type is not recognized.

Response: Only DECLARE CURSOR, DECLARE VARIABLE, and DECLARE TABLE, are supported. Check for spelling or syntax errors.

RXT0603E CURSOR NAME csrname IS INVALID OR RESERVED

Explanation: The cursor name cannot be used.

Response: Cursor names must be valid REXX variable symbols 1 to 8 bytes long. $RXTCSR$ is a reserved name.

RXT0604E MAXIMUM NUMBER OF DECLARED CURSORS EXCEEDED

Explanation: More cursors were declared than are available in the pool of static cursors.

Response: You must free a cursor in order to declare another one.

RXT0605E CUSOR NAME csrname IS ALREADY IN USE

Explanation: You have tried to re-declare a cursor that has already been declared.

Response: Free the cursor before trying to re-declare it.

RXT0606E DECLARE CURSOR STATEMENT IS UNUSABLE

Explanation: The DECLARE CURSOR cannot be used.

Response: Check for syntax errors, and rerun the program.

RXT0607E VARIABLE NAME varname IS INVALID

Explanation: The host variable name not a valid REXX variable name.

Response: Check for coding errors. Refer to the REXX Reference for information regarding valid REXX variable names. Note though, that the "?" cannot be used, even though it is permitted in REXX symbols.

RXT0608E DECLARE STATEMENT SYNTAX ERROR

Explanation: The DECLARE command cannot be used due to syntax errors.

Response: Correct any errors and rerun the program.

RXT0609E FREE STATEMENT IS UNUSABLE

Explanation: The FREE command is in error.

Response: Check for syntax errors, correct these, and rerun the program.

RXT0610E FREE STATEMENT IS UNRECOGNIZED

Explanation: The FREE type is unrecognized.

Response: Only FREE CURSOR and FREE VARIABLE commands are supported. Check for spelling errors.

RXT0611E CURSOR NAME csrname IS OPEN

Explanation: The operation on the cursor cannot be performed because the cursor is open.

Response: Close the cursor before attempting the operation.

RXT0612E CURSOR NAME csrname NOT FOUND

Explanation: You have attempted to use a cursor before you have declared it.

Response: Use the DECLARE CURSOR command to declare the cursor before using its name. If you thought you did, check for logic or spelling errors.

RXT0613E VARIABLE NAME varname NOT FOUND

Explanation: You have attempted an operation on a variable that is not declared.

Response: You either did not declare the variable, or you have already freed it.

RXT0614E NO VARIABLES FOR PROGRAM progname

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

Explanation: A non-zero SQLCODE has been returned by DB2. The message explains the problem.

Response: Refer to DB2 Messages and Codes, SC26-4379 for problem resolution.

RXT0616E SQL STATEMENT STRING IS EMPTY

Explanation: The host command was zero-length or all blanks.

Response: You must pass a non-blank host command expression. Use the TRACE C REXX instruction to trace host command execution.

RXT0617E token IS NOT A RECOGNIZED SQL VERB

Explanation: The SQL command could not be executed because the first word was not a recognized SQL command.

Response: Check for spelling errors in your host command.

RXT0618E token IS NOT A RECOGNIZED OPTION

Explanation: The token in the OPTIONS command is not a valid option.

Response: Check for spelling errors.

RXT0619E NO OPTIONS SPECIFIED

Explanation: No options followed the OPTIONS verb.

Response: You must code at least one option.

RXT0620E OPTIONS STATEMENT SYNTAX ERROR

Explanation: The OPTIONS command could not be executed due to syntax errors.

Response: Check for spelling errors. Also note that options must be separated by one or more blanks.

RXT0621E DB2 DID NOT COMPLETE SQLCA

Explanation: A DB2 request did not result in the SQLCA being filled in.

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

RXT0622E NO. OF INTO VARS DOES NOT MATCH NO. OF SELECTED COLS

Explanation: The INTO clause of a SELECT or FETCH statement does not have the same number of variables as there are columns to be retrieved.

Response: Correct the problem and retry the request.

RXT0623E CONNECT STATEMENT SYNTAX ERROR

Explanation: The CONNECT statement is not useable due to syntax errors.


RXT0624E SET STATEMENT SYNTAX ERROR

Explanation: The SET statement is not useable due to syntax errors.


RXT0625E DESCRIBE STATEMENT SYNTAX ERROR

Explanation: The DESCRIBE statement is not useable due to syntax errors.


RXT0626E TABLE/VIEW NAME IS TOO LONG

Explanation: The table or view name is longer than 254 bytes.


RXT0627E VARIABLE NAME varname IS INVALID OR TOO LONG

Explanation: The variable name is not a valid REXX variable name.

Response: Correct the problem and retry the request. Refer to REXX Reference for the definition of valid variable names.

RXT0628E CLOSE STATEMENT SYNTAX ERROR

Explanation: The CLOSE statement is not usable due to syntax errors.



RXT0629E CURSOR NAME csrname HAS BEEN USED BEFORE IT HAS BEEN DECLARED

Explanation: The cursor that has been OPENed, FETCHed, or CLOSEd, or used in a WHERE CURRENT OF clause has not been declared.

Response: Execute a DECLARE CURSOR statement prior to using the csrname in any other statement.

RXT0630E OPEN STATEMENT SYNTAX ERROR

Explanation: The OPEN statement is not useable due to syntax errors.


RXT0631E FETCH STATEMENT SYNTAX ERROR

Explanation: The FETCH statement is not useable due to syntax errors.


RXT0632E BEGIN/END DECLARE SECTION SYNTAX ERROR

Explanation: The BEGIN or END DECLARE SECTION statement is not useable due to syntax errors.


RXT0633E STATEMENT CONTAINED AN INVALID OUTPUT VARIABLE

Explanation: One of the output variables in the statement was not a valid REXX variable name.


RXT0634E STATEMENT CONTAINS A QUESTION MARK. QUESTION MARKS ARE NOT PERMITTED.

Explanation: A question mark was found in the host command expression.

Response: Question marks are not permitted and must be removed.

RXT0635E END OF STATEMENT FOUND BEFORE END OF LITERAL

Explanation: The parser ran out of tokens before a closing quote mark was found.


RXT0636E STATEMENT CONTAINS A TOKEN LARGER THAN 250 BYTES

Explanation: The parser encountered a token larger than the maximum.

Response: Neither DB2 nor REXX require tokens larger than 250 bytes. Correct the problem and retry the request. Check for missing blank delimiters.

RXT0637E 'EXEC SQL' OR TERMINATING SEMICOLON SYNTAX ERROR

Explanation: The EXEC SQL or terminating semicolon were mis-coded.

Response: Check for spelling and punctuation errors. Correct the problem and retry the request.

RXT0638E INTO CLAUSE SYNTAX ERROR

Explanation: The INTO clause could not be processed.

Response: Verify that your host variables are all prefixed with colons, and that host variable expression are separated by commas.

RXT0639E varname IS AN INVALID DATA VARIABLE NAME

Explanation: The variable named in this message is not a valid REXX variable name.


RXT0640E varname IS AN INVALID INDICATOR VARIABLE NAME

Explanation: The variable named in this message is not a valid REXX variable name.



RXT0641E INPUT INDICATOR VARIABLE varname CONTAINS A VALUE THAT CANNOT BE CONVERTED TO A SMALLINT NUMBER

Explanation: The indicator variable contains a non- numeric value.

Response: Use TRACE I to find the problem. Indicator variables must contain numeric values between -32768 and +32767.

RXT0642E IRXEXCOM DETECTED INVALID VARIABLE NAME

Explanation: The REXX variable access routine indicated that a variable name in the request is invalid.


RXT0643E A COLON WAS NOT IMMEDIATELY FOLLOWED BY A VARIABLE NAME

Explanation: A colon that was not immediately followed by another token was found.

Response: You may have coded a blank between the colon and the variable name. Correct the problem and retry the request.

RXT0644E VARIABLE varname CONTAINS A VALUE THAT IS MORE THAN 32767 BYTES LONG

Explanation: A value larger than the maximum accepted by DB2 was found.

Response: DB2 will not accept a value larger than this. Correct the problem and retry the request.

RXT0645E VARIABLE varname COULD NOT BE CONVERTED TO TYPE db2type

Explanation: The variable listed could not be converted from the REXX printable data type to the target DB2 data type.

Response: Usually this happens when a variable declaration is missing. Check for spelling errors.

RXT0646E RELEASE STATEMENT SYNTAX ERROR

Explanation: The RELEASE statement could not be used due to syntax errors.


Dynamic Allocation

RXT0800E token IS NOT A RECOGNIZED ALLOCATE KEYWORD

Explanation: The token listed is not a valid ALLOCATE or FREE keyword.

Response: Check for spelling errors, errors in abbreviation, and punctuation errors.

RXT0801E A STATUS OF 'NEW' IS INCOMPATIBLE WITH A DATA SET CONCATENATION REQUEST

Explanation: The request tried to allocate more than one data set with a status of NEW.

Response: You can only allocate NEW data sets one at a time.

RXT0800E keyword KEYWORD SYNTAX ERROR

Explanation: The keyword listed was not followed by a correct value expression.

Response: Keyword values must be enclosed in parentheses. In addition, each keyword has specific value coding requirements.

Internal

RXT0900S REXXTOOLS STACK OVERFLOW

Explanation: The product's storage stack pointer has exceeded one of its bounds.

Response: Contact Open Software Technologies.

RXT0901S REXXTOOLS STACK UNDERFLOW

Explanation: The product's storage stack pointer has exceeded one of its bounds.

Response: Contact Open Software Technologies.

RXT9002S INVALID ANCHOR BLOCK

Explanation: The RXTANCHR module has been corrupted.

Response: Try logging off and logging back on. If that does not correct the problem, obtain a dump of the RXTANCHR module, and contact Open Software Technologies.


RXT1351S REXX PROGRAM NAME IS INVALID RXTWTR Explanation: The REXX program name is syntactically invalid. OST0002S PROGRAM NOT APF AUTHORIZED

Explanation: The RXTWTR program is not APF-authorized and cannot function. Execution terminates.

Response: REXX program names must be valid MVS PDS member names.

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 REXXTOOLS load library is in the APF list or is in the link list with the LNKAUTH=LNKLST parameter specified in the IEASYSxx member of SYS1.PARMLIB.

Explanation: The REXX program could not be executed due to some type of internal REXX error.

Response: Try rerunning the transaction. If the problem persists, contact Open Software Technologies.

RXTAMT (APPC/MVS Transaction Program)

RXT1353S CANNOT LOAD REXX PROGRAM

Explanation: The REXX program could not be loaded. RXT1350S REXX PROGRAM NAME IS MISSING

Response: Make sure you have coded the REXX program name correctly (check spelling). Also verify that the REXX program can be found in the SYSEXEC data set concatenation.

Explanation: The REXX program cannot be executed.

Response: You must specify the name of the REXX program on the PARM= JCL parameter. The syntax for this parameter is identical to the one used for IRXJCL (see the REXX Reference).

RXT1354S CANNOT INIT REXX ENVIRONMENT

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

Documents