|Introduction||Specifying Data Set Names|
|Using Pattern Matching||Parsing Returned Values|
|DSORG, Status, and Disposition||Return Codes and Messages|
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
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:
call dsninfo "'sys1.parmlib'"
The valid wild card characters and their meanings are as follows:
|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.|
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:
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.
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 endIn 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) endFor 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.
parse value listm(dsname,,,'u') with rc mc if rc = 0 then do i = 1 to mc parse pull name ttr alias userfld endWhen 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 endNote: 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).
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' dsnameIn 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.
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:
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:
MVS/ESA Authorized Assembler Services Reference
MVS/ESA Authorized Assembler Services Guide
MVS/DFP System Programming Reference
DFSMS/MVS Using Advanced Services Data Sets
MVS/DFP Macro Instructions for Data Sets
DFSMS/MVS Macro Instructions for Data Sets
|All Services||MVS/ESA System Messages (various volumes)|