HCL Workload Automation, Version 9.4

Alternative method to set the user return code

About this task

In some IBM i environments, the system API retrieving the user return code (Urc) from the Agent Monitor code does not retrieve the correct value for Urc. It is therefore not recommended that you use any IBM i system APIs to retrieve the user return code. To receive a value returned by a called program, it is better to provide, instead, a parameter to receive the value.

Even if the Agent Monitor can retrieve the user return code using system API, an alternative user return code retrieval method was implemented in the Agent Monitor code. The alternative retrieval method has the following logic. The USERRC job environment variable is created and set to the INI value before submitting the user command. When the command ends, the Agent Monitor retrieves its user return code using the system APIs, but it also verifies if the USERRC job environment variable was updated at user program level. If a value different from INI is found, this is considered as the user return code and the value retrieved using the system APIs is ignored because the user program modified the value of USERRC job environment variable.

The change of the USERRC variable at user program level requires the USERRC value change before exiting from the application user code. In the ILE C case, you can do this using the putenv statement, where the user return code is set to be returned.

The following example shows how the user code returns the user return code using the IBM i agent reserved job environment variable USERRC. This code was obtained from the code of the example in Controlling the job environment with the user return code by replacing the exit with the putenv statement.

=========================================================================
#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)");
   EnvVarRC = putenv("USERRC=10");                                  
   return;                                                         
}  
=========================================================================