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
- 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.
- #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 ******** 15:02:55 000042 KNAX0091-I ADSH000042 The job started. 15:02:55 000042 KNAX7901-I The job controller will wait for all asynchronous processes at the end of the job. 15:02:55 000042 KNAX7902-I The job controller will run in tty stdin mode. 15:02:55 000042 KNAX6831-I The command definition matched the rule specified by the environment settings parameter CHILDJOB_SHEBANG. script="./cld.sh" shebang="/bin/sh" >>>>>> [JOBLOG] /home/usr/cld.sh 15:02:55 000043 KNAX6571-I The child job ADSH000043 started. parent job=ADSH000042 parent job ID=000042 15:02:55 000043 KNAX6572-I The child job ADSH000043 will use the job environment file "/opt/jp1as/conf/adsh.conf". 15:02:55 000043 KNAX7902-I The job controller will run in tty stdin mode. 15:02:55 000043 KNAX6110-I Execution of the command val=10 (line=2) finished successfully. exit status=0 execution time=0.000s CPU time=0.000s 15:02:55 000043 KNAX6015-E No argument is specified. filename="/home/usr/cld.sh" line=3 15:02:55 000043 KNAX6521-E The command unset (line=3) failed. exit status=1 execution time=0.000s CPU time=0.000s 15:02:55 000043 KNAX6584-I A job stopped because a command that terminates execution of the script was executed. 15:02:55 000043 KNAX0101-E ADSH000043 An error occurred during execution of the job. 15:02:55 000043 KNAX6578-I The child job ADSH000043 ended. exit status=8 execution time=0.001s CPU time=0.000s <<<<<< [JOBLOG] /home/usr/cld.sh 15:02:55 000042 KNAX6521-E The command ./cld.sh (line=1) failed. exit status=8 execution time=0.027s CPU time=0.000s 15:02:55 000042 KNAX6116-I Execution of the command ./cmdA (line=2) finished successfully. exit status=0 execution time=0.001s CPU time=0.000s 15:02:55 000042 KNAX0101-E ADSH000042 An error occurred during execution of the job. 15:02:55 000042 KNAX0098-I ADSH000042 The job ended. exit status=0 execution time=0.030s CPU time=0.000s ******** Script IMAGE ******** ***** /home/usr/prt.sh ***** 0001 : ./cld.sh 0002 : ./cmdA 0003 : ***** CONVERSION INFORMATION ***** ***** /home/usr/cld.sh ***** 0001 : #!/bin/sh 0002 : val=10 0003 : unset 0004 : ./cmdX $val 0005 : ***** CONVERSION INFORMATION ***** ******** JOB SCOPE STDERR ******** >>>>>> [STDERR] /home/usr/cld.sh KNAX0726-I The child job ID was assigned. job ID=000043 KNAX0101-E ADSH000043 An error occurred during execution of the job. KNAX0240-I The setting specified for the environment variable ADSH_JOBRC_FATAL was applied. value=8 <<<<<< [STDERR] /home/usr/cld.sh KNAX0101-E ADSH000042 An error occurred during execution of the job. KNAX0098-I ADSH000042 The job ended. exit status=0 execution time=0.030s 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/000042-ADSH000042/" 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 ******** 17:15:38 000155 KNAX0091-I ADSH000155 The job started. 17:15:38 000155 KNAX7901-I The job controller will wait for all asynchronous processes at the end of the job. 17:15:38 000155 KNAX7902-I The job controller will run in tty stdin mode. 17:15:38 000155 KNAX6832-I The command definition matched the rule specified by the environment settings parameter CHILDJOB_EXT. script=".\cld.sh" >>>>>> [JOBLOG] c:\home\usr\cld.sh 17:15:38 000156 KNAX6571-I The child job ADSH000156 started. parent job=ADSH000155 parent job ID=000155 17:15:38 000156 KNAX6572-I The child job ADSH000156 will use the job environment file "c:\jp1as\conf\adsh.conf". 17:15:38 000156 KNAX7902-I The job controller will run in tty stdin mode. 17:15:38 000156 KNAX6110-I Execution of the command val=10 (line=2) finished successfully. exit status=0 execution time=0.000s CPU time=0.000s 17:15:38 000156 KNAX6015-E No argument is specified. filename="c:\home\usr\cld.sh" line=3 17:15:38 000156 KNAX6521-E The command unset (line=3) failed. exit status=1 execution time=0.000s CPU time=0.000s 17:15:38 000156 KNAX6584-I A job stopped because a command that terminates execution of the script was executed. 17:15:38 000156 KNAX0101-E ADSH000156 An error occurred during execution of the job. 17:15:38 000156 KNAX6578-I The child job ADSH000156 ended. exit status=16 execution time=0.000s CPU time=0.000s <<<<<< [JOBLOG] c:\home\usr\cld.sh 17:15:38 000155 KNAX6521-E The command .\cld.sh (line=1) failed. exit status=16 execution time=0.062s CPU time=0.015s 17:15:38 000155 KNAX6116-I Execution of the command .\cmdA.exe (line=2) finished successfully. exit status=0 execution time=0.016s CPU time=0.016s 17:15:38 000155 KNAX0101-E ADSH000155 An error occurred during execution of the job. 17:15:38 000155 KNAX0098-I ADSH000155 The job ended. exit status=0 execution time=0.078s CPU time=0.047s ******** Script IMAGE ******** ***** c:\home\usr\prt.sh ***** 0001 : .\\cld.sh 0002 : .\\cmdA 0003 : ***** CONVERSION INFORMATION ***** ***** c:\home\usr\cld.sh ***** 0001 : #!/bin/sh 0002 : val=10 0003 : unset 0004 : .\\cmdX $val 0005 : ***** CONVERSION INFORMATION ***** ******** JOB SCOPE STDERR ******** >>>>>> [STDERR] c:\home\usr\cld.sh KNAX0726-I The child job ID was assigned. job ID=000156 KNAX0101-E ADSH000156 An error occurred during execution of the job. KNAX0240-I The setting specified for the environment variable ADSH_JOBRC_FATAL was applied. value=16 <<<<<< [STDERR] c:\home\usr\cld.sh KNAX0101-E ADSH000155 An error occurred during execution of the job. KNAX0098-I ADSH000155 The job ended. exit status=0 execution time=0.078s CPU time=0.047s ******** JOBSTEP OUTPUT ******** KNAX6380-I A job name will be added to the spool job directory of the root job. spool job directory="C:\Users\Public\Documents\Hitachi\JP1AS\JP1ASE\spool\000155 -ADSH000155\" 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.