LISTDSI returns one of the following function codes that replace the function call, and retrieves information about a data set's allocation, protection, and directory and stores it in specific variables. Table 1 shows the function codes that replace the function call.

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.

The variables in which LISTDSI stores data set information are described in Table 2.

To suppress TSO/E messages issued by the LISTDSI function, use the MSG("OFF") function. For information about the MSG function, see MSG.

You can use the LISTDSI function only in REXX execs that run in the TSO/E address space.

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

Variables that LISTDSI sets

Table 2 describes the variables that LISTDSI sets. For VSAM data sets, only the variables SYSDSNAME, SYSEATTR, SYSEADSCB, SYSVOLUME, SYSUNIT, and SYSDSORG are accurate; all other variables are set to question marks.

Reason Codes

Reason codes from the LISTDSI function appear in variable SYSREASON. Table 3 shows the LISTDSI reason codes. With each reason code the REXX variable SYSMSGLVL2 is set to message IKJ584nnI, where nn is the reason code. These messages are described in z/OS TSO/E Messages.

Examples:

The following are some examples of using LISTDSI.

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

2. To retrieve information about the DD called APPLPAY, you can use LISTDSI as follows:

   ddinfo = LISTDSI("applpay" "FILE")

3. 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 value "directory", so in the LISTDSI function, infod becomes the word "directory". 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)

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

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

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