ADMIN_DS_SEARCH stored procedure

The SYSPROC.ADMIN_DS_SEARCH stored procedure determines if certain data sets are cataloged, or if a library member of a cataloged data set exists. You can search for a physical sequential (PS) data set, a partitioned data set (PDS), a partitioned data set extended (PDSE), a generation data group (GDG), a generation data set (GDS), or the library member of a cataloged PDS or PDSE.

Environment

Begin general-use programming interface information.

The load module for ADMIN_DS_SEARCH, DSNADMDE, must reside in an APF-authorized library. ADMIN_DS_SEARCH 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:

The EXECUTE privilege on the ADMIN_DS_SEARCH stored procedure
Ownership of the stored procedure
SYSADM authority

The ADMIN_DS_SEARCH 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_SEARCH--(--data-set-name,------------->

>--member-name,--dump-option,--data-set-exists,--return-code,--->

>--message--)--------------------------------------------------><

Option descriptions

data-set-name

Specifies the name of a PS data set, PDS, PDSE, GDG or GDS.

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

member-name

Specifies the name of a PDS or PDSE member. Set this parameter to a blank character if you only want to check the existence of the PDS or PDSE.

This is an input parameter of type CHAR(8) 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 occurred:

A call to the IBM® routine IEFDB476 to get messages about an unsuccessful SVC 99 call failed.
Load IDCAMS program 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.

data-set-exists

Indicates whether a data set or library member exists or not. Possible values are:

-1: Call did not complete successfully. Unable to determine if data set or member exists.
0: Data set or member was found
1: Data set not found
2: PDS or PDSE member not found

This is an output parameter of type INTEGER.

return-code

Provides the return code from the stored procedure. Possible values are:

0: The call completed successfully.
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 IDCAMS messages if return-code is 0. Otherwise, contains messages describing the error encountered by the stored procedure. The first messages are generated by the stored procedure and messages that are generated by z/OS might follow these first messages.

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

Example

The following C language sample shows how to invoke ADMIN_DS_SEARCH:

 #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_SEARCH parameters                             */
   char        dsname[45];             /* Data set name or GDG       */
   char        mbrname[9];             /* Library member name        */
   char        dumpopt[2];             /* Dump option                */
   long int    exist;                  /* Data set or library member */
                                       /* existence indicator        */
   long int    retcd;                  /* Return code                */
   char        errmsg[1332];           /* Error message              */
   EXEC SQL END DECLARE SECTION;

   /******************************************************************/
   /* Assign values to input parameters to determine whether a       */
   /* library member exists or not                                   */
   /******************************************************************/
   strcpy(dsname, "USER.DATASET.PDS");
   strcpy(mbrname, "MEMBER0A");
   strcpy(dumpopt, "N");

   /******************************************************************/
   /* Call stored procedure SYSPROC.ADMIN_DS_SEARCH                  */
   /******************************************************************/
   EXEC SQL CALL SYSPROC.ADMIN_DS_SEARCH
                        (:dsname, :mbrname, :dumpopt,
                         :exist,  :retcd,   :errmsg);

   return(retcd);
 }

Output

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

data-set-exists
return-code
message

End general-use programming interface information.