Hitachi

Job Management Partner 1 Version 10 Job Management Partner 1/Advanced Shell Description, User's Guide, Reference, and Operator's Guide

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.

Table 2‒17: Whether the ADSH_JOBRC_FATAL environment variable setting is applied by error type

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:

  • adshexec.exe

  • adshexecsub.exe

  • adshesub.exe

  • adshedit.exe

N

6

All errors other than those listed in 2 to 5 above. The typical errors are as follows:

  • Command line parsing errors in the adshexec command

  • Invalid status errors in a job definition script file specified in the adshexec command's argument

  • Environment file parsing errors

  • Job definition script parsing errors

  • Initialization errors in the job execution log, system execution log, and trace log

  • Initialization errors in asc files

  • (Windows only) License check errors

  • (Windows only) Errors resulting from a reception of control signal (CTRL + C, CTRL + BREAK, CTRL_CLOSE_EVENT)

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:

  • (UNIX only) Executing of the kill or quit command or re-execution of the run command

  • (Windows only) Selecting the Quit Debugging menu, clicking the Quit Debugging button, or closing the editor window to cancel 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:

  • adshexec.exe

  • adshexecsub.exe

  • adshesub.exe

  • adshedit.exe

N

11

This includes all errors other than those listed in 7 to 10 above. The typical errors are as follows:

  • Special built-in command errors (excluding the typeset errors and the errors in the return command executed within a function or an external script)

  • Assignment operation errors#5

  • Errors in variable substitution in a job termination format#6

  • Errors caused by the specification of an out-of-range array element (outside the range from 0 to 65535)

  • Resource allocation errors caused by a shortage of memory and disk capacity

  • Input/output errors

  • Internal conflict errors

  • (Windows only) Errors resulting from a reception of control signal (CTRL + C, CTRL + BREAK, CTRL_CLOSE_EVENT)

  • (Windows only) Errors resulting from the execution of a conditional expression containing the operator -h, -G, -L, -O, or -ef (except when a value other than ERR is specified in the UNSUPPORT_TEST parameter)

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:

  • Parsing errors in the files allocated by an extended script command

  • Postprocessing errors in spool job management files

  • Postprocessing errors in the root job's spool job directory

  • Post processing errors in event files

N

14

(Windows only) Errors that occur if any of the following processes is terminated immediately by a function such as TerminateProcess:

  • adshexec.exe

  • adshexecsub.exe

  • adshesub.exe

  • adshedit.exe

N

15

All errors other than those listed in 12 to 14 above. The typical errors are as follows:

  • Postprocessing errors in the asc files

  • Child jobs' spool job directory deletion errors

  • (UNIX only) DBG file parsing errors

  • Internal conflict errors

  • (Windows only) Errors resulting from a reception of control signal (CTRL + C, CTRL + BREAK, CTRL_CLOSE_EVENT)

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.

To Page Top

(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:

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:

  1. This is a message indicating that the ADSH_JOBRC_FATAL environment variable was applied.

  2. 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:

  1. The setting of the ADSH_JOBRC_FATAL environment variable was applied as the child job's return code.

  2. 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:

  1. This is a message indicating that the ADSH_JOBRC_FATAL system environment variable was applied.

  2. 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:

  1. The setting of the ADSH_JOBRC_FATAL environment variable was applied as the child job's return code.

  2. This is a message indicating that the ADSH_JOBRC_FATAL system environment variable was applied to the child job.

To Page Top

Trademarks

All Rights Reserved. Copyright (C) 2014, 2015, Hitachi, Ltd.