ADMIN_JOB_QUERY stored procedure

The SYSPROC.ADMIN_JOB_QUERY stored procedure displays the status and completion information about a job.

Environment

Begin general-use programming interface information.

The load module for ADMIN_JOB_QUERY, DSNADMJQ, must reside in an APF-authorized library. ADMIN_JOB_QUERY 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_QUERY, DSNADMJQ, must be program controlled if the BPX.DAEMON.HFSCTL FACILITY class profile has not been set up. For information on how to define DSNADMJQ 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_QUERY stored procedure
  • Ownership of the stored procedure
  • SYSADM authority

Syntax

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

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

>--+-password-+-,--job-ID,--status,--max-RC,-------------------->
   '-NULL-----'                                

>--completion-type,--system-abend-code,--user-abend-code,------->

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

Option descriptions

user-ID
Start of changeSpecifies the user ID under which the job is queried.

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

End of change
password
Start of changeSpecifies 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).

End of change
job-ID
Specifies the job ID of the job being queried. 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.

status
Identifies the current status of the job. Possible values are:
1
Job received, but not yet run (INPUT).
2
Job running (ACTIVE).
3
Job finished and has output to be printed or retrieved (OUTPUT).
4
Job not found.
5
Job in an unknown phase.

This is an output parameter of type INTEGER.

max-RC
Provides the job completion code.

This parameter is always null if querying in a JES3 z/OS Version 1.7 or earlier system. For JES3, this feature is only supported for z/OS Version 1.8 or higher.

This is an output parameter of type INTEGER.

completion-type
Identifies the job's completion type. Possible values are:
0
No completion information is available.
1
Job ended normally.
2
Job ended by completion code.
3
Job had a JCL error.
4
Job was canceled.
5
Job terminated abnormally.
6
Converter terminated abnormally while processing the job.
7
Job failed security checks.
8
Job failed in end-of-memory .

This parameter is always null if querying in a JES3 z/OS Version 1.7 or earlier system. For JES3, this feature is only supported for z/OS Version 1.8 or higher.

The completion-type information is the last six bits in the field STTRMXRC of the IAZSSST mapping macro. This information is returned via SSI 80. For additional information, see the discussion of the SSST macro in z/OS MVS™ Data Areas.

This is an output parameter of type INTEGER.

system-abend-code
Returns the system abend code if an abnormal termination occurs.

This parameter is always null if querying in a JES3 z/OS Version 1.7 or earlier system. For JES3, this feature is only supported for z/OS Version 1.8 or higher.

This is an output parameter of type INTEGER.

user-abend-code
Returns the user abend code if an abnormal termination occurs.

This parameter is always null if querying in a JES3 z/OS Version 1.7 or earlier system. For JES3, this feature is only supported for z/OS Version 1.8 or higher.

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.
4
The job was not found, or the job status is unknown.
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.

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

Example

The following C language sample shows how to invoke ADMIN_JOB_QUERY:

 #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_QUERY parameters                             */
   char        userid[129];            /* User ID                    */
   short int   ind_userid;             /* Indicator variable         */
   char        password[25];           /* Password                   */
   short int   ind_password;           /* Indicator variable         */
   char        jobid[9];               /* Job ID                     */
   short int   ind_jobid;              /* Indicator variable         */
   long int    stat;                   /* Job status                 */
   short int   ind_stat;               /* Indicator variable         */
   long int    maxrc;                  /* Job maxcc                  */
   short int   ind_maxrc;              /* Indicator variable         */
   long int    comptype;               /* Job completion type        */
   short int   ind_comptype;           /* Indicator variable         */
   long int    sabndcd;                /* System abend code          */
   short int   ind_sabndcd;            /* Indicator variable         */
   long int    uabndcd;                /* User abend code            */
   short int   ind_uabndcd;            /* 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 query the status and      */
   /* completion code of 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;
   strcpy(jobid, "JOB00111");
   ind_jobid = 0;

   /******************************************************************/
   /* Call stored procedure SYSPROC.ADMIN_JOB_QUERY                  */
   /******************************************************************/
   EXEC SQL CALL SYSPROC.ADMIN_JOB_QUERY
                        (:userid    :ind_userid,
                         :password  :ind_password,
                         :jobid     :ind_jobid,
                         :stat      :ind_stat,
                         :maxrc     :ind_maxrc,
                         :comptype  :ind_comptype,
                         :sabndcd   :ind_sabndcd,
                         :uabndcd   :ind_uabndcd,
                         :retcd     :ind_retcd,
                         :errmsg    :ind_errmsg);

   return(retcd);
 }

Output

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

  • status
  • max-RC
  • completion-type
  • system-abend-code
  • user-abend-code
  • return-code
  • message

End general-use programming interface information.