ADMIN_DS_LIST stored procedure

The SYSPROC.ADMIN_DS_LIST stored procedure returns a list of data set names, a generation data group (GDG), a partitioned data set (PDS) member, a partitioned data set extended (PDSE) member, or generation data sets of a GDG.

Environment

Begin general-use programming interface information.

The load module for ADMIN_DS_LIST, DSNADMDL, must reside in an APF-authorized library. ADMIN_DS_LIST runs in a WLM-established stored procedures address space, and all libraries in this WLM procedure STEPLIB DD concatenation must be APF-authorized.

Authorization

To execute the CALL statement, the owner of the package or plan that contains the CALL statement must have one or more of the following privileges on each package that the stored procedure uses:

  • The EXECUTE privilege on the package for DSNADMDL
  • Ownership of the package
  • PACKADM authority for the package collection
  • SYSADM authority

The ADMIN_DS_ LIST caller also needs authorization from an external security system, such as RACF®, in order to perform the requested operation on an z/OS® data set resource.

Syntax

The following syntax diagram shows the SQL CALL statement for invoking this stored procedure:

>>-CALL--SYSPROC.ADMIN_DS_LIST--(--data-set-name,--------------->

>--list-members,--list-generations,--max-results,--------------->

>--dump-option,--return-code,--message--)----------------------><

Option descriptions

data-set-name
Start of changeSpecifies the data set name. You can use masking characters, except for when you list members of a PDS/PDSE (list-members = 'Y') or the generation data sets of a GDG (list-generations = 'Y'). For example: USER.* or USER.A*CD. In addition, the specified data set name cannot start with a masking character.

If no masking characters are used, only one data set will be listed.

This is an input parameter of type CHAR(44) and cannot be null.

End of change
list-members
Specifies whether to list PDS or PDSE members. Possible values are:
Y
List members. Only set to Y when data-set-name is a fully qualified PDS or PDSE.
N
Do not list members.

This is an input parameter of type CHAR(1) and cannot be null.

list-generations
Specifies whether to list generation data sets. Possible values are:
Y
List generation data sets. Only set to Y when data-set-name is a fully qualified GDG.
N
Do not list generation data sets.

This is an input parameter of type CHAR(1) and cannot be null.

max-results
Specifies the maximum number of result set rows. This option is applicable only when both list-members and list-generations are 'N'.

This is an input parameter of type INTEGER and cannot be null.

dump-option
Specifies whether to use the DB2® standard dump facility to dump the information necessary for problem diagnosis when any of the following errors occur:
  • SQL error.
  • A call to the IBM® routine IEFDB476 to get messages about an unsuccessful SVC 99 call failed.
  • Load Catalog Search Interface module error.

Possible values are:

Y
Generate a dump.
N
Do not generate a dump.

This is an input parameter of type CHAR(1) and cannot be null.

return-code
Provides the return code from the stored procedure. Possible values are:
0
The call completed successfully.
4
Processing completed, but some data sets received catalog management errors. Data set information is returned for the data sets that did not receive catalog management errors. Error information is returned for the data sets that received catalog management errors.
12
The call did not complete successfully. The message output parameter contains messages describing the error.

This is an output parameter of type INTEGER.

message
Contains messages describing the error encountered by the stored procedure. If no error occurred, then no message is returned.

The first messages in this area are generated by the stored procedure. Messages that are generated by DB2 or by z/OS might follow the first messages.

This is an output parameter of type VARCHAR(1331).

Example

The following C language sample shows how to invoke ADMIN_DS_LIST:

 #pragma csect(CODE,"SAMDLPGM")
 #pragma csect(STATIC,"PGMDLSAM")
 #pragma runopts(plist(os))
 
 #include    <stdio.h>
 #include    <stdlib.h>
 #include    <string.h>

/******************** DB2 SQL Communication Area ********************/
 EXEC SQL INCLUDE SQLCA;

 int main( int argc, char *argv[] )    /* Argument count and list    */
 {
   /****************** DB2 Host Variables ****************************/
   EXEC SQL BEGIN DECLARE SECTION;

   /* SYSPROC.ADMIN_DS_LIST parameters                               */
   char        dsname[45];             /* Data set name or filter    */
   char        listmbr[2];             /* List library members       */
   char        listgds[2];             /* List GDS                   */
   long int    maxresult;              /* Maximum result set rows    */
   char        dumpopt[2];             /* Dump option                */
   long int    retcd;                  /* Return code                */
   char        errmsg[1332];           /* Error message              */

   /* Result set locators                                            */
   volatile SQL TYPE IS RESULT_SET_LOCATOR *rs_loc1;

   /* Result set row                                                 */
   char        dsnamer[45];            /* Data set name,             */
                                       /* library member name, or    */
                                       /* absolute generation number */
   long int    createyr;               /* Create year                */
   long int    createday;              /* Create day                 */
   long int    type;                   /* Data set type              */
   char        volume[7];              /* Data set volume            */
   long int    primaryext;             /* Size of first extent       */
   long int    secondext;              /* Size of secondary extent   */
   char        measure[10];            /* Extent unit of measurement */
   long int    extinuse;               /* Current allocated extents  */
   char        dasduse[9];             /* DASD usage                 */
   char        harba[7];               /* High allocated RBA         */
   char        hurba[7];               /* High used RBA              */
   EXEC SQL END DECLARE SECTION;

   char * ptr;
   int i = 0;
   /******************************************************************/
   /* Assign values to input parameters to list all members of       */
   /* a library                                                      */
   /******************************************************************/
   strcpy(dsname, "USER.DATASET.PDS");
   strcpy(listmbr, "Y");
   strcpy(listgds, "N");
   maxresult = 1;
   strcpy(dumpopt, "N");

   /******************************************************************/
   /* Call stored procedure SYSPROC.ADMIN_DS_LIST                    */
   /******************************************************************/
   EXEC SQL CALL SYSPROC.ADMIN_DS_LIST
                        (:dsname,  :listmbr, :listgds, :maxresult,
                         :dumpopt, :retcd,   :errmsg);

   /******************************************************************/
   /* Retrieve result set when the SQLCODE from the call is +446,    */
   /* which indicates that result sets were returned                 */
   /******************************************************************/
   if (SQLCODE == +466)               /* Result sets were returned   */
   {
     /* Establish a link between the result set and its locator      */
     EXEC SQL ASSOCIATE LOCATORS (:rs_loc1)
              WITH PROCEDURE SYSPROC.ADMIN_DS_LIST;

     /* Associate a cursor with the result set                       */
     EXEC SQL ALLOCATE C1 CURSOR FOR RESULT SET :rs_loc1;

     /* Perform fetches using C1 to retrieve all rows from the       */
     /* result set                                                   */
     EXEC SQL FETCH C1 INTO :dsnamer, :createyr, :createday,
                            :type, :volume, :primaryext,
                            :secondext, :measure, :extinuse,
                            :dasduse, :harba, :hurba;

     while(SQLCODE==0)
     {
       EXEC SQL FETCH C1 INTO :dsnamer, :createyr, :createday,
                              :type, :volume, :primaryext,
                              :secondext, :measure, :extinuse,
                              :dasduse, :harba, :hurba;
     }

     EXEC SQL CLOSE C1;
   }

   return(retcd);
 }

Output

This stored procedure returns the following output parameters, which are described in Option descriptions:

  • return-code
  • message

In addition to the preceding output, the stored procedure returns one result set that contains the list of data sets, GDGs, PDS or PDSE members, or generation data sets that were requested.

The following table shows the format of the result set:

Table 1. Result set row for ADMIN_DS_LIST result set
Column name Data type Contents
DSNAME VARCHAR(44)
  • Data set name, if list-members is "N" and list-generations is "′N".
  • Member name, if list-members is "Y".
  • Absolute generation number (of the form G0000V00) from a generation data set name, if list-generations is "Y".
CREATE_YEAR INTEGER The year that the data set was created. Not applicable for member and VSAM cluster.
CREATE_DAY INTEGER The day of the year that the data set was created, as an integer in the range of 1 to 366 where 1 represents January 1). Not applicable for member and VSAM cluster.
TYPE INTEGER Type of data set. Possible values are:
0
Unknown type of data set
1
PDS data set
2
PDSE data set
3
Member of PDS or PDSE
4
Physical sequential data set
5
Generation data group
6
Generation data set
8
VSAM cluster
9
VSAM data component
10
VSAM index component
VOLUME CHAR(6) Volume where data set resides. Not applicable for member and VSAM cluster.
PRIMARY_EXTENT INTEGER Size of first extent. Not applicable for member and VSAM cluster.
SECONDARY_EXTENT INTEGER Size of secondary extent. Not applicable for member and VSAM cluster.
MEASUREMENT_UNIT CHAR(9) Unit of measurement for first extent and secondary extent. Possible values are:
  • BLOCKS
  • BYTES
  • CYLINDERS
  • KB
  • MB
  • TRACKS
Not applicable for member and VSAM cluster.
EXTENTS_IN_USE INTEGER Current allocated extents. Not applicable for member and VSAM cluster.
DASD_USAGE CHAR(8) FOR BIT DATA Disk usage. For VSAM data and VSAM index only.
HARBA CHAR(6) FOR BIT DATA High allocated RBA. For VSAM data and VSAM index only.
HURBA CHAR(6) FOR BIT DATA High used RBA. For VSAM data and VSAM index only.
ERRMSG VARCHAR(256)

An error message that explains the first data set-related failure that was encountered by the stored procedure while gathering the attributes of a data set. Some possible error messages are DSNA661I, DSNA662I, and DSNA635I.

If an error did not occur while gathering data set attributes, this column is blank.

When a data set spans more than one volume, one row is returned for each volume that contains a piece of the data set. The VOLUME, EXTENTS_IN_USE, DASD_USAGE, HARBA, and HURBA columns reflect information for the specified volume.

If a data set entry error is encountered, the ADMIN_DS_LIST stored procedure returns the data set that caused the error in the result set, along with data sets that did not have errors. In the result set, the attribute columns for the data set that caused the error are set to specific values, as shown in the following table.

Table 2. Values of data set attributes when an error is encountered
Attribute Value
CREATE_YEAR 0
CREATE_DAY 0
TYPE 0
VOLUME blank
PRIMARY_EXTENT -1
SECONDARY_EXTENT -1
MEASUREMENT_UNIT blank
EXTENTS_IN_USE -1
DASD_USAGE
-1
(x'FFFFFFFFFFFFFFFF')
HARBA
-1
(x'FFFFFFFFFFFF')
HURBA
-1
(x'FFFFFFFFFFFF')

End general-use programming interface information.