HCL Workload Automation, Version 9.4

Controlling the job environment with JOBMANRC

About this task

The normal mode is the only mode that allows retrieval of the end-of job codes, using the definition of a control user exit, JOBMANRC, described in this section as JCL source sample. See below for the meaning of each end-of-job code.

To set up a generic environment to run all jobs launched by HCL Workload Automation or pre-process their return codes, you can create a program named JOBMANRC in the QTWS library. The following is a template you can use as a model for your JOBMANRC.

/*************************************************************/
/*                                                           */
/*             JOBMANRC SAMPLE PROGRAM                       */
/*                                                           */
/*************************************************************/
PGM      PARM(&JCL_NAME &JCL_LEN)
/* Here we receive the name of the program to launch */
DCL      VAR(&JCL_NAME) TYPE(*CHAR) LEN(4098) 
DCL      VAR(&JCL_LEN) TYPE(*CHAR) LEN(4)     
DCL      VAR(&RC) TYPE(*CHAR) LEN(20) VALUE('                    ')
DCL      VAR(&CL_STATUS) TYPE(*CHAR) LEN(7) VALUE(' ')
DCL      VAR(&USR_STATUS) TYPE(*CHAR) LEN(4) VALUE(' ')
DCL      VAR(&PGM_STATUS) TYPE(*CHAR) LEN(4) VALUE(' ')
DCL      VAR(&MESSAGE) TYPE(*CHAR) LEN(255)
DCL      VAR(&COMMAND) TYPE(*CHAR) LEN(255)
DCL      VAR(&CMD_LEN) TYPE(*DEC) LEN(4 0)    
/*****************************************************/
/*   HERE WE CALL TO THE TWSEXEC UTILITY PROGRAM     */
/*****************************************************/
/* Now we call the CL Program that will launch the OPC script */
CALL     PGM(QTWS/TWSEXEC) PARM(&JCL_NAME &JCL_LEN &RC )
MONMSG   MSGID(CPF0000)
CHGVAR   VAR(&CL_STATUS) VALUE(%SST(&RC 1 7))
CHGVAR   VAR(&CMD_LEN) VALUE(&JCL_LEN)
CHGVAR   VAR(&COMMAND) VALUE(%SST(&JCL_NAME 1 &CMD_LEN))
/**********************************************/
/* VERIFY THE MESSAGE CODE AFTER EXECUTION    */
/**********************************************/
IF       COND(&CL_STATUS *NE 'CPF0000') THEN(DO)
CHGVAR   VAR(&MESSAGE) VALUE('QTWS/400: JOBMANRC ERROR -> ' +
*BCAT &CL_STATUS *BCAT ' executing the program: -> ' +
*BCAT &COMMAND)
/***********************************************/
/* SEND A WARNING TO THE OPERATOR              */
/***********************************************/
SNDMSG   MSG(&MESSAGE) TOUSR(*SYSOPR)
/***********************************************/
/* SEND AN ERROR TO ALLOW THIS PROGRAM TO FAIL */
/***********************************************/
SNDPGMMSG  MSGID(CPF0006) MSGF(QCPFMSG) MSGTYPE(*ESCAPE)
ENDDO
CHGVAR   VAR(&USR_STATUS) VALUE(%SST(&RC 12 4))
/***********************************************/
/* VERIFY THE USER RETURN CODE AFTER EXECUTION */
/***********************************************/
IF     COND(&USR_STATUS *NE '0000') THEN(DO)
CHGVAR VAR(&MESSAGE) VALUE('QTWS/400: JOBMANRC PROGRAM USER ERROR ->' +
*BCAT &USR_STATUS *BCAT ' executing the program: -> ' +
*BCAT &COMMAND)
/***********************************************/
/* SEND A WARNING TO THE OPERATOR              */
/***********************************************/
SNDMSG   MSG(&MESSAGE) TOUSR(*SYSOPR)
ENDDO
CHGVAR   VAR(&PGM_STATUS) VALUE(%SST(&RC 8 4))
/************************************************/
/* VERIFY A PROGRAM RETURN CODE AFTER EXECUTION */
/************************************************/
IF     COND(&PGM_STATUS *GT '0001') THEN(DO)
CHGVAR VAR(&MESSAGE) VALUE('QTWS/400: JOBMANRC PROGRAM ERROR ->' +
*BCAT &PGM_STATUS *BCAT ' executing the program: -> ' +
*BCAT &COMMAND)
/***********************************************/
/* SEND A WARNING TO THE OPERATOR              */
/***********************************************/
SNDMSG   MSG(&MESSAGE) TOUSR(*SYSOPR)
/***********************************************/
/* SEND AN ERROR TO ALLOW THIS PROGRAM TO FAIL */
/***********************************************/
SNDPGMMSG MSGID(CPF0006) MSGF(QCPFMSG) MSGTYPE(*ESCAPE)
ENDDO
EXITNOERR:
ENDPGM

If a JOBMANRC program exists in the QTWS library, HCL Workload Automation executes it instead of executing the actual scheduled jobs. For each job, HCL Workload Automation passes the scheduled job’s name to JOBMANRC in the variable &JCL_NAME. The scheduled job is executed by the HCL Workload Automation supplied program TWSEXEC, which must be run in the manner shown in the template. TWSEXEC returns the scheduled job’s return code in the variable &RC, which can then be tested to determine the action to be taken.

TWSEXEC returns, for the scheduled job, a full return code that is the combination of the following end-of-job codes:

End status code or <Status> (0 if successful)
Program return code or <Prc> (0000 if successful)
User return code or <Urc> (0000 if successful)

The full return code is a 15-character string that is the combination of status 'AAAnnnn', 'Prc', and 'Urc', where 'AAAnnnn' is 'CPF0000' when the end status code is zero (or an appropriate IBM i system message when the end status code is nonzero). 'AAAnnnn' is the System message associated to the end status code.

Note: On an IBM i system, the meaning of each end-of-job code is the following:

End status code: It indicates if the system issued a controlled cancellation of the job. Possible values are 1 (the subsystem or the job itself is canceled), 0 (the subsystem or the job itself is not canceled), blank (the job is not running).
Program return code: It specifies the completion code of the last program (such as a data file utility program, or an RPG or COBOL program, invoked by the job). If the job includes no program, the program return code is 0.
User return code: It specifies the user-defined return code set by ILE high-level language constructs. For example, the return code of a program written in C language. It represents the most recent return code set by any thread within the job.

JOBMANRC captures, using the TWSEXEC program, the full return code. This allows the end-of-job codes to be extracted and managed.

In the sample given, the first check is on the System message code: its only acceptable value is 'CPF0000'. The next check is on the User return code: its only acceptable value is 0. The last check is on the Program return code that can either be 0 or 1 (if any RPG, COBOL, or DFU programs are running). If any of the three return codes has a different value, JOBMANRC sends an escape message and the completion state of the scheduled job is set to ABEND. If all three return codes are acceptable, the escape message is not sent and the completion code of the job is set to SUCC.