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 Specifying Data Set Names
Using Pattern Matching Parsing Returned Values
DSORG, Status, and Disposition Return Codes and Messages
Service Descriptions

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.

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:
- Specify the specific generation, as in: GDG01.G0001V00.
- 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:

To find all entities with a fixed prefix, use a pattern with the fixed characters followed by an asterisk (e.g., abc*).
To find all entities with a fixed suffix, use a pattern with an asterisk followed by the fixed characters (e.g., *abc).
Prefix and suffix type patterns can be combined, as in abc*123.
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.
A pattern composed only of fixed characters will match one (and only one) entity (ddname or member name).
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".
*abcxyz**	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.
*abc*	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 templet 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.

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)

Service Descriptions

The sections that follow describe the syntax and operation of the data set information functions.