Use the LISTDSI statement to obtain information about a data set that is available on DASD. The LISTDSI statement can retrieve information about a data set's allocation, protection, and directory, and store the information in CLIST variables.

The CLIST 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. It can also use the LISTDSI information as input to the ALLOCATE command, 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, the CLIST stores only the volume serial ID (in variable &SYSVOLUME), the generic device type (in variable &SYSUNIT), and the data set organization (in variable &SYSDSORG). The CLIST sets all other LISTDSI variables to question marks.

If you use LISTDSI to retrieve information about a multiple volume data set, the CLIST stores information for the first volume only. Similarly, if you specify a file name or the PREALLOC parameter and you have other data sets allocated to the same file name, then the system might not retrieve information for the data set you wanted.

When you use LISTDSI to obtain information about a concatenation of more than one data set, LISTDSI returns information only about the first data set in the concatenation. Likewise, if the file name identifies a multi-volume data set, LISTDSI can return information only about the first volume, and is not able to detect that the data set 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. 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.

To suppress TSO/E messages issued by the LISTDSI statement, use the CONTROL NOMSG statement. For information about the CONTROL statement, see CONTROL statement.

>>-+--------+--LISTDSI------------------------------------------>
   '-label:-'            

                                             .-NODIRECTORY-.   
>--+-data_set_name--+-------------------+-+--+-DIRECTORY---+---->
   |                +-VOLUME(serial_id)-+ |                    
   |                '-PREALLOC----------' |                    
   '-file_name--FILE----------------------'                    

   .-NOSMSINFO-.                .-NOMULTIVOL-.  .-RACF---.   
>--+-----------+--+----------+--+------------+--+--------+-----><
   '-SMSINFO---'  +-RECALL---+  '-MULTIVOL---'  '-NORACF-'   
                  '-NORECALL-'                               

label

A name the CLIST can reference in a GOTO statement to branch to this LISTDSI statement. label is one-to-31 alphanumeric characters, beginning with an alphabetic character.

data_set_name | file_name

data_set_name

The name of the data set about which you want to retrieve information.

file_name

The name of an allocated file (ddname) about which you want to retrieve information.

VOLUME(serial_id) | PREALLOC

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.

If you do not specify either VOLUME or PREALLOC, the system locates the data set through catalog search.

If you specify a file_name, LISTDSI ignores the VOLUME and PREALLOC parameters.

FILE

specifies that you provided a file_name instead of a data_set_name. If you do not specify FILE, LISTDSI assumes that you provided a data set name.

DIRECTORY | NODIRECTORY

DIRECTORY

indicates that you want directory information for a partitioned data set (PDS or PDSE).

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 for a partitioned data set. If you do not require directory information, NODIRECTORY can significantly speed up processing. NODIRECTORY is the default.

SMSINFO | NOSMSINFO

indicates whether you want SMS information about an SMS-managed data set, like the type of data set, the used space, the data -, storage -, and management class names. See also Table 1.

SMSINFO

indicates that you want SMS information about data_set_name or file_name. Neither data_set_name nor file_name may refer to a VSAM index or a data component.

If the specified data set is not managed by SMS, LISTDSI continues, but no SMS information is provided in the corresponding CLIST 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.

RECALL | NORECALL

RECALL

indicates that you want to recall a data set migrated by HSM. The system recalls the data set regardless of its level of migration or the type of device it has been migrated to.

NORECALL

indicates that you do not want to recall a data set. If the data set has been migrated, the system displays 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).

MULTIVOL | 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 | NORACF

indicates whether a check for RACF authority is done or not. If not, the data set will not be opened by LISTDSI, for example, to read directory information.

PROC 0
SET DSNAME = ABCDEFGHIJ.XYZ       /* Syntactically not valid name,
                                  /* because a qualifier is longer
                                  /* than 8 characters
CONTROL NOMSG                     /* Set OFF to suppress any LISTDSI
                                  /* TSO/E messages
LISTDSI &DSNAME                   /* Obtain data set information
WRITE Return code from LISTDSI is ==> &LASTCC
EXIT CODE(0)