exit_codes
Theme: Configure
Who Is It For? System Administrator
What is it?
Reference for the exit_codes utility, which runs a job and displays its return values, exit code, exit signal, and core image status for debugging purposes.
- You are configuring Failure Criteria for a job in OpCon and need to confirm what exit code the job's executable returns under normal and error conditions.
- You are debugging a job that is reporting an unexpected status and want to verify the numeric exit code, exit signal, and whether a core image was created.
The exit_codes utility runs a job and displays the return values. Helpful for debugging, this information aids in determining the expected results for a job in OpCon.
This utility displays the following information when a job completes:
- Start image
- User ID used
- Group ID used
- Job start date/time
- Job end date/time
- Numeric exit code
- Numeric exit signal
- If a core image was created. This information is displayed in binary format (i.e., 1 = Yes, 0 = No).
For dependable results, the job specified in the Start Image must explicitly perform an exit () call. Most UNIX implementations return a zero when a process completes normally; however, some UNIX implementations return 18 when a process completes normally.
Syntax
exit_codes -u# -g# -s"<start image>"
Parameters
| Parameter | Required | Description |
|---|---|---|
-u# | Required | User ID under which the job runs. |
-g# | Required | Group ID under which the job runs. |
-s"<start image>" | Required | Start image and arguments for the job. |
Exception handling
Job always returns exit code 0 regardless of the actual outcome — The job's executable does not explicitly call exit(), and some UNIX implementations return 0 when a process completes normally regardless of the program's intent. — Modify the script to explicitly call exit() with a meaningful code. If exit codes are not available, use STDOUT redirection with Failure Criteria instead.
Exit code is not in the expected range — An exit code outside the -127 to +127 range was specified. UNIX truncates codes outside this range, producing unexpected values. — Ensure all exit() calls in the job use a code within -127 to +127.
Examples
The following example shows the command to run the agent's generic program, genericpgm, from the /usr/local/lsam/bin directory. The generic program's parameters cause the job to run for two seconds and to terminate with an exit code of three:
exit_codes -u0 -g0 -s"/usr/local/lsam/bin/genericpgm -t2 -e3"
The following output displays on the screen with the exit_codes utility processes the job:
/usr/local/lsam/bin/genericpgm started at Fri Oct 31 12:09:03 2003
/usr/local/lsam/bin/genericpgm - Arguments : time: 2 exit: 3 signal: 0 core : N
/usr/local/lsam/bin/genericpgm ERRORED at Fri Oct 31 12:09:05 2003
Start image : /usr/local/lsam/bin/genericpgm -t2 -e3
User-id used : 0
Group used : 0
Job started : Fri Oct 31 12:09:03 2003
Job finished : Fri Oct 31 12:09:07 2003
Exit status : 3
Exit signal : 0
Core image created : 0
Glossary
exit code — A numeric value returned by a process when it completes. The Unix Agent reads this value to determine whether an OpCon job succeeded or failed. Valid range: -127 to +127.
exit signal — A numeric value indicating whether the process was terminated by a signal (non-zero) or exited normally (0). Displayed alongside the exit code in exit_codes output.
core image — A file written to disk when a process terminates abnormally. Displayed in binary format by exit_codes (1 = created, 0 = not created).