LISTDSI
Function code | Description |
---|---|
0 | LISTDSI processing was successful. Data set information was retrieved. |
4 | LISTDSI processing was successful. Some data set information is unavailable. Review the reason code in the returned variable SYSREASON and check the messages returned in SYSMSGLVL1 and SYSMSGLVL2 to determine which information is unavailable. |
16 | LISTDSI processing was not successful. An error occurred. None of the variables containing information about the data set can be considered valid, except for SYSREASON. The SYSREASON variable contains the LISTDSI reason code (see Reason Codes). |
You can use LISTDSI to obtain information about a data set that is available on DASD. LISTDSI does not directly support data that is on tape. LISTDSI supports generation data group (GDG) data sets when using absolute generation names, but does not support relative GDG names. LISTDSI does not support hierarchical file system (HFS) data sets. Unpredictable results may occur.
argument_string = "REXXEXEC VOLUME(PACK1) NODIRECTORY NORECALL"
x = LISTDSI(argument_string)
If LISTDSI causes a syntax error (for example, if you specify more than one argument string), a function code is not returned. In addition, none of the LISTDSI variables are set.
To suppress TSO/E messages issued by the LISTDSI function, use the MSG("OFF") function. For information about the MSG function, see MSG.
- data-set-name
- the name of the data set about which you want to retrieve information. See Specifying Data Set Names for more information.
- location
- specifies how you want the data set (as specified in data-set-name) located. You can specify location, only if you specify
a data set name, not a filename. For location, specify
one of the following values. If you do not specify either VOLUME
or PREALLOC, the system locates the data set through catalog search.
- ‘VOLUME(serial ID)’ specifies the serial number of the volume where the data set is located.
- ‘PREALLOC’ specifies that the location of the specified data set is determined by allocating the data set, rather than through a catalog search. PREALLOC allows data sets that have been previously allocated to be located without searching a catalog and allows unmounted volumes to be mounted.
- filename
- the name of an allocated file (ddname) about which you want to retrieve information.
- file
- you must specify the word
FILE
if you specify filename instead of data-set-name. If you do not specify FILE, LISTDSI assumes that you specified a data-set-name. - directory
- indicates whether you want directory information for a partitioned
data set (PDS or PDSE). For directory, specify one
of the following:
- ‘DIRECTORY’ indicates that you want directory information.
Requesting DIRECTORY information for a PDS may cause the date last referenced (SYSREFDATE) to be updated by LISTDSI. Refer to the description of the SYSREFDATE variable for more information about when SYSREFDATE might be updated by LISTDSI.
- ‘NODIRECTORY’ indicates that you do not want directory information. If you do not require directory information, NODIRECTORY can significantly improve processing. NODIRECTORY is the default.
- ‘DIRECTORY’ indicates that you want directory information.
- multivol
- Specify MULTIVOL or NOMULTIVOL. The default if not specified is
NOMULTIVOL. Indicates whether data size calculations should include
all volumes, when a data set resides on more than one volume. The
new SYSNUMVOLS and SYSVOLUMES variables are not affected by this operand,
as these are always set.
If the VOLUME keyword and the MULTIVOL keyword are both specified, the MULTIVOL keyword is ignored. In this case, data set size information is returned just for the specified volume.
- racf
- Specify RACF® or NORACF. The default if not specified is RACF. Indicates whether a check for RACF authority is done or not. If not done, the data set will not be opened by LISTDSI, for example, to read directory information.
- recall
- indicates whether you want to recall a data set migrated by Data
Facility Hierarchical Storage Manager (DFHSM). For recall,
specify one of the following:
- ‘RECALL’ indicates that you want to recall a data set migrated by DFHSM. The system recalls the data set regardless of its level of migration or the type of device to which it has been migrated.
- ‘NORECALL’ indicates that you do not want to recall
a data set. If the data set has been migrated, the system stores
an error message.
If you do not specify either RECALL or NORECALL, the system recalls the data set only if it has been migrated to a direct access storage device (DASD).
- smsinfo
- indicates whether you want System Managed Storage (SMS) information
about an SMS-managed data set. This information includes
- type of data set
- used space
- data class name
- storage class name
- management class name.
For smsinfo, specify one of the following:- ‘SMSINFO’ indicates that you want SMS information
about data-set-name or filename. Neither data-set-name nor filename may refer to a VSAM index or data component.
If the specified data set is not managed by SMS, LISTDSI continues, but no SMS information is provided in the corresponding REXX variables.
Specify SMSINFO only if you want SMS information about a data set. NOSMSINFO (the default) may significantly reduce the execution time of the LISTDSI statement.
Requesting SMSINFO for a PDSE data set may cause the date last referenced (SYSREFDATE) to be updated by LISTDSI. Refer to the description of the SYSREFDATE variable for more information about when SYSREFDATE might be updated by LISTDSI.
- ‘NOSMSINFO’ indicates that you do not want SMS information about the specified data set. NOSMSINFO is the default.
You can use the LISTDSI function only in REXX execs that run in the TSO/E address space.
Environment Customization Considerations If you use IRXINIT to initialize language processor environments, note that you can use LISTDSI only in environments that are integrated into TSO/E (see Types of environments - integrated and not integrated into TSO/E).
You can use the LISTDSI information to determine whether the data set is the right size or has the right organization or format for a given task. You can also use the LISTDSI information as input to the ALLOCATE command, for example, to create a new data set using some attributes from the old data set while modifying others.
If you use LISTDSI to retrieve information about a VSAM data set, LISTDSI stores only the volume serial ID (in variable SYSVOLUME), the device unit (in variable SYSUNIT), and the data set organization (in variable SYSDSORG).
If you use LISTDSI to retrieve information about a multiple volume data set, LISTDSI stores information for the first volume only. Similarly, if you specify a file name or you specify PREALLOC for location and you have other data sets allocated to the same file name, the system may not retrieve information for the data set you wanted.
LISTDSI
When you use LISTDSI to obtain information about a file, LISTDSI will return information only about the first data set in the file, if the file consists of a concatenation of more than one data set. Likewise, if the ddname specified by filename points to a multi-volume data set, LISTDSI can return information only about the first volume, and will not be able to detect that the data is multi-volume.
If the data set is SMS managed and is capable of expanding to multiple volumes, but has not yet done so, it is considered a single volume data set by LISTDSI until it has expanded to the second volume. In any case, LISTDSI will only retrieve information for the first volume referenced by the request.
As part of its processing, LISTDSI issues a RACF authority check against the provided data set which will cause a security violation to occur if the user does not have at least READ access to the data set. RACF does not issue an ICH408I message due to message suppression requested by LISTDSI, and therefore LISTDSI issues a return code of 0 (NODIRECTORY specified) or 4 (DIRECTORY specified). The only indication a security violation has occurred is that an SMF type-80 RACF audit record is created.
LISTDSI considers file names in the form SYSnnnnn
as system-generated file
names. If LISTDSI is used to obtain information about a data set that was pre-allocated multiple
times using a file name of the form SYSnnnnn
, an existing file may be
unintentionally freed.
Specifying Data Set Names
- Non fully-qualified data set name that follows the naming conventions — When there is only
one set of quotation marks or no quotation marks, TSO/E adds your prefix to the data set name.
x = LISTDSI('myrexx.exec') x = LISTDSI(myrexx.exec)
- Fully-qualified data set name — The extra quotation marks prevent TSO/E from adding your
prefix to the data set name.
x = LISTDSI("'sys1.proj.new'") x = LISTDSI('''sys1.proj.new''')
- Variable name that represents a fully-qualified or non fully-qualified data set name — The
variable name must not be enclosed in quotation marks because quotation marks prevent variable
substitution. An example of using a variable for a fully-qualified data set name is:
/* REXX program for .... */ ⋮ var1 = "'sys1.proj.monthly'" ⋮ dsinfo = LISTDSI(var1) ⋮ EXIT
Variables that LISTDSI sets
Variable | Contents |
---|---|
SYSDSNAME | Data set name |
SYSVOLUME | Volume serial ID |
SYSUNIT | Generic device type on which volume resides, for example 3390. |
SYSDSORG | Data set organization:
|
SYSRECFM | Record format; one to six character combination of the following:
|
SYSLRECL | Logical record length |
SYSBLKSIZE | Block size |
SYSKEYLEN | Key length |
SYSALLOC | Allocation, in space units |
SYSUSED | Allocation used, in space units. For a partitioned data set extended (PDSE), 'N/A' will be returned; see the description of the variable SYSUSEDPAGES for used space of a PDSE. |
SYSUSEDPAGES | The used space of a partitioned data set extended (PDSE) in 4K pages. |
SYSPRIMARY | Primary allocation in space units |
SYSSECONDS | Secondary allocation in space units |
SYSUNITS | Space units:
|
SYSEXTENTS | Number of extents allocated |
SYSUSEDEXTENTS | Indicates the number of extents used. For a partitioned data set extended (PDSE), this variable returns 'N/A'; see the descriptions of variables SYSUSEDPAGES and SYSUSEDPERCENT for more information about used space of a PDSE. |
SYSCREATE | Creation date Year/day format, for example: 1990/102 |
SYSREFDATE | Last referenced date Year/day format, for example: 2010/107 Specifying DIRECTORY or SMSINFO
may cause the last referenced date to be updated to the current date under the following
circumstances:
|
SYSEXDATE | Expiration date Year/day format, for example: 1990/365 |
SYSPASSWORD | Password indication:
|
SYSRACFA | RACF indication:
|
SYSUPDATED | Backup change indicator:
|
SYSTRKSCYL | Tracks per cylinder for the unit identified in the SYSUNIT variable |
SYSBLKSTRK | Blocks (whose size is given in variable SYSBLKSIZE) per track for the unit
identified in the SYSUNIT variable. For a PDSE, the value N/Ais returned because a block of size SYSBLKSIZE can 'span' a track in a PDSE. The value contained in SYSUSEDPAGES is a more meaningful measurement of space usage for a PDSE. |
SYSADIRBLK | For a partitioned data set (PDS) the number of directory blocks allocated will
be returned. For a partitioned data set extended (PDSE), NO_LIMwill be returned because there is no static allocation for its directory. A value is returned only if DIRECTORY is specified on the LISTDSI statement. |
SYSUDIRBLK | For a partitioned data set (PDS) the number of directory blocks used will be
returned. For a partitioned data set extended (PDSE), N/Awill be returned because it is not a static value. A value is returned only if DIRECTORY is specified on the LISTDSI statement. |
SYSMEMBERS | Number of members - returned only for partitioned data sets when DIRECTORY is specified |
SYSREASON | LISTDSI reason code |
SYSMSGLVL1 | First-level message if an error occurred |
SYSMSGLVL2 | Second-level message if an error occurred |
SYSDSSMS | Contains information about the type of a data set, provided by DFSMS/MVS. If the SMS data set
type could not be retrieved, the SYSDSSMS variable contains:
If the data set is a PDSE and the SMSINFO operand was specified on the LISTDSI call and
SMS data set type information could be retrieved, the SYSDSSMS variable contains:
Note: This detailed data set type information for a PDSE is not returned if the user issuing the
LISTDSI call does not have RACF READ authority to the data
set.
|
SYSDATACLASS(1) | The SMS data class name - returned only if SMSINFO is specified on the LISTDSI statement and the data set is managed by SMS. |
SYSSTORCLASS(1) | The SMS storage class name - returned only if SMSINFO is specified on the LISTDSI statement and the data set is managed by SMS. |
SYSMGMTCLASS(1) | The SMS management class name - returned only if SMSINFO is specified on the LISTDSI statement and the data set is managed by SMS. |
SYSSEQDSNTYPE |
Indicates the type of sequential data set: BASIC - regular sequential data set LARGE - large sequential data set EXTENDED - extended sequential data set If the data set is not sequential, this variable returns a null string. |
SYSEATTR | Indicates the current status of the EATTR bits in the DSCB that describe the EAS eligibility status of a data set. The EAS can only contain data sets that are EAS-eligible.
|
SYSEADSCB | Indicates whether the data set has extended attributes:
|
SYSALLOCPAGES | Indicates number of pages allocated to a PDSE. |
SYSUSEDPERCENT | Indicates percentage of pages used out of pages allocated for a PDSE. This is a number from 0 to 100, rounded down to the nearest integer value. |
SYSNUMVOLS | Indicates a number from 1 to 59 as tape is not supported, but will always return 1 if a volume is specified, instead of trying LOCATE all volumes for the data set. |
SYSVOLUMES | Indicates up to 412 characters with a list of volumes separated by spaces where the first six characters will always match SYSVOLUME and each volume name takes up six spaces padded with blanks to help simplify parsing. If a volume is specified on the LISTDSI call, just that volume name is returned. |
SYSCREATETIME | Indicates the time a data set was created in the format hh:mm:ss where hh is hours since midnight, mm is minutes since midnight, and ss is seconds since midnight. This variable is only set for EAV data sets and can be used together with the SYSCREATE variable to determine the date and time when a data set was created. |
SYSCREATESTEP | Indicates the name of the job step that created the data set. |
SYSCREATEJOB | Indicates the name of the job that created the data set. |
Note: For data sets not managed by SMS, these variables return a null string.
|
Reason Codes
Reason code | Description |
---|---|
0 | Normal completion. |
1 | Error parsing the function. |
2 | Dynamic allocation processing error. |
3 | The data set is a type that cannot be processed. |
4 | Error determining UNIT name. |
5 | Data set not cataloged. |
6 | Error obtaining the data set name. |
7 | Error finding device type. |
8 | The data set does not reside on a direct access storage device. |
9 | DFHSM migrated the data set. NORECALL prevents retrieval. |
11 | Directory information was requested, but you lack authority to access the data set. |
12 | VSAM data sets are not supported. |
13 | The data set could not be opened. |
14 | Device type not found in unit control block (UCB) tables. |
17 | System or user abend occurred. |
18 | Partial data set information was obtained. |
19 | Data set resides on multiple volumes. Consider using the MULTIVOL keyword to obtain data set size information totaled across all volumes. |
20 | Device type not found in eligible device table (EDT). |
21 | Catalog error trying to locate the data set. |
22 | Volume not mounted. |
23 | Permanent I/O error on volume. |
24 | Data set not found. |
25 | Data set migrated to non-DASD device. |
26 | Data set on MSS (Mass Storage) device. |
27 | No volume serial is allocated to the data set. |
28 | The ddname must be one to eight characters. |
29 | Data set name or ddname must be specified. |
30 | Data set is not SMS-managed. |
31 | ISITMGD macro returned with bad return code and reason code. Return code and reason code can be found in message IKJ58431I, which is returned in variable &SYSMSGLVL2. |
32 | Unable to retrieve SMS information. DFSMS/MVS has incorrect level. |
33 | Unable to retrieve SMS information. DFSMS/MVS is not active. |
34 | Unable to retrieve SMS information. OPEN error. |
35 | Unexpected error from DFSMS/MVS internal service IGWFAMS. |
36 | Unexpected error from the SMS service module. |
37 | Unexpected error from DFSMS service IGGCSI00. |
Examples:
The following are some examples of using LISTDSI.
- To set variables with information about data set USERID.WORK.EXEC, use the LISTDSI function as
follows:
x = LISTDSI(work.exec) SAY 'Function code from LISTDSI is: ' x SAY 'The data set name is: ' sysdsname SAY 'The device unit on which the volume resides is:' sysunit SAY 'The record format is: ' sysrecfm SAY 'The logical record length is: ' syslrecl SAY 'The block size is: ' sysblksize SAY 'The allocation in space units is: ' sysalloc SAY 'Type of RACF protection is: ' sysracfa
Output from the example might be:Function code from LISTDSI is: 0 The data set name is: USERID.WORK.EXEC The device unit on which the volume resides is: 3380 The record format is: VB The logical record length is: 255 The block size is: 6124 The allocation in space units is: 33 Type of RACF protection is: GENERIC
- To retrieve information about the DD called APPLPAY, you can use LISTDSI as follows:
ddinfo = LISTDSI("applpay" "FILE")
- Suppose you want to retrieve information about a PDS called SYS1.APPL.PAYROLL, including
directory information. You do not want the PDS to be located through a catalog search, but have the
location determined by the allocation of the data set. You can specify LISTDSI as follows:
/* REXX program for .... */ ⋮ var1 = "'sys1.appl.payroll'" infod = "directory" ⋮ pdsinfo = LISTDSI(var1 infod "prealloc") ⋮ EXIT
In the example, the variable var1 was assigned the name of the PDS (SYS1.APPL.PAYROLL). Therefore, in the LISTDSI function call, var1 is not enclosed in quotation marks to allow for variable substitution. Similarly, the variable infod was assigned the valuedirectory
, so in the LISTDSI function, infod becomes the worddirectory
. The PREALLOC argument is enclosed in quotation marks to prevent any type of substitution. After the language processor evaluates the LISTDSI function, it results in the following function call being processed:LISTDSI('sys1.appl.payroll' directory prealloc)
- The LISTDSI function issues message IKJ56709I if a syntactically invalid data set name is passed
to the function. To prevent this message from being displayed, use the MSG('OFF') function.
dsname = "'ABCDEFGHIJ.XYZ'" /*syntactically invalid name, because a qualifier is longer than 8 characters */ msgval = MSG('OFF') /* save current MSG value and suppress messages */ x = LISTDSI(dsname) /* Retrieve data set information */ say 'Function Code returned by LISTDSI ==> ' x msgval = MSG(msgval) /* Restore MSG setting */ exit 0
- To use LISTDSI to set variables with information about a multivolume data set,
'BILL.WORK.MULTI01', use the LISTDSI function with the MULTIVOL operand as follows. Because the data
set may reside on multiple volumes, code the MULTIVOL keyword to obtain data set size information
aggregated across all volumes of the data set. SYSNUMVOLS returns the number of volumes allocated,
and SYSVOLUMES is a list of the volumes on which the data set is
allocated.
/* REXX - Test LISTDSI V2R1 example with MULYTIVOL usage */ /* */ /*********************************************************************/ /* To set variables with information about a possibly */ /* multivolume data set 'BILL.WORK.MULTI01', use the LISTDSI */ /* function as follows. Because the data set may be on multiple */ /* volumes, code the MULTIVOL keyword to obtain data set size */ /* information aggregated across volumes of the data set. */ /* SYSNUMVOLS returns the number of volumes allocated, and */ /* SYSVOLUMES is a list of the volumes on which the data set is */ /* allocated. */ /*********************************************************************/ x = LISTDSI('''BILL.WORK.MULTI01''' MULTIVOL) SAY 'Function code from LISTDSI is: ' x SAY 'The data set name is ....... : ' sysdsname SAY 'The device unit on which the volume resides is: ' sysunit SAY 'The data set organization is : ' sysdsorg SAY 'The record format is ....... : ' sysrecfm SAY 'The logical record length is : ' syslrecl SAY 'The block size is .......... : ' sysblksize SAY 'Type of RACF protection is . : ' sysracfa SAY SAY 'The space unit of allocation is ......... : ' sysunits SAY 'The primary allocation in space units is. : ' sysprimary SAY 'The secondary allocation in space units is: ' sysseconds SAY 'The space allocated in space units ...... : ' sysalloc SAY 'The spaced used in space units is ....... : ' sysused SAY 'The number of extents allocated is ...... : ' sysextents SAY 'The number of extents in use is ......... : ' sysusedextents SAY 'The first (or possibly only volume) is .. : ' sysvolume SAY SAY 'Number of volumes on which data set resides is: ' sysnumvols if sysnumvols > 1 then SAY 'Data Set is on multiple vols (vollist) ... :<'sysvolumes'>' else SAY 'Data set is on a single vol: ............. :<'sysvolumes'>' /*****************************************************************/ /* Explain any function error code */ /*****************************************************************/ IF x ^= 0 then /* Report on any non-0 function code */ do say say '--------------------------------------' say 'LISTDSI Function Code is : ' x say 'LISTDSI Reason Code is : ' sysreason say 'Error messages returned : ' say '==>' SYSMSGLVL1 say '==>' SYSMSGLVL2 say '--------------------------------------' end exit 0 Output from this example might be: Function code from LISTDSI is: 0 The data set name is ....... : BILL.WORK.MULTI01 The device unit on which the volume resides is: 3390 The data set organization is : PS The record format is ....... : FB The logical record length is : 4160 The block size is .......... : 20800 Type of RACF protection is . : GENERIC The space unit of allocation is ......... : TRACK The primary allocation in space units is. : 3 The secondary allocation in space units is: 5 The space allocated in space units ...... : 193 The spaced used in space units is ....... : 162 The number of extents allocated is ...... : 39 The number of extents in use is ......... : 33 The first (or possibly only volume) is .. : SL2B07 Number of volumes on which data set resides is: 3 Data Set is on multiple vols (vollist) ... :<SL2B07 SL2B0C SL2B05>
- In the previous example with a multivolume data set, if you just want to retrieve
information about the part of the data set on the second volume, "SL2BOC", you could code the
LISTDSI call in the example with the VOLUME operand, while omitting the MULTIVOL operand. Because
information about a specific volume is requested, SYSNUMVOLS returns 1 (for the requested volume),
and SYSVOLUME and SYSVOLUMES both return just the specified volume
name.
With this invocation in the above exec: x = LISTDSI('''BILL.WORK.MULTI01''' 'VOLUME(SL2B0C)') The output might look something like the following : Function code from LISTDSI is: 0 The data set name is ....... : BILL.WORK.MULTI01 The device unit on which the volume resides is: 3390 The data set organization is : PS The record format is ....... : FB The logical record length is : 4160 The block size is .......... : 20800 Type of RACF protection is . : GENERIC The space unit of allocation is ......... : TRACK The primary allocation in space units is. : 5 The secondary allocation in space units is: 5 The space allocated in space units ...... : 80 The spaced used in space units is ....... : 80 The number of extents allocated is ...... : 16 The number of extents in use is ......... : 16 The first (or possibly only volume) is .. : SL2B0C Number of volumes on which data set resides is: 1 Data set is on a single vol: ............. :<SL2B0C>
Special Considerations
LISTDSI considers file names starting with ‘SYS’ followed by five digits to be system-generated file names. If you use LISTDSI to obtain information about a data set that was preallocated multiple times using file names starting with ‘SYS’ followed by five digits, an existing file may be freed.