2.6.15 Defining the return code in the event of an unresumable error in a job
If a job is terminated due to an error, such as a memory shortage or a job definition script parsing error, the job controller's return code is set to 1. You can change this return code to any value from 1 to 255 by setting a value in the ADSH_JOBRC_FATAL environment variable.
For details about how to specify the ADSH_JOBRC_FATAL environment variable, see (2) ADSH_JOBRC_FATAL environment variable (specifies the return code in the event of an unresumable error in jobs).
- Organization of this subsection
(1) Whether the ADSH_JOBRC_FATAL environment variable can be applied
The following table lists the types of errors that might occur while the job controller is running and whether the return code defined in the ADSH_JOBRC_FATAL environment variable can be applied.
No. |
Timing of error |
Error type |
Applicability#1 |
---|---|---|---|
1 |
When a job is started by the adshexec command or a job definition script is debugged from the editor |
Errors that prevent the OS from starting execution of the adshexec command. For example, this type of error occurs when the load module that is used by the adshexec command does not exist. |
N |
2 |
Before a job definition script is run |
Parsing errors in the ADSH_JOBRC_FATAL environment variable |
N#2 |
3 |
Event file initialization errors |
N |
|
4 |
(UNIX only) Errors that occur during signal reception |
N#3 |
|
5 |
(Windows only) Errors that occur if any of the following processes is terminated immediately by a function such as TerminateProcess:
|
N |
|
6 |
All errors other than those listed in 2 to 5 above. The typical errors are as follows:
|
Y |
|
7 |
While a job definition script is running |
Errors that do not stop job definition script processing#4 |
N |
8 |
Errors caused when a job is terminated by using the debugger's command, menu, or button listed below during debugging:
|
N |
|
9 |
(UNIX only) Errors that occur during signal reception |
N#3 |
|
10 |
(Windows only) Errors that occur if any of the following processes is terminated immediately by a function such as TerminateProcess:
|
N |
|
11 |
This includes all errors other than those listed in 7 to 10 above. The typical errors are as follows:
|
Y |
|
12 |
After execution of a job definition script |
(UNIX only) Errors that occur during signal reception |
N#3 |
13 |
The following errors related to files and directories:
|
N |
|
14 |
(Windows only) Errors that occur if any of the following processes is terminated immediately by a function such as TerminateProcess:
|
N |
|
15 |
All errors other than those listed in 12 to 14 above. The typical errors are as follows:
|
Y |
- Legend:
-
Y: The setting of the ADSH_JOBRC_FATAL environment variable takes effect.
N: The setting of the ADSH_JOBRC_FATAL environment variable does not take effect.
- #1
-
The options specified in the adshexec command do not affect whether the setting of the ADSH_JOBRC_FATAL environment variable takes effect. For example, if the adshexec command with the -c option specified is executed and a syntax error occurs, the ADSH_JOBRC_FATAL environment variable setting still takes effect.
This applicability depends on the OS as follows:
-
In UNIX, the -d option is specified in the adshexec command
For the debugger and the jobs subject to debugging that are executed by the run command, the following items in the table are checked to determine the applicability:
Debugger: Items 1 to 6 and 12 to 15
Jobs subject to debugging: Items 7 to 15
-
In Windows, debugging is executed from the editor
For the jobs to be debugged, items 1 to 15 in the table are checked to determine the applicability.
-
- #2
-
The return code is 255.
- #3
-
If the job controller receives a signal and the job terminates with an error, the job's return code is 128 + the signal number.
- #4
-
If an extended script command results in an error while a job definition script is running, the subsequent job steps and commands listed below are not executed; however, this is not treated as an unresumable error. Therefore, the setting of the ADSH_JOBRC_FATAL environment variable does not take effect.
-
Job steps whose run attribute is omitted or normal
-
Instructions outside job steps
-
- #5
-
This does not apply when an assignment operation is specified in the argument of a regular built-in command.
The table below shows the classification of assignment operation specifications and whether the setting of the ADSH_JOBRC_FATAL environment variable is applied. The error indicated in this table occurs if an attempt is made to assign a value to the NUM variable that has been defined as being read-only in readonly NUM.
Classification of assignment operation specification
Example of error
Applicability
An assignment operation is specified on its own.
NUM=100
Y
An assignment operation is specified in the argument of a reserved script command.
time NUM=100
Y
An assignment operation is specified in the argument of a special built-in command.
export NUM=100
Y
An assignment operation is specified in the argument of a regular built-in command.
let NUM=100
N
- #6
-
As a result of variable substitution, the job might become unresumable and be terminated with an error depending on the status of variable. The following shows the status of variable that results in an error for each format:
- ${variable:?[word]}
-
If variable has been defined and its value is null (empty character string) or is undefined, an error results.
- ${variable?[word]}
-
If variable is undefined, an error results.
(2) ADSH_JOBRC_FATAL environment variable (specifies the return code in the event of an unresumable error in jobs)
The ADSH_JOBRC_FATAL environment variable is used to specify the job controller's return code in the event a job becomes unresumable and is terminated with an error. The specified return code is applied to jobs that are executed by using the adshexec command and to jobs that are executed from JP1/Advanced Shell - Developer's editor.
The following shows how to apply the value of this environment variable globally in the entire system:
-
Windows
Define ADSH_JOBRC_FATAL as a system environment variable.
-
UNIX
Specify the ADSH_JOBRC_FATAL environment variable setting in /etc/profile.
If this environment variable is not specified and a job terminates with an unresumable error, the controller's return code is set to 1.
(a) Values permitted in the environment variable
- termination-code ~<unsigned integer> ((1 to 255))
-
Specifies the return code to be set when a job cannot be resumed. If the value is padded with leading zeros such as 001, the leading zeros are deleted and the value is treated as being 1.
(b) Notes
-
If the ADSH_JOBRC_FATAL environment variable is defined by using the export parameter in the environment file or the ADSH_JOBRC_FATAL environment variable is defined or changed within a file or a job definition script specified in the ENV shell variable, this functionality does not take effect within that job. The functionality takes effect on another job that is started from that job.
-
The ADSH_JOBRC_FATAL environment variable defines the final return codes for jobs. It does not affect the return codes of individual commands and job steps.
-
If any of the following values is set, the job terminates, without being executed, with an error with return code 255:
-
Value consisting of four or more characters (example: 1234)
-
Value outside the permitted range (example: 500)
-
Non-numeric characters (example: 1A4, +8, 8.0)
-
Value consisting of no character (null character string)
-
-
Whether the ADSH_JOBRC_FATAL environment variable is applied in the event of an error depends on each job. If an unresumable error occurs only within a root job or a child job, the ADSH_JOBRC_FATAL environment variable will not be applied to any other root job or child job to change its return code.
(c) Examples
The following shows an example of a UNIX job that was started with 8 set in the ADSH_JOBRC_FATAL environment variable and terminated with an unresumable error.
- The job could not be resumed because the directory specified in the SPOOL_DIR parameter in the environment file was not found:
-
- Contents of /etc/profile:
ADSH_JOBRC_FATAL=8 export ADSH_JOBRC_FATAL
- Command specification at the job start:
$ /opt/jp1as/bin/adshexec test.sh
The following shows the execution results:
KNAX0441-E The directory specified for the parameter "SPOOL_DIR" does not exist. line=1 KNAX0410-E An error occurred when parsing the environment file "sample.ase". For details, see the message output before this one. KNAX0240-I The setting specified for the environment variable ADSH_JOBRC_FATAL was applied. value=8 ...1. KNAX7999-I Advanced Shell ended. exit status=8 ...2.
The following explains execution results 1 and 2:
-
This is a message indicating that the ADSH_JOBRC_FATAL environment variable was applied.
-
The setting of the ADSH_JOBRC_FATAL environment variable was applied as the job controller's return code.
- A child job was terminated due to an error in the special built-in command (unset command).
-
- Contents of /etc/profile:
ADSH_JOBRC_FATAL=8 export ADSH_JOBRC_FATAL
- Contents of the environment file:
#-adsh_conf CHILDJOB_SHEBANG /bin/sh
- Contents of the root job's job definition script (prt.sh):
./cld.sh ./cmdA
- Contents of the child job's job definition script (cld.sh):
#!/bin/sh val=10 unset ./cmdX $val
- Command specification at the job start:
$ /opt/jp1as/bin/adshexec prt.sh
The following shows the execution results:
******** JOB CONTROLLER MESSAGE ******** 14:14:22 010467 KNAX0091-I ADSH010467 The job started. 14:14:22 010467 KNAX7901-I The adshexec command will wait for all asynchronous processes at the end of the job. 14:14:22 010467 KNAX7902-I The adshexec command will run in tty stdin mode. 14:14:22 010467 KNAX6831-I The command definition matched the rule specified by the environment settings parameter CHILDJOB_SHEBANG. script="./cld.sh" shebang="/bin/sh" 14:14:22 010467 KNAX6521-E The command ./cld.sh (line=1) failed. exit status=8 execution time=0.008s CPU time=0.000s 14:14:22 010467 KNAX6116-I Execution of the command ./cmdA (line=2) finished successfully. exit status=0 execution time=0.001s CPU time=0.000s 14:14:22 010467 KNAX0101-E ADSH010467 An error occurred during execution of the job. 14:14:22 010467 KNAX0098-I ADSH010467 The job ended. exit status=0 execution time=0.012s CPU time=0.000s ******** Script IMAGE ******** ***** /home/usr/work/prt.sh ***** 0001 : ./cld.sh 0002 : ./cmdA ***** CONVERSION INFORMATION ***** ******** JOB SCOPE STDERR ******** KNAX7901-I The adshexec command will wait for all asynchronous processes at the end of the job. KNAX0724-I The job ID was assigned. job ID=010468 KNAX0101-E ADSH010468 An error occurred during execution of the job. 14:14:22 010468 KNAX6571-I The child job ADSH010468 started. parent job=ADSH010467 parent job ID=010467 14:14:22 010468 KNAX7901-I The adshexec command will wait for all asynchronous processes at the end of the job. 14:14:22 010468 KNAX7902-I The adshexec command will run in tty stdin mode. 14:14:22 010468 KNAX6110-I Execution of the command val=10 (line=2) finished successfully. exit status=0 execution time=0.000s CPU time=0.000s 14:14:22 010468 KNAX6015-E No argument is specified. filename="/home/usr/work/cld.sh" line=3 14:14:22 010468 KNAX6521-E The command unset (line=3) failed. exit status=1 execution time=0.000s CPU time=0.000s 14:14:22 010468 KNAX6584-I A job stopped because a command that terminates execution of the script was executed. 14:14:22 010468 KNAX0101-E ADSH010468 An error occurred during execution of the job. 14:14:22 010468 KNAX6578-I The child job ADSH010468 ended. exit status=8 execution time=0.001s CPU time=0.000s KNAX0240-I The setting specified for the environment variable ADSH_JOBRC_FATAL was applied. value=8 KNAX0101-E ADSH010467 An error occurred during execution of the job. KNAX0098-I ADSH010467 The job ended. exit status=0 execution time=0.012s CPU time=0.000s ******** JOBSTEP OUTPUT ******** KNAX6380-I A job name will be added to the spool job directory of the root job. spool job directory="/var/opt/jp1as/spool/010467-ADSH010467/" KNAX7999-I Advanced Shell ended. exit status=0
The following explains execution results 1 and 2:
-
The setting of the ADSH_JOBRC_FATAL environment variable was applied as the child job's return code.
-
This is a message indicating that the ADSH_JOBRC_FATAL environment variable was applied to the child job.
The following shows an example of a Windows job that was started with 16 set in the ADSH_JOBRC_FATAL system environment variable and terminated with an unresumable error.
- The job could not be resumed because the directory specified in the LOG_DIR parameter in the environment file was not found.
-
This example specifies the following system environment variable and value:
-
Variable: ADSH_JOBRC_FATAL
-
Value: 16
- Command specification at the job start:
adshexec test.ash
The following shows the execution results:
KNAX0441-E The directory specified for the parameter "LOG_DIR" does not exist. line=1 KNAX0410-E An error occurred when parsing the environment file "sample.ase". For details, see the message output before this one. KNAX0240-I The setting specified for the environment variable ADSH_JOBRC_FATAL was applied. value=16 ...1. KNAX7999-I Advanced Shell ended. exit status=16 ...2.
The following explains execution results 1 and 2:
-
This is a message indicating that the ADSH_JOBRC_FATAL system environment variable was applied.
-
The setting of the ADSH_JOBRC_FATAL environment variable was applied as the job's return code.
-
- A child job was terminated due to an error in the special built-in command (unset command)
-
This example specifies the following system environment variable and value:
-
Variable: ADSH_JOBRC_FATAL
-
Value: 16
- Contents of the environment file:
#-adsh_conf CHILDJOB_SHEBANG /bin/sh
- Contents of the root job's job definition script (prt.sh):
./cld.sh ./cmdA
- Contents of the child job's job definition script (cld.sh):
#!/bin/sh val=10 unset ./cmdX $val
- Command specification at the job start:
adshexec prt.sh
The following shows the execution results:
******** JOB CONTROLLER MESSAGE ******** 15:01:30 000004 KNAX0091-I ADSH000004 The job started. 15:01:30 000004 KNAX7901-I The adshexec command will wait for all asynchronous processes at the end of the job. 15:01:30 000004 KNAX7902-I The adshexec command will run in tty stdin mode. 15:01:30 000004 KNAX6831-I The command definition matched the rule specified by the environment settings parameter CHILDJOB_SHEBANG. script=".\cld.sh" shebang="/bin/sh" 15:01:30 000004 KNAX6521-E The command .\cld.sh (line=1) failed. exit status=16 execution time=0.197s CPU time=0.077s 15:01:30 000004 KNAX6116-I Execution of the command .\cmdA.exe (line=2) finished successfully. exit status=0 execution time=0.030s CPU time=0.016s 15:01:30 000004 KNAX0101-E ADSH000004 An error occurred during execution of the job. 15:01:30 000004 KNAX0098-I ADSH000004 The job ended. exit status=0 execution time=0.233s CPU time=0.093s ******** Script IMAGE ******** ***** D:\work\prt.sh ***** 0001 : .\\cld.sh 0002 : .\\cmdA ***** CONVERSION INFORMATION ***** ******** JOB SCOPE STDERR ******** KNAX7901-I The adshexec command will wait for all asynchronous processes at the end of the job. KNAX0724-I The job ID was assigned. job ID=000005 KNAX0101-E ADSH000005 An error occurred during execution of the job. 15:01:30 000005 KNAX6571-I The child job ADSH000005 started. parent job=ADSH000004 parent job ID=000004 15:01:30 000005 KNAX7901-I The adshexec command will wait for all asynchronous processes at the end of the job. 15:01:30 000005 KNAX7902-I The adshexec command will run in tty stdin mode. 15:01:30 000005 KNAX6110-I Execution of the command val=10 (line=2) finished successfully. exit status=0 execution time=0.000s CPU time=0.000s 15:01:30 000005 KNAX6015-E No argument is specified. filename="D:\work\cld.sh" line=3 15:01:30 000005 KNAX6521-E The command unset (line=3) failed. exit status=1 execution time=0.000s CPU time=0.000s 15:01:30 000005 KNAX6584-I A job stopped because a command that terminates execution of the script was executed. 15:01:30 000005 KNAX0101-E ADSH000005 An error occurred during execution of the job. 15:01:30 000005 KNAX6578-I The child job ADSH000005 ended. exit status=16 execution time=0.012s CPU time=0.016s KNAX0240-I The setting specified for the environment variable ADSH_JOBRC_FATAL was applied. value=16 KNAX0101-E ADSH000004 An error occurred during execution of the job. KNAX0098-I ADSH000004 The job ended. exit status=0 execution time=0.233s CPU time=0.093s ******** JOBSTEP OUTPUT ******** KNAX6380-I A job name will be added to the spool job directory of the root job. spool job directory="C:\Documents and Settings\All Users\Documents\Hitachi\JP1AS\JP1ASE\spool\003115-ADSH003115\" KNAX7999-I Advanced Shell ended. exit status=0
The following explains execution results 1 and 2:
-
The setting of the ADSH_JOBRC_FATAL environment variable was applied as the child job's return code.
-
This is a message indicating that the ADSH_JOBRC_FATAL system environment variable was applied to the child job.
-