ADMIN_COMMAND_UNIX stored procedure

The SYSPROC.ADMIN_COMMAND_UNIX stored procedure executes a z/OS® UNIX System Services command and returns the output.

Environment

Begin general-use programming interface information.

ADMIN_COMMAND_UNIX runs in a WLM-established stored procedure address space.

The load module for ADMIN_COMMAND_UNIX, DSNADMCU, must be program controlled if the BPX.DAEMON.HFSCTL FACILITY class profile has not been set up. For information on how to define DSNADMCU to program control, see installation job DSNTIJRA.

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 DSNADMCU
Ownership of the package
PACKADM authority for the package collection
SYSADM authority

The user specified in the user-ID input parameter of the SQL CALL statement must have the appropriate authority to execute the z/OS UNIX System Services command.

Syntax

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

>>-CALL--SYSPROC.ADMIN_COMMAND_UNIX--(--+-user-ID-+-,----------->
                                        '-NULL----'     

>--+-password-+-,--USS-command,--------------------------------->
   '-NULL-----'                   

>--+-output-layout---------------------------------------------------+-,-->
   | .-OUTMODE=BLK-------------------------------------------------. |     
   '-+-NULL--------------------------------------------------------+-'     
     +-OUTMODE=LINE------------------------------------------------+       
     '-Start of changeDEFAULT_HOME_DIR=home_directoryEnd of change-'       

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

Option descriptions

user-ID

Specifies the user ID under which the z/OS UNIX System Services command is issued.

If user-ID is NULL, password must also be NULL. If the user-ID and password values are NULL, the login process uses the primary authorization ID of the process.

You can specify NULL for this parameter in the following circumstances:

The operating system is any supported level, and the authorization ID that is associated with the stored procedure address space has daemon authority.
The operating system is z/OS Version 1 Release 13 or later, and the authorization ID that is associated with the stored procedure address space does not have daemon authority but is authorized to the BPX.SRV.userid SURROGAT class profile, where 'userid' is the authorization ID of the stored procedure. In this case, you must install APAR OA36062. For more information about how the RACF® security administrator can authorize the authorization ID that is associated with the stored procedure address space to a SURROGAT class profile, see Defining servers to process users without passwords or password phrases.
Daemon authority is given to any superuser that is permitted to the BPX.DAEMON FACILITY class profile. If the BPX.DAEMON FACILITY class profile is not defined, all superusers have daemon authority.

This is an input parameter of type VARCHAR(128).

password

Specifies the password associated with the input parameter user-ID.

The value of password is passed to the stored procedure as part of payload, and is not encrypted. It is not stored in dynamic cache when parameter markers are used.

If password is NULL, user-ID must also be NULL. If the user-ID and password values are NULL, the login process uses the primary authorization ID of the process.

You can specify NULL for this parameter in the following circumstances:

The operating system is any supported level, and the authorization ID that is associated with the stored procedure address space has daemon authority.
The operating system is z/OS Version 1 Release 13 or later, and the authorization ID that is associated with the stored procedure address space does not have daemon authority but is authorized to the BPX.SRV.userid SURROGAT class profile, where 'userid' is the authorization ID of the stored procedure. In this case, you must install APAR OA36062.

This is an input parameter of type VARCHAR(24).

USS-command

Specifies the z/OS UNIX System Services command to be executed.

This is an input parameter of type VARCHAR(32704) and cannot be null.

output-layout

Specifies how the output from the z/OS UNIX System Services command is returned and the default home directory of the specified user-ID.

The output from the z/OS UNIX System Services command is a multi-line message. Possible values are:

OUTMODE=LINE: Each line is returned as a row in the result set.
OUTMODE=BLK: The lines are blocked into 32677 blocks and each block is returned as a row in the result set.

You specify the default home directory for user-ID as follows:

DEFAULT_HOME_DIR=home_directory

If the home directory of the specified user-ID does not exist, or user-ID does not have a home directory, the SYSPROC.ADMIN_COMMAND_UNIX stored procedure runs the command under the default home directory that you specify.

The maximum length of home_directory is 1007.

If you need to specify both OUTMODE and DEFAULT_HOME_DIR, consider the following examples:

OUTMODE=LINE,DEFAULT_HOME_DIR=/tmp

DEFAULT_HOME_DIR=/tmp,OUTMODE=LINE

If a null or empty string is provided, the default option OUTMODE=BLK is used.

This is an input parameter of type VARCHAR(1024).

return-code

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

0: The call completed successfully.
4: The stored procedure used the default home directory.
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® 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_COMMAND_UNIX:

#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_COMMAND_UNIX parameters                          */
   char        userid[129];            /* User ID                    */
   short int   ind_userid;             /* Indicator variable         */
   char        password[25];           /* Password                   */
   short int   ind_password;           /* Indicator variable         */
   char        command[32705];         /* USS command                */
   short int   ind_command;            /* Indicator variable         */
   char        layout[1025];           /* Command output layout      */
   short int   ind_layout;             /* Indicator variable         */
   long int    retcd;                  /* Return code                */
   short int   ind_retcd;              /* Indicator variable         */
   char        errmsg[1332];           /* Error message              */
   short int   ind_errmsg;             /* Indicator variable         */

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

   /* Result set row                                                 */
   long int    rownum;                 /* Sequence number of the     */
                                       /* table row                  */
   char        text[32678];            /* A row in USS command output*/
   EXEC SQL END DECLARE SECTION;

   /******************************************************************/
   /* Assign values to input parameters to execute a USS command     */
   /* Set the indicator variables to 0 for non-null input parameters */
   /* Set the indicator variables to -1 for null input parameters    */
   /******************************************************************/
   strcpy(userid, "USRT001");
   ind_userid = 0;
   strcpy(password, "N1CETEST");
   ind_password = 0;
   strcpy(command, "ls");
   ind_command = 0;
   ind_layout = -1;

   /******************************************************************/
   /* Call stored procedure SYSPROC.ADMIN_COMMAND_UNIX               */
   /******************************************************************/
   EXEC SQL CALL SYSPROC.ADMIN_COMMAND_UNIX
                        (:userid    :ind_userid,
                         :password  :ind_password,
                         :command   :ind_command,
                         :layout    :ind_layout,
                         :retcd     :ind_retcd,
                         :errmsg    :ind_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_COMMAND_UNIX;

     /* 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 :rownum, :text;
     while(SQLCODE==0)
     {
       EXEC SQL FETCH C1 INTO :rownum, :text;
     }

     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 z/OS UNIX System Services command output messages.

The following table shows the format of the result set returned in the created global temporary table SYSIBM.USS_CMD_OUTPUT:

Table 1. Result set row for ADMIN_COMMAND_UNIX result set
Column name	Data type	Contents
ROWNUM	INTEGER	Sequence number of the table row, from 1 to `n`
TEXT	VARCHAR(32677)	A block of text or a line from the output messages of a z/OS UNIX System Services command

End general-use programming interface information.