ADMIN_COMMAND_MVS stored procedure

Environment

The load module for the ADMIN_COMMAND_MVS stored procedure, DSNADMCM, must reside in an APF-authorized library. The ADMIN_COMMAND_MVS stored procedure runs in a WLM-established stored procedures address space, and all of the libraries that are specified in the STEPLIB DD statement 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 stored procedure
• Ownership of the stored procedure
• SYSADM authority

ADMIN_COMMAND_MVS uses an extended MCS console to issue the requested command.

The caller of ADMIN_COMMAND_MVS™ must have READ access to the MVS.MCSOPER.* or MVS.MCSOPER.xxxxxxxx (where xxxxxxxx is the name of the extended console) resource profile of the RACF® OPERCMDS class. By default, unless overwritten by CONSNAME which is specified in the subparameters input parameter of ADMIN_COMMAND_MVS, the name of the extended MCS console is DSNADMCM. If MVS.MCSOPER.xxxxxxxx exists, the ADMIN_COMMAND_MVS caller must have READ access to this profile. Otherwise, the caller must have READ access to MVS.MCSOPER.*.

In the OPERPARM segment of the extended MCS console's user profile (defined in a security product, such as RACF), specify the following console attributes:

• STORAGE= 512 or higher
• AUTH= ALL
• UD= NO
• HC= NO
• INTIDS= NO
• UNKNIDS= NO

You must also set the ROUTCODE, LEVEL, and MSCOPE console attributes. The attributes that you specify depend on the type of command:

START DB2, STOP DB2, DISPLAY WLM, LIST COPYPOOL, or QUERY COPYPOOL commands

Specify:

• ROUTCODE=NONE
• LEVEL=NB
• MSCOPE=*

DUMP command

Specify:

• ROUTCODE=ALL
• LEVEL=NB ALL
• MSCOPE=*

STOP DB2 command when DB2 is already stopping

Specify:

• ROUTCODE=ALL
• LEVEL=NB ALL
• MSCOPE=*ALL

Important: Specify ROUTCODE=ALL and MSCOPE=*ALL only when you anticipate that DB2 is already stopping when the STOP DB2 command is issued by ADMIN_COMMAND_MVS, and plan to increase the STORAGE value in these cases.

If the OPERPARM segment of the extended MCS console's user profile is not defined, default values are applied for all console attributes, except for the following attributes:

• STORAGE=512
• AUTH=ALL
• LEVEL=NB
• MSCOPE=*

For more information about controlling attributes for users of extended MCS consoles, see Defining console attributes for extended MCS consoles .

The extended MCS console must be authorized to execute the requested command.

Option descriptions

type

Specifies the type of command to be issued.

Valid values are:

• HSM
• DB2
• DUMP
• WLM

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

command_prefix

Specifies the command prefix that identifies which DB2 subsystem to direct the command to.

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

You cannot specify null for this parameter if the type parameter is set to DB2.

remote_system

Specifies the z/OS® system to which the DB2 command is to be routed.

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

You cannot specify null for this parameter if both of the following conditions apply:

• DB2 is the type parameter
• The DB2 command will be routed to a z/OS system that is different from the system where the stored procedure is executing

jobname

Specifies the name of the batch job or started task to be modified.

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

You cannot specify null for this parameter if HSM is the type parameter.

command

Specifies the command to be executed.

Valid values depend on the value of the type parameter.

• When the type parameter is set to DB2, valid values are:

  • START
  • STOP

• When the type parameter is set to DUMP, the valid value is DUMP.

• When the type parameter is set to HSM, valid values are:

  • QUERY COPYPOOL
  • LIST COPYPOOL

• When the type parameter is set to WLM, the valid value is DISPLAY.

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

parameters

Specifies the parameters of the command, or the program parameters that will be passed to the started task.

Valid values depend on the value of the command parameter.

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

You cannot specify null for this parameter if the type parameter is set to HSM, DUMP, or WLM.

subparameters

Specifies the sub-parameters of the command. The following keyword-value pairs are supported:

CONSNAME=console-name

The name of the console that the stored procedure activates. If not specified, the default is DSNADMCM. The specified console must not already be active.

IRLMPROC=procedure-name

The procedure name of the connected IRLM. The stored procedure performs the following actions if IRLMPPROC is specified:

• If DB2 is already stopping when the stored procedure issues the STOP DB2 command, it starts monitoring IRLM termination after the DSN9022I message is received.
• If DB2 is not stopped or is not already stopping when the stored procedure issues the STOP DB2 command, it starts monitoring IRLM termination after message DSN3100I is received.

Monitoring occurs within the specified wait-timeout period and ends when the IRLM address space terminates or the wait timeout period expires. The stored procedure reports DB2 normal termination only after it determines that IRLM address space is terminated.

The IRLM procedure name is 1 - 8 characters. The first character must be a letter A - Z, #, $, or @; the remaining characters can be A through Z, 0 - 9, or #, $, or @.

This keyword-value pair can only be specified when the type parameter is DB2, the command parameter is STOP, and the SSNM keyword is not specified.

SSNM=subsystem-name

The DB2 subsystem name. The stored procedure performs the following actions:

• If DB2 is already stopping when the stored procedure issues the STOP DB2 command, it starts monitoring ssnmMSTR termination after the DSN9022I message is received.
• If DB2 is not stopped or is not already stopping when the stored procedure issues the STOP DB2 command, the keyword is ignored and no monitoring of ssnmMSTR termination occurs.

Monitoring occurs within the specified wait-timeout period and ends when the ssnmMSTR address space terminates or the wait timeout period expires. The stored procedure reports DB2 normal termination only after it determines that the ssnmMSTR address space is terminated.

The subsystem name is 1 - 4 characters. The first character must be a letter A - Z, #, $, or @; the remaining characters can be A through Z, 0 - 9, or #, $, or @.

This keyword-value pair can be specified only when the the type parameter is DB2, the command parameter is STOP, and the IRLMPROC keyword is not specified.

LIST_CP_KEYWORDS=DUMPVOLS

This keyword-value pair can be specified only when the type parameter is HSM and the command parameter is LIST COPYPOOL.

QUERY_CP_BACKUP=number-of-versions

The number of copy pool backup versions. This key-value pair can be specified only when the command parameter is set to QUERY COPYPOOL.

Alternatively, if no key-value pairs specified for subparameters, the following values are supported:

• DUMPVOLS, when the command parameter is LIST COPYPOOL.
• The number of copy pool backup versions, when command parameter is QUERY COPYPOOL.

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

You cannot specify null for this parameter if both of the following conditions apply:

• The type parameter is set to HSM
• The command parameter is set to QUERY COPYPOOL

wait_timeout

Specifies the amount of time (in seconds) that this procedure waits for the command to complete and for the message to be routed to the console. If the console is already active, the wait time includes the time that the procedure waits for the console to become available. If stopping DB2 and the IRLM or ssnmMSTR address space termination is being monitored, the wait time includes the time the procedure monitors the status of these address spaces.

For DB2 START and DB2 STOP, valid values are 1-900, and the default wait time is 180 seconds. Otherwise, valid values are 1-120, and the default wait time is 5 seconds.

This parameter is an input parameter of type INTEGER.

return_code

Provides the return code from the stored procedure.

Possible values are:

0

The stored procedure did not encounter any errors during processing. However, this return code does not indicate that the command executed successfully. The command_completion_code output parameter indicates whether the command executed successfully or not.

4

The stored procedure issued the command but was unable to determine the command execution status based on the command messages that were retrieved within the prescribed wait time. For example, the wait time might have expired.

When return_code is 4, the command_completion_code parameter is set to 8 or 16.

All command messages that were retrieved within the prescribed wait time are returned in the result set.

8

The stored procedure issued the command but was unable to determine the command execution status because it was unable to retrieve all the command messages that were queued to the extended MCS console. When return_code is 8, the command_completion_code parameter is set to 8 or 16. All the command messages that were retrieved so far are returned in the result set. For STOP DB2, the latest IRLM or DB2 MSTR address space status information (from the 'D A' output) is also returned in the result set if IRLM or MSTR termination monitoring was performed successfully.For STOP DB2, the latest IRLM or DB2 MSTR address space status information (from the 'D A' output) is also returned in the result set if IRLM or MSTR termination monitoring was performed successfully.

12

The stored procedure encountered an error during processing. The message output parameter contains messages that describe the error.

This parameter is an output parameter of type INTEGER.

command_completion_code

Indicates the completion status of the command.

Possible values are:

0

One of the following conditions applies:

• The command completed successfully.
• If the command parameter is QUERY COPYPOOL, there is no FlashCopy® process that is active in the background.

For details about command_completion_code 0, see Table 1.

4

One of the following conditions applies:

• The command was not processed. For example, DB2 was already stopped when STOP DB2 was requested.
• If the command parameter is QUERY COPYPOOL, one or more FlashCopy processes are active in the background.

For details about command_completion_code 4, see Table 2.

8

The command started but the completion status is unknown. For details about command_completion_code 8, see Table 3.

12

The command completed abnormally. For details about command_completion_code 12, see Table 4.

16

The command output does not satisfy the conditions that are listed for command_completion_code 0, 4, 8, or 12.

This parameter is an output parameter of type INTEGER.

The following tables describe the messages that ADMIN_COMMAND_MVS looks for when assigning a specific value to command_completion_code.

Table 1. Description of command_completion_code 0

Command	Command completion code description	Messages received
DISPLAY WLM	DISPLAY WLM completed successfully.	Message IWM029I was received.
DUMP	DUMP completed successfully.	Both of the following messages were received: IEA794I IEA911E or IEA611I
LIST COPYPOOL	The list of copy pools that was output by LIST COPYPOOL is complete.	Both of the following messages were received: COPYPOOL=xx...xx, where xx...xx is the name of the copy pool that is specified in the parameters input parameter ARC0140I
QUERY COPYPOOL	No FlashCopy processes are active in the background.	Message ARC1821I was received. The number of copy pool backup versions (as specified in the subparameters input parameter) and the number of copy pool versions that are not in active FlashCopy relationships is the same. Message ARC1820I was not received.
START DB2	START DB2 completed successfully.	Message DSN9022I cmd_prefix was received, which indicates that DB2 START completed normally.
STOP DB2	STOP DB2 completed successfully.	DSN3100I cmd_prefix Message 'irlm_procname NOT FOUND' was found in the 'D A, irlm_procname' command output when the stored procedure checked the IRLM address space status.

Table 2. Description of command_completion_code 4

Command	Command completion code description	Messages received
QUERY COPYPOOL	One or more FlashCopy processes are active in the background.	One or more ARC1820I messages and zero or more ARC1821I messages were received. The number of copy pool backup versions (as specified in the subparameters input parameter) and the number of copy pool versions that are in active and not in active FlashCopy relationships is the same.
START DB2	DB2 is already active when the command was issued.	Message DSNY003I cmd_prefix was received.
STOP DB2	One of the following scenarios applies: DB2 was already stopped when the command was issued. DB2 was in the process of stopping when the command was issued, and it stopped successfully.	DB2 was already stopped: DSN3106I cmd_prefix DB2 was in the process of stopping: DSNY004I cmd_prefixand DSN9022I cmd_prefix, where DSN9022I cmd_prefix indicates that DB2 STOP completed normally, and either message 'ssnmMSTR NOT FOUND' was found in the 'D A, ssnmMSTR' command output when the stored procedure checked thessnmMSTR address space status, or message 'irlm_procname NOT FOUND' was found in the 'D A, irlm_procname' command output when the stored procedure checked the IRLM address space status.

Table 3. Description of command_completion_code 8

Command	Command completion code description	Messages received	Expected completion messages not received
DUMP	The dump was captured but not written.	Message IEA794I was received.	One of the following messages was not received: IEA911E IEA611I
LIST COPYPOOL	The listing from LIST COPYPOOL is truncated.	Message COPYPOOL=xx...xxx was received, where xx...xx is the name of the copy pool that is specified in the parameters input parameter.	Message ARC0140I was not received.
QUERY COPYPOOL	One or more FlashCopy processes are active or not active in the background.	One or more ARC1820I or ARC1821I messages was received.	The total number of ARC1820I and ARC1821I messages is not equal to the total number of copy pool backup versions that is specified in the subparameters input parameter.
START DB2	DB2 is in the process of starting, but the completion status of START DB2 is unknown.	Message DSNY024I cmd_prefix was received.	One of the following messages was not received: DSN9023I cmd_prefix DSNV086E cmd_prefix DSN3104I cmd_prefix DSN9022I cmd_prefix, which indicates that DB2 START completed normally DSN3100I cmd_prefix
STOP DB2	DB2 is in the process of stopping, but the completion status of STOP DB2 is unknown.	One of the following messages was received: DSNY002I cmd_prefix DSNY004I cmd_prefix	DSNY002I cmd_prefix received: None of the following messages were received: DSN3100I cmd_prefix DSN3107I cmd_prefix DSN9023I cmd_prefix Or, message DSN3100I cmd_prefix was received but message 'irlm_procname NOT FOUND' was not found in the 'D A, irlm_procname' command output when the stored procedure checked the IRLM address soace status. DSNY004I cmd_prefix received: None of the following messages were received: DSN9022I cmd_prefix, which indicates that DB2 STOP completed normally DSN9023I cmd_prefix Or, message DSN9022I cmd_prefix was received but either message 'irlm_procname NOT FOUND' was not found in the 'D A, irlm_procname' command output when the stored procedure checked the IRLM address space status, or message 'ssnmMSTR NOT FOUND' was not found in the 'D A, ssnmMSTR' command output when the stored procedure checked the ssnmMSTR address space status.

Table 4. Description of command_completion_code 12

Command	Command completion code description	Messages received
DISPLAY WLM	DISPLAY WLM completed abnormally.	One of the following messages was received: IWM002I IWM003I IWM030I
LIST COPYPOOL	No output was generated from LIST COPYPOOL.	Message ARC0140I was received, but message COPYPOOL=xx...xxx was not received, where xx...xxx is the name of the copy pool that is specified in the parameters input parameter.
START DB2	START DB2 completed abnormally.	One of the following messages was received: DSN9023I cmd_prefix DSNV086E cmd_prefix DSN3106I cmd_prefix DSN3107I cmd_prefix DSN3104I cmd_prefix DSN3100I cmd_prefix
STOP DB2	STOP DB2 completed abnormally.	One of the following messages was received: DSN3107I cmd_prefix DSN9023I cmd_prefix

message

Contains messages that describe the error that was encountered by the stored procedure.

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

Example

The following C language example shows how to invoke ADMIN_COMMAND_MVS.

#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_MVS parameters                           */
 EXEC SQL BEGIN DECLARE SECTION;
 /* SYSPROC.ADMIN_COMMAND_MVS parameters                           */
 char       ptype[25];           /* Command type                   */
 char       pcprefix[9];         /* DB2 subsystem command prefix   */
 char       prmtsys[9];          /* Remote system                  */
 char       pjobnm[9];           /* Started task job name          */
 char       pcmd[127];           /* Command to be executed         */
 char       pparms[125];         /* Command parameters             */
 char       psubparms[125];      /* Command subparameters          */
 long int   pwait;               /* Command completion wait time   */
 long int   prc;                 /* Return code                    */
 long int   pccc;                /* Command completion code        */
 char       pmsg[1332];          /* Error message                  */

 short int  ind_ptype;           /* Indicator variable             */
 short int  ind_pcprefix;        /* Indicator variable             */
 short int  ind_prmtsys;         /* Indicator variable             */
 short int  ind_pjobnm;          /* Indicator variable             */
 short int  ind_pcmd;            /* Indicator variable             */
 short int  ind_pparms;          /* Indicator variable             */
 short int  ind_psubparms;       /* Indicator variable             */
 short int  ind_pwait;           /* Indicator variable             */
 short int  ind_prc;             /* Indicator variable             */
 short int  ind_pccc;            /* Indicator variable             */
 short int  ind_pmsg;            /* 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[2001];             /* Message                    */
 EXEC SQL END DECLARE SECTION;
 /******************************************************************/
 /* Clear temporary table SYSIBM.MVS_CMD_OUTPUT                    */
 EXEC SQL DELETE FROM SYSIBM.MVS_CMD_OUTPUT;
 /******************************************************************/
 /* Set procedure input parameters                                 */
 /******************************************************************/
 strcpy(ptype, "WLM");
 strcpy(pcmd, "DISPLAY");
 strcpy(pparms, "APPLENV=*");
 ind_ptype = 0;
 ind_pcprefix = -1;
 ind_prmtsys = -1;
 ind_pjobnm = -1;
 ind_pcmd = 0;
 ind_pparms = 0;
 ind_psubparms = -1;
 ind_pwait = -1;
 /******************************************************************/
 /* Call stored procedure SYSPROC.ADMIN_COMMAND_MVS                */
 /******************************************************************/
 EXEC SQL CALL SYSPROC.ADMIN_COMMAND_MVS (
             :ptype:ind_ptype,
             :pcprefix:ind_pcprefix,
             :prmtsys:ind_prmtsys,
             :pjobnm:ind_pjobnm,
             :pcmd:ind_pcmd,
             :pparms:ind_pparms,
             :psubparms:ind_psubparms,
             :pwait:ind_pwait,
             :prc:ind_prc,
             :pccc:ind_pccc,
             :pmsg:ind_pmsg);
 /******************************************************************/
 /* 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_MVS;
 /* 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;
  }
 }
 return;
}

Output

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

• return-code
• command_completion_code
• message

In addition to the preceding output, the stored procedure returns one result set that contains the command messages. For STOP DB2, the latest IRLM or DB2 ssnmMSTR address space status information (from the 'D A' output) is also returned in the result set if IRLM or MSTR termination monitoring was performed successfully.

For DB2 START, DB2 STOP, and DUMP commands, both solicited messages (which are command responses) and unsolicited messages (which are other system messages) are retrieved and returned. Otherwise, only solicited messages are returned.

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