5.8.3 Defining job steps
The job step definition commands whose names begin with #-adsh_step are used to group a portion of a job definition script as a job step. A job step consists of a group of commands.
- Organization of this subsection
(1) How to group commands
A group of commands normally executed as a job step is specified in a block from the #-adsh_step_start command to the #-adsh_step_error or #-adsh_step_end command. This block is called a job step normal block.
A group of commands that is executed only if the last command in the job step normal block terminates with an error is specified in a block from the #-adsh_step_error command to the #-adsh_step_end command. This block is called a job step error block.
(2) Flow of job step execution
The following describes the flow of job step execution.
Whether the job step is to be skipped is determined based on the preceding job step having terminated with an error, based on whether any commands terminated with an error, or based on the run attribute's specification. For details about the run attribute, see 9.5.9 #-adsh_step_start command, #-adsh_step_error command, #-adsh_step_end command (defines a job step) in 9.5 Extended script commands.
The commands in the job step normal block are executed sequentially. If any of the commands terminates with an error and the onError attribute is stop, JP1/Advanced Shell exits the job step normal block without executing the subsequent commands. If the onError attribute is cont, JP1/Advanced Shell executes the subsequent commands and then exits the job step normal block.
If #-adsh_step_error is defined and the last command in the job step normal block terminates with an error, the commands in the job step error block are executed sequentially by JP1/Advanced Shell.
(3) Declaring shell variables that are valid only within a job step
You can declare shell variables that are to be valid only within the current job step by specifying the stepVar attribute. When the declared shell variables are exported, they are placed in exported status only within the job step.
When the job step begins, the job controller automatically places the shell variables in undefined status. However, if the PATH shell variable is defined to be valid only within the job step, the values before the job step started are inherited.
When the job step terminates, the job controller automatically resets the shell variables to their status when the job step started.
You can declare shell variables with the same names as shell variables outside the job step. The following notes apply when you declare such shell variables:
A declared shell variable is treated as different from other shell variable with the same name outside the job step.
When the job step starts, a declared shell variable is placed in undefined status. The value of a shell variable with the same name outside the job step is not inherited because it is treated as a separate shell variable.
A shell variable with the same name outside the job step cannot be referenced or updated within the current job step.
After the job step has terminated, a shell variable with the same name outside the job step can be referenced and updated again.
The following shows a usage example.
- Usage example of a job definition script file:
01: VAL1=AAA 02: echo "Before starting the step (outside the step)" 03: echo "beforeStepVar1="$VAL1 04: echo "beforeStepVar2="$VAL2 05: 06: #-adsh_step_start S1 -stepVar VAL1,VAL2 07: echo "The step has started" 08: echo "startStepVar1="$VAL1 09: echo "startStepVar2="$VAL2 10: VAL1=XXX 11: VAL2=YYY 12: echo "endStepVar1="$VAL1 13: echo "endStepVar2="$VAL2 14: #-adsh_step_end 15: 16: echo "The step was terminated" 17: echo "afterStepVar1="$VAL1 18: echo "afterStepVar2="$VAL2
This example declares VAL1 that has a shell variable with the same name outside the job step and VAL2 that does not have a shell variable with the same name outside the job step.
The following shows the execution results:
Before starting the step (outside the step) beforeStepVar1=AAA <-- References VAL1 outside the job step. This is a different variable from VAL1 inside the job step. beforeStepVar2= <-- References VAL2 outside the job step, but a nonexistent step was started. startStepVar1= <-- References VAL1 inside the job step. This is a different variable from VAL1 outside the job step. startStepVar2= endStepVar1=XXX endStepVar2=YYY The step was terminated afterStepVar1=AAA <-- References VAL1 outside the job step. This is a different variable from VAL1 inside the job step. afterStepVar2= <-- References VAL2 outside the job step, but it does not exist.
If you specify PATH in a shell variable that is valid only within the job step, you can add a path to the PATH shell variable that is valid only in that job step. The initial value of the PATH shell variable is the value in effect before the job step starts.
The following example shows how to add paths to the PATH shell variable that are valid only within the current job step. This example assumes that the value of the PATH shell variable is a:b when execution of the job definition script begins.
#-adsh_job J1 --> 1. cmdA PATH=x:$PATH --> 2. cmdB #-adsh_step_start S1 -stepVar PATH --> 3. cmdC PATH=y:$PATH --> 4. cmdD #-adsh_step_end --> 5.
The numbers in this example correspond to the numbers in the following explanation:
The initial value of PATH is a:b.
Valid inside the job step. The value of PATH becomes x:a:b.
Specifies PATH for stepVar. The shell variable remains undeleted and the value remains as x:a:b.
Valid inside the job step. The value of PATH becomes y:x:a:b.
Resets PATH to the value in effect when the job step started. The value of PATH becomes x:a:b.
If you use the PATH_CONV_VAR parameter or #-adsh_path_var command, you can define and use the shell variable that converts the path of directory between Windows and UNIX. For details of this function, see 5.8.5 Defining shell variables that handle path names.
(4) Specifying the job step return code in the event of a job step error
You can set a desired return code for a job step in the event of a job step error. To do this, execute the exit command with the desired return code specified in its argument inside the job step error block. In this case, the value specified in the argument of the exit command is also set as the job's return code because the job is terminated by the exit command.
The value specified in the argument of the exit command also becomes the return code of job step when a . (dot) command or #-adsh_script command is used within the job step error block to call an external script and then the exit command with the argument specified is executed inside the called external script.
The following example executes the exit command with the argument specified inside the job step error block:
#-adsh_step_start STEP1 cmdA cmdB <-- Terminated in an error with return code 1. cmdC #-adsh_step_error exit 4 <-- The job step terminates with an error and the exit command's argument 4 becomes the return code of the job step. #-adsh_step_end
If the exit command with no argument specified is executed inside the job step error block, the return code of the last command executed within the job step normal block becomes the job step's return code.
The following example executes the exit command with no argument specified inside the job step error block:
#-adsh_step_start STEP1 cmdA cmdB <-- Error termination with return code 1. cmdC #-adsh_step_error exit <-- The job step terminates with an error. Because the exit command has no arguments, the return code of cmdB becomes the return code of the job step. #-adsh_step_end
(5) Job step execution examples
The following shows example job definition script file executions in which all commands terminate normally and in which an intermediate command terminates with an error.
Example execution in which all commands terminate normally
#!/opt/jp1as/bin/adshexec #-adsh_job JOB001 #-adsh_step_start STEP001 command1 <-- Executed. command2 <-- Executed. command3 <-- Executed. #-adsh_step_error command4 <-- Not executed. command5 <-- Not executed. #-adsh_step_end #-adsh_step_start STEP002 command6 <-- Executed. #-adsh_step_end #-adsh_step_start STEP003 -run abnormal command7 <-- Not executed. #-adsh_step_end #-adsh_step_start STEP004 -run always command8 <-- Executed. #-adsh_step_end
Example execution in which command2 terminates with an error (onError attribute is stop)
#!/opt/jp1as/bin/adshexec #-adsh_job JOB001 #-adsh_step_start STEP001 -onError stop command1 <-- Executed. command2 <-- Executed (error termination). command3 <-- Not executed. #-adsh_step_error command4 <-- Executed. command5 <-- Executed. #-adsh_step_end #-adsh_step_start STEP002 command6 <-- Not executed. #-adsh_step_end #-adsh_step_start STEP003 -run abnormal command7 <-- Executed. #-adsh_step_end #-adsh_step_start STEP004 -run always command8 <-- Executed. #-adsh_step_end
Example execution in which command2 terminates with an error (onError attribute is cont)
#!/opt/jp1as/bin/adshexec #-adsh_job JOB001 #-adsh_step_start STEP001 -onError cont command1 <-- Executed. command2 <-- Executed (error termination). command3 <-- Executed. #-adsh_step_error command4 <-- Not executed. command5 <-- Not executed. #-adsh_step_end #-adsh_step_start STEP002 command6 <-- Executed. #-adsh_step_end #-adsh_step_start STEP003 -run abnormal command7 <-- Not executed. #-adsh_step_end #-adsh_step_start STEP004 -run always command8 <-- Executed. #-adsh_step_end
If a command outside the job step results in an error, the subsequent job definition script is handled as follows:
The subsequent commands outside the job step are executed.
The subsequent commands whose run attribute is normal are not executed.
The subsequent job steps whose run attribute is abnormal or always are executed.
The following shows an execution example:
#-adsh_job CMD_ERROR echo "Job start." cd -x #Command that results in an error <--This command results in an error. echo "Job end." <--Commands outside the job step execute. #-adsh_step_start STEP01 -run normal <--Does not execute a job step for which run normal is specified. echo "command in step" #-adsh_step_end #-adsh_step_start STEP02 -run abnormal <--Executes a job step for which run abnormal is specified. echo "command in step" #-adsh_step_end #-adsh_step_start STEP03 -run always <--Executes a job step for which run always is specified. echo "command in step" #-adsh_step_end
If a job step results in an error, whether the subsequent job step is to be executed is determined by the run attribute of the subsequent job step. Commands outside the subsequent job step will not be executed. The following shows an execution example:
#-adsh_job STEP_ERROR #-adsh_step_start STEP01 echo "Step start." cd -x #Command that results in an error echo "Step end." #-adsh_step_end <--The job step terminates with an error. echo "Job end." <--If the preceding job step resulted in an error, commands outside the subsequent job step do not execute.
The return code of a command executed inside the job step error block has no effect on the return code of the job step. The return code of the last command executed inside the job step normal block becomes the return code of the job step. The following shows an execution example:
#-adsh_job STEP_ERRBLK_RC #-adsh_step_start STEP01 echo "Step start." cd -x #Command that results in an error with rc=1 <--The result of this command becomes the return code of the job step. echo "Step end." #-adsh_step_error echo "step error block" #Command that results in rc=0 <--No effect on the job step's rc. #-adsh_step_end <--The error result of the cd command is applied and the job step terminates with rc=1.
(6) The relationship of shell functions and the trap command
Regardless of where a shell function or action of a trap command was defined, whether the shell function or action is executed inside or outside of a job step is determined by where the shell function or action was executed.