HCL Workload Automation, Version 9.4

Alternative method to retrieve the user return code with JOBMANRC

About this task

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

It is recommended that you use version 8.5.1 or later of user exit code, where a new urc retrieving "method" was implemented in the TWSEXEC code, with the following logic: a job environment variable is created, named USERRC, and set to the INI value before submitting the user command. When the command ends, TWSEXEC retrieves its urc with the system APIs, as usual, 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 urc and the value retrieved through system APIs is ignored. This means that the user program modified the value of USERRC.

Modifying USERRC at user program level requires specific code in the application user code, where the urc is set to be returned. The following example shows how the user code passes back the urc via the IBM i agent reserved job environment variable USERRC:
-----------------------------------------------------------
#include <stdio.h>
#include <stdlib.h> ---------------------------------(***)
#include <string.h> ---------------------------------(***)
void main(int argc, char *argv[])
{
  int      ind;
  int      iEndSts = 240;
  char     UserRetCode[10]; 
  system("DSPLIBL");
  ind = sprintf(UserRetCode, "%s", "USERRC="); 
  ind += sprintf(UserRetCode+ind, "%d", iEndSts); 
  putenv(UserRetCode); 
  exit(iEndSts); 
}
(***) >>> this is a required include <<<
------------------------------------------------------------

This example shows one way to set USERRC to the urc value. Usually, the urc is the result of complex processing, not just a simple system statement.