7.10.3 Checking the return code of a job

You can check the return code of a job in the Monitor Details - [unit-name] dialog box of JP1/AJS3 - View, or from the value of EXITCODE in the job information output by the jpqjobget command. Under normal circumstances, 0 is set as the return code when a job terminates normally. If the job terminates abnormally, the return code of the job process is set. However, in the following cases, the return code is set by JP1/AJS3.

Table 7‒13: Return codes set by JP1/AJS3 and associated conditions
Condition	Return code set by JP1/AJS3
If one of the following statuses occurs in a QUEUE job for which JP1/AJS3 is specified as a host, a PC job, a Unix job, a flexible job, an HTTP connection job, an action job, or a custom job: Failed to start Killed (including jobs killed due to their timeout period elapsing) Ended abnormally^#	`-1`
If an unexpected JP1/AJS3 error occurs during execution of a Unix job.	`255`

#

If a problem occurs during post-processing by JP1/AJS3 after a job process has terminated (for example, if the result file could not be transferred to the manager host), the return code of the job process is overwritten with -1 by JP1/AJS3 and the job process terminates abnormally.

Cautionary notes

For flexible jobs executed on Windows hosts and PC jobs, the job processes started by these jobs themselves can return -1 as a return code. For flexible jobs executed on Linux hosts and Unix jobs, if job processes end with a negative value, the return code is calculated by adding 256 to the negative value. For example, if a job process ends with -1, the return code is 256 - 1 = 255. In a user application, if you need to determine whether the return code was set by the job process or JP1/AJS3, do not use a return code of -1 or 255 in your user applications.
For flexible jobs executed on Linux hosts and Unix jobs, a login script is executed prior to job execution. Therefore, if processing terminates during execution of the login script, the return code for the login script is set. Make sure that processing does not terminate abnormally during execution of the login script. For details about how to change the login script, see 13.4.2 Changing the login scripts in the JP1/Automatic Job Management System 3 Configuration Guide.
For a flexible job, if either of the following options is selected for the end judgment method and the selected end condition is not satisfied, the return code is set to 1:

- Normal if specified file exists

- Normal if file was updated

In some cases the return code of a job is set by the OS, rather than by a user application or JP1/AJS3. The following table gives examples of typical return codes. Because upgrading your OS might change these return codes, check the technical information for your OS.

Table 7‒14: Examples of return codes set by the OS
OS	Return code	Cause	Action to take
Windows	259 or -1	The process might have failed to open the results file. In this case, one of the following occurs: Message KAVU3284-W is output: `A` `system` `call` `error` `occurred` `in` `the` `internal` `process` `(logical-host-name)` `(reason` `module:` `reason-module`, `reason` `code` `1:` `0x2013000a`, `system` `call` `name:` `CreateFile`, `reason` `code` `2:` `reason-code-2)` The following message is output to the standard error output: `The` `process` `cannot` `access` `the` `file.` `The` `file` `is` `being` `used` `by` `another` `process.`	As the standard output file or standard error output file when you register a job, do not specify a file opened from within a program executed as a job or opened by redirection from a batch file. However, where the file is opened from within the program by a function call, you can work around the problem by opening the file with a setting that permits shared read and write modes.
Windows	128	There might be a desktop heap shortage. If so, one of the following messages is output: `XXXX`.`XXX` `-` `application` `error:` `application` `not` `initialized` `correctly`; or `Failed` `to` `initialize` `XXXX`.`XXX`	To reduce use of the desktop heap, use the same user account as the JP1/AJS3 service to execute jobs.
UNIX	Signal number + 128	A program started from a job process might have received a signal.^#	Take one of the following actions: Set up the program started from a job process so that it does not receive signals. Set up a signal handler or similar for the program to provide additional processing that sets signal-dependent return codes.

#: If the job process itself receives a signal, jobs with Standard specified as the execution service will change to the Killed status with the return code -1. Jobs with Queueless Agent specified as the execution service will change to Ended abnormally status with the return code -1.

Organization of this subsection

(1) Return codes of flexible jobs
(2) Return codes of HTTP connection jobs
(3) Return codes of event jobs and action jobs

(1) Return codes of flexible jobs

The following table describes the return codes of flexible jobs.

Note that if a flexible job is executed by broadcast execution, the largest of the return codes for the executions on the destination agents is used for the return code of the flexible job. However, if at least one of the return codes is -1, the return code of the flexible job is -1.

Table 7‒15: Return codes of flexible jobs
Return code	Description	Corresponding message
Return code set by the user application (executable file)	Always normal, Always abnormal, or Judgment by threshold is selected as the end judgment method, and JP1/AJS3 processing terminated normally.	KAVS8138-I KAVS8140-I
0	Normal if specified file exists or Normal if file was updated is selected as the end judgment method, and the condition for being normal is met.
1	Normal if specified file exists or Normal if file was updated is selected as the end judgment method, and the condition for being normal is not met.
-1	The monitoring termination time was exceeded.	KAVS8101-E
	Resources are insufficient.	KAVS8102-E
	Communication with the JP1/AJS3 Autonomous Agent Messenger service is impossible.	KAVS8100-E
	A system error occurred.	KAVV8106-E
	No executable file exists.	KAVS8108-E
	The permission level is too low to execute the executable file.	KAVS8109-E

To Page Top

(2) Return codes of HTTP connection jobs

The following table describes the return codes of HTTP connection jobs.

Table 7‒16: List of return codes of HTTP connection jobs
Return code	Description	Corresponding message
0	If return codes are explicitly specified, this return code indicates that processing terminated normally (the HTTP status code specified for `0`). If return codes are not explicitly specified, this return code indicates that processing terminated normally (HTTP status code `200`).	KAVS8050-I
1 to 9	If return codes are explicitly specified, this return code corresponds to the HTTP status code that is specified for normal termination.	KAVS8050-I
10	Ended normally (an HTTP status code that is not `200` and not defined for any return code).	KAVS8050-I
20	A timeout occurred.	KAVS8061-E
30	The name of the connection destination host could not be resolved.	KAVS8054-E
40	Another error occurred during file access.	KAVS8053-E
60	A parameter error occurred. The job definition items are specified incorrectly (for example, the length or value is invalid).	KAVS8051-E
64	The connection configuration file contains syntax errors.	KAVS8052-E
70	The URL is specified incorrectly. The resource referenced at the URL does not exist. The transmission information file used when the `GET` method is called contains line breaks.	KAVS8060-E
80	No file exists. A directory was specified.	KAVS8053-E
81	A permission error occurred when a file was accessed. A directory was specified.	KAVS8053-E
90	An attempt to load environment setting parameters failed.	KAVS8063-E
101	Connection to the connection destination host failed.	KAVS8056-E
102	An error occurred during communication with the connection destination host.	KAVS8057-E
106	The size of response data exceeds the maximum file size specified in the connection configuration file.	KAVS8059-E
110	One of the following HTTPS authentication errors occurred: HTTPS authentication failed. A handshake failed. The certificate was invalid. The certificate file could not be accessed. The CRL file was invalid. A CRL file access error occurred. The publisher (CN (Common Name) or SAN (subjectAltName)) could not be checked. The validation period of the certificate has expired. The certificate is invalid.	KAVS8062-E
120	A memory shortage occurred.	KAVS0902-E
124	An unexpected error occurred. The libraries necessary for executing the HTTP connection job could not be loaded.	KAVS8058-E KAVS0990-E

To Page Top

(3) Return codes of event jobs and action jobs

For details about the return codes that can be set while an event job or action job is being executed (from the start to the end of a job process), see A. Return Values from Event Jobs and Action Jobs.

To Page Top