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
(2) Flow of job step execution
(3) Declaring shell variables that are valid only within a job step
(4) Specifying the job step return code in the event of a job step error
(5) Job step execution examples
(6) The relationship of shell functions and the trap command

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

To Page Top

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

To Page Top

(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, JP1/Advanced Shell 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, JP1/Advanced Shell 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 the current job step. For the initial value of PATH, the value in effect before the job step starts is inherited.

The example shown below adds paths to the PATH shell variable that is valid only in the 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 the example of adding paths to a PATH shell variable that is valid only in the current job step 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.

When you use the #-adsh_path_var command, you can define and use the shell variables for converting directory paths between Windows and UNIX. For details about this function, see 5.8.5 Defining shell variables that handle path names.

To Page Top

(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

To Page Top

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

To Page Top

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

To Page Top