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