HCL Workload Automation, Version 9.4

Controlling the job environment with the user return code

About this task

With the introduction of the IBM i ILE model, it is possible to retrieve a value returned by a called program inside the same job.

When the Agent Monitor verifies that a submitted command is completed, it retrieves the following end of job codes using an IBM i System API:

End status code or <Status> (0 if successful)

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 or <Prc> (0000 if successful)

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 or <Urc> (0000 if successful)

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.

If the submitted command is a call to a user ILE program returning a value on exiting, this value is found in the Urc end of job code.

You can decide how to control the job environment of your submitted jobs by preparing the commands to be submitted as CALLs to your ILE programs, where the internal flow is controlled and the end status is decided through proper exit values. If a user program ends in error for an incorrect flow control, without returning a value, the Agent Monitor does not set the Return Code as user return code (Urc), but follows the criteria described in The agent return code retrieval.

The following example shows an ILE C user program where two batch jobs are launched and a value of 10 is returned to the caller, regardless of the completion status of the batch jobs.

=========================================================================
#include <stdio.h>                                                 
#include <stdlib.h>                                                
#include <string.h>                                                
void main(int argc, char *argv[])                                  
{                                                                  
   int   EnvVarRC=0;                                               
   printf("issuing SBMJOB CMD(CALL MYLIB/DIVBY0)...\n");         
   system("SBMJOB CMD(CALL MYLIB/DIVBY0)");                      
   printf("issuing SBMJOB CMD(WRKACTJOB OUTPUT(*PRINT))...\n");    
   system("SBMJOB CMD(WRKACTJOB OUTPUT(*PRINT)) LOG(4 0 *SECLVL)");
   exit(10);                                                   
   return;                                                         
}                                                                  
=========================================================================