3.1.3 Job steps

The job step is a unit of job execution and is a part of a job definition script consisting of a group of commands. When you allocate regular files and temporary files, you can define the files that are valid only within one job step. Such files are postprocessed when the job step in which the files were allocated terminates.

Several job steps are mutually related. If one job step is not processed correctly, execution of the next job step might be meaningless. In such a case, you can specify job step execution conditions so that subsequent processing is skipped.

Jobs steps are used for the following purposes:

Automating command and program error processing
Controlling shell script execution in units of job steps

Organization of this subsection

(1) Automating termination processing and log output in the event of a command error
(2) Controlling execution in units of job steps

(1) Automating termination processing and log output in the event of a command error

Conventional scripts require the return code to be checked, error messages output, temporary files deleted, and other error handling procedures to be performed for each command that is executed.

A job step enables you to monitor the return code of a command executed within the job step, output an error message, delete temporary files, and perform predefined processing (such as an error handling procedure).

The following shows an example script that uses job steps to automate termination processing and output a log in the event of an error.

Comparison based on whether job steps are used

When job steps are not used

01  progA
02  ret=$?
03  if [[ $ret != 0 ]]; then    --- (1)
04    echo "progA error"        --- (1)
05    exit $ret                 --- (1)
06  fi                          --- (1)
07
08  TEMP="/tmp/tempfile"
09
10  progB ${INFILE_B} ${TEMP}
11  ret=$?
12  if [[ $ret != 0 ]]; then
13    echo "progB error"
14    rm ${TEMP}                --- (2)
15    exit $ret
16  fi
17
18  progC ${TEMP} ${OUTFILE_C}
19  ret=$?
20  if [[ $ret != 0 ]]; then
21    echo "progC error"
22  fi
23
24  rm ${TEMP}                  --- (2)
25  exit $ret

When job steps are used

01  #-adsh_job J01
02
03  #-adsh_step_start S01        --- (1)
04    progA
05  #-adsh_step_end
06
07  #-adsh_step_start S02
08    #-adsh_file_temp TEMP      --- (2)
09    progB ${INFILE_B} ${TEMP}
10    progC ${TEMP} ${OUTFILE_C}
11  #-adsh_step_end

The following explains (1) and (2) in the example script.

About (1)

If you do not use job steps, you must check for an error each time a command is executed, and then code error message output processing and script cancellation processing.

On the other hand, if you define a group of commands as a job step, you can output an error message automatically in the event of an error, and then terminate the job step without executing the subsequent commands.

About (2)

If no job step is used, the user must code each and every process for deleting the created temporary files.

If a job step is used, the temporary files allocated for the job step by JP1/Advanced Shell's temporary file function are deleted automatically when the job step terminates.

When you use job steps, processes such as in (1) and (2) above can be automated. The following shows the log output results in the case where progB results in an error.

Job execution logs (excerpt)

********  JOB CONTROLLER MESSAGE  ********
17:05:25 000515 KNAX0091-I J01 The job started.
17:05:25 000515 KNAX7901-I The adshexec command will wait for all asynchronous processes at the end of the job.
17:05:25 000515 KNAX7902-I The adshexec command will run in tty stdin mode.
17:05:25 000515 KNAX0092-I J01.S01 step started.
17:05:25 000515 KNAX6116-I Execution of the command ./progA (line=4) finished successfully. exit status=0 execution time=0.000s CPU time=0.000s
17:05:25 000515 KNAX6597-I J01.S01 step succeeded. exit status=0 execution time=0.001s CPU time=0.000s
17:05:25 000515 KNAX0092-I J01.S02 step started.
17:05:25 000515 KNAX1601-I J01.S02 Allocation of file(s) for a step started.
17:05:25 000515 KNAX6409-I The file TEMP was allocated as "create". path=/var/opt/jp1as/temp/TEMP_000515_J01_CGNCtb
17:05:25 000515 KNAX6521-E The command ./progB (line=9) failed. exit status=1 execution time=0.000s CPU time=0.000s  ... (1)
17:05:25 000515 KNAX6410-I The file TEMP was deallocated as "del". path=/var/opt/jp1as/temp/TEMP_000515_J01_CGNCtb
17:05:25 000515 KNAX1604-I The file /var/opt/jp1as/temp/TEMP_000515_J01_CGNCtb was deleted.                          ... (2)
17:05:25 000515 KNAX6596-E J01.S02 step failed. exit status=1 execution time=0.002s CPU time=0.000s
17:05:25 000515 KNAX0101-E J01 An error occurred during execution of the job.
17:05:25 000515 KNAX0098-I J01 The job ended. exit status=1 execution time=0.006s CPU time=0.000s                    ... (3)

The following explains job execution logs (1) through (3):

About (1): The command resulted in an error, so the subsequent commands were not executed.
About (2): A temporary file allocated by JP1/Advanced Shell's temporary file function was deleted automatically.
About (3): The job terminated with the return code specified in the error handling procedure.

To Page Top

(2) Controlling execution in units of job steps

You can define a group of related commands as a job step and control job execution according to the results of the job step's processing. JP1/Advanced Shell provides various functions for controlling execution in units of job steps.

The following shows an example script that controls execution in units of job steps.

Comparison based on whether job steps are used

When job steps are not used

01  retmax=0
02  VAR=`progA`
03  export VAR
04  progB
05
06  tempVAR=$VAR                       --- (1)
07  VAR=`progC`
08  progD
09  retD=$?                            --- (2)
10  if [[ $retmax -lt $retD ]]; then
11    retmax=$retD                     --- (3)
12  fi
13  VAR=$tempVAR                       --- (1)
14
15  if [[ $retD -ge 16 ]]; then        --- (4)
16    exit $retD
17  fi
18
19  if [[ $retD -ne 0 ]]; then         --- (5)
20    if [[ $retD -eq 4 ]]; then       --- (2)
21      result="progD: warning"
22    else
23      result="progD: error"
24    fi
25    progE $result
26    retE=$?
27    if [[ $retmax -lt $retE ]]; then
28      retmax=$retE                   --- (3)
29    fi
30    if [[ $retE -ge 16 ]]; then      --- (4)
31      exit $retE
32    fi
33  fi
34
35  progF                              --- (6)
36  exit $retmax                       --- (3)

When job steps are used

01  #-adsh_job_stop 16:                     --- (4)
02  VAR=`progA`
03  export VAR
04  progB
05
06  #-adsh_step_start S01 -stepVar VAR      --- (1)
07    VAR=`progC`
08    export VAR
09    progD
10  #-adsh_step_end
11
12  #-adsh_step_start S02 -run abnormal     --- (5)
13    if [[ $ADSH_STEPRC_S01 -eq 4 ]]; then --- (2)
14      result="STEP01: warning"
15    else
16      result="STEP01: error"
17    fi
18    progE $result
19  #-adsh_step_end
20
21  #-adsh_step_start S03 -run always       --- (6)
22    progF
23    exit $ADSH_RC_STEPMAX                 --- (3)
24  #-adsh_step_end

The following explains (1) through (6) in the example script.

About (1)

If you do not use job steps, using a shell variable with a duplicated name for another purpose requires a separate process (such as saving its value temporarily in another variable).

If you use a job step, you can use shell variables that are valid only within the job step by using the stepVar attribute of the #-adsh_step_start extended script command to declare the variable names.

About (2)

If you do not use job steps, to branch processing based on the return code of a specific command, you must store the command's return code in a separate shell variable.

If you use job steps, you can reference each job step's return code, which is set automatically by JP1/Advanced Shell.

About (3)

If you do not use job steps, to reference the maximum value of a command's return code, you must update the maximum value each time the command is executed.

If you use job steps, you can reference the maximum value of each job step's return code, which is set automatically by JP1/Advanced Shell.

About (4)

If you do not use job steps, to terminate a script when a command's return code exceeds a threshold value, you must check the threshold value each time a command is executed.

If you use job steps, you can monitor each job step's return code automatically by using the #-adsh_job_stop extended script command to declare the threshold value.

About (5)

If you do not use job steps, you must control execution by determining whether the subsequent processing is to be executed based on a command's return code.

If you use job steps, you can define that a job step is to be executed only when the preceding process results in an error. You do this by specifying abnormal in the run attribute of the #-adsh_step_start extended script command.

About (6)

If you use job steps, you can define a job step to always execute, regardless of whether the preceding process was successful. You do this by specifying always in the run attribute of the #-adsh_step_start extended script command.

To Page Top