ADMIN_JOB_CANCEL stored procedure

The SYSPROC.ADMIN_JOB_CANCEL stored procedure purges or cancels a job.

Environment

Begin general-use programming interface information.

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

The load module for ADMIN_JOB_CANCEL, DSNADMJP, must be program controlled if the BPX.DAEMON.HFSCTL FACILITY class profile has not been set up. For information on how to define DSNADMJP 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:

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

The user specified in the user-ID input parameter of the SQL CALL statement also needs authorization from an external security system, such as RACF®, in order to perform the requested operation.

Syntax

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

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

>--+-password-+-,--processing-option,--job-ID,--return-code,---->
   '-NULL-----'                                                

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

Option descriptions

user-ID

Specifies the user ID under which the job is canceled or purged.

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

processing-option

Identifies the type of command to invoke. Possible values are:

1: Cancel a job.
2: Purge a job.

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

job-ID

Specifies the job ID of the job to be canceled or purged. Acceptable formats are:

Jnnnnnnn
JOBnnnnn

where n is a digit between 0 and 9. For example: JOB01035

Both Jnnnnnnn and JOBnnnnn must be exactly 8 characters in length.

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

 #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_JOB_CANCEL parameters                            */
   char        userid[129];            /* User ID                    */
   short int   ind_userid;             /* Indicator variable         */
   char        password[25];           /* Password                   */
   short int   ind_password;           /* Indicator variable         */
   long  int   procopt;                /* Processing option          */
   short int   ind_procopt;            /* Indicator variable         */
   char        jobid[9];               /* Job ID                     */
   short int   ind_jobid;              /* Indicator variable         */
   long int    retcd;                  /* Return code                */
   short int   ind_retcd;              /* Indicator variable         */
   char        errmsg[1332];           /* Error message              */
   short int   ind_errmsg;             /* Indicator variable         */
   EXEC SQL END DECLARE SECTION;

   /******************************************************************/
   /* Assign values to input parameters to purge a job               */
   /* Set the indicator variables to 0 for non-null input parameters */
   /******************************************************************/
   strcpy(userid, "USRT001");
   ind_userid = 0;
   strcpy(password, "N1CETEST");
   ind_password = 0;
   procopt = 2;
   ind_procopt = 0;
   strcpy(jobid, "JOB00105");
   ind_jobid = 0;

   /******************************************************************/
   /* Call stored procedure SYSPROC.ADMIN_JOB_CANCEL                 */
   /******************************************************************/
   EXEC SQL CALL SYSPROC.ADMIN_JOB_CANCEL
                        (:userid    :ind_userid,
                         :password  :ind_password,
                         :procopt   :ind_procopt,
                         :jobid     :ind_jobid,
                         :retcd     :ind_retcd,
                         :errmsg    :ind_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.