ADMIN_DS_WRITE stored procedure

The SYSPROC.ADMIN_DS_WRITE stored procedure writes either text or binary records that are passed in a global temporary table to data sets or their members. You can write to a physical sequential (PS) data set, a partitioned data set (PDS) member, a partitioned data set extended (PDSE) member, or a generation data set (GDS).

This stored procedure can either append or replace an existing PS data set, PDS or PDSE member, or GDS. Also, this stored procedure can create a new PS data set, PDS or PDSE data set or member, or a new GDS for an existing generation data group (GDG) as needed. This stored procedure supports only data sets with LRECL=80 and RECFM=FB.

Environment

Begin general-use programming interface information.

The load module for ADMIN_DS_WRITE, DSNADMDW, must reside in an APF-authorized library. ADMIN_DS_WRITE 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 DSNADMDW
Ownership of the package
PACKADM authority for the package collection
SYSADM authority

The ADMIN_DS_WRITE caller also needs authorization from an external security system, such as RACF®, in order to write to 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_WRITE--(--data-type,------------------>

>--data-set-name,--member-name,--processing-option,------------->

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

Option descriptions

This stored procedure takes the following input options:

data-type

Specifies the type of data to be saved. Possible values are:

1: Text data
2: Binary data

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

data-set-name

Specifies the name of the data set, GDG that contains the GDS, or library that contains the member, to be written to. Possible values are:

PS data set name: Name of the PS data set, if writing to a PS data set.
GDG name: Name of the GDG, if writing to a GDS within this GDG.
PDS or PDSE name: Name of the PDS or PDSE, if writing to a member that belongs to this library.

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

member-name

Specifies the relative generation number of the GDS, if writing to a GDS, or the name of the PDS or PDSE member, if writing to a PDS or PDSE member. Otherwise, a blank character. Possible values are:

GDS relative generation number: Relative generation number of a GDS, if writing to a GDS. For example: -1, 0, +1
PDS or PDSE member name: Name of the PDS or PDSE member, if writing to a library member.
blank: In all other cases, blank.

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

processing-option

Specifies the type of operation. Possible values are:

R: Replace
A: Append
NM: New member
ND: New PS, PDS, PDSE, or GDS data set

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

dump-option

Specifies whether to use the DB2® standard dump facility to dump the information necessary for problem diagnosis when an SQL error has occurred or when a call to the IBM® routine IEFDB476 to get messages about an unsuccessful SVC 99 call failed.

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

Additional input

In addition to the input parameters, the stored procedure reads records to be written to a file from a created global temporary table. If the data to be written is text data, then the stored procedure reads records from SYSIBM.TEXT_REC_INPUT. If the data is binary data, then the stored procedure reads records from the created global temporary table SYSIBM.BIN_REC_INPUT.

The following table shows the format of the created global temporary table SYSIBM.TEXT_REC_INPUT containing text records to be saved:

Table 1. Additional input for text data for the ADMIN_DS_WRITE stored procedure
Column name	Data type	Contents
ROWNUM	INTEGER	Sequence number of the table row, from 1 to `n`.
TEXT_REC	CHAR(80)	Text record to be saved.

The following table shows the format of the created global temporary table SYSIBM.BIN_REC_INPUT containing binary records to be saved:

Table 2. Additional input for binary data for the ADMIN_DS_WRITE stored procedure
Column name	Data type	Contents
ROWNUM	INTEGER	Sequence number of the table row, from 1 to `n`.
BINARY_REC	VARCHAR(80) FOR BIT DATA	Binary record to be saved.

Example

The following C language sample shows how to invoke ADMIN_DS_WRITE:

 #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_WRITE parameters                              */
   long int    datatype;               /* Data type                  */
   char        dsname[45];             /* Data set name or GDG       */
   char        mbrname[9];             /* Library member name,       */
                                       /* generation # (-1, 0, +1),  */
                                       /* or blank                   */
   char        procopt[3];             /* Processing option          */
   char        dumpopt[2];             /* Dump option                */
   long int    retcd;                  /* Return code                */
   char        errmsg[1332];           /* Error message              */

   /* Temporary table SYSIBM.TEXT_REC_INPUT columns                  */
   long int    rownum;                 /* Sequence number of the     */
                                       /* table row                  */
   char        textrec[81];            /* Text record                */
   EXEC SQL END DECLARE SECTION;

   /******************************************************************/
   /* Create the records to be saved                                 */
   /******************************************************************/
   char dsrecord[12][50] = {
   "//IEBCOPY  JOB ,CLASS=K,MSGCLASS=H,MSGLEVEL=(1,1)",
   "//STEP010 EXEC PGM=IEBCOPY",
   "//SYSPRINT DD SYSOUT=*",
   "//SYSUT3 DD SPACE=(TRK,(1,1)),UNIT=SYSDA",
   "//SYSUT4 DD SPACE=(TRK,(1,1)),UNIT=SYSDA",
   "//*",
   "//DDI1 DD DSN=USER.DEV.LOADLIB1,DISP=SHR",
   "//DDO1 DD DSN=USER.DEV.LOADLIB2,DISP=SHR",
   "//SYSIN DD *",
   " COPY OUTDD=DDO1,INDD=DDI1",
   "/*",
   "//*"
   } ;
   int i = 0;                          /* Loop counter               */

   /******************************************************************/
   /* Assign the values to input parameters to create a new          */
   /* partitioned data set and member                                */
   /******************************************************************/
   datatype = 1;
   strcpy(dsname, "USER.DATASET.PDS");
   strcpy(mbrname, "MEMBER01");
   strcpy(procopt, "ND");
   strcpy(dumpopt, "N");

   /******************************************************************/
   /* Clear temporary table SYSIBM.TEXT_REC_INPUT                    */
   /******************************************************************/
   EXEC SQL DELETE FROM SYSIBM.TEXT_REC_INPUT;

   /******************************************************************/
   /* Insert the records to be saved in the new library member       */
   /* into the temporary table SYSIBM.TEXT_REC_INPUT                 */
   /******************************************************************/
   for (i = 0; i < 12; i++)
   {
     rownum = i+1;
     strcpy(textrec, dsrecord[i]);
     EXEC SQL INSERT INTO SYSIBM.TEXT_REC_INPUT
                     ( ROWNUM, TEXT_REC)
              VALUES (:rownum, :textrec);
   };

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

   return(retcd);
 }

Output

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

return-code
message

End general-use programming interface information.