#-adsh_step_start command, #-adsh_step_error command, #-adsh_step_end command (defines a job step)

Format

#-adsh_step_start
     [job-step-name]
     [-successRC return-code-definition[,return-code-definition ...]]
     [-stepVar shell-variable-name[,shell-variable-name ...]]
     [-run {normal|abnormal|always}]
     [-onError {cont|stop}]
 
... processing in the job step... (job step normal block)
 
 [#-adsh_step_error]
 
 [... processing at the time of a job step error... (job step error block)]
 
#-adsh_step_end

To Page Top

Description

This command groups a portion of the job definition script into a job step. A job step is a set of commands assembled into a group. A maximum of 4,095 job step definitions can be specified.

For details about how to use job steps, see 5.8.3 Defining job steps.

For details about determining whether the commands executed within job steps terminate normally or result in an error, see 5.8.8 Return codes of jobs, job steps, and commands.

For details about handling errors in job steps, see 5.8.10 Processing in the event of an error during job execution.

To Page Top

Arguments

job-step-name

~<environment variable name>((1 to 31 bytes))

Specifies a name for the job step, which will serve as one way of identifying the job step. The specified job step name will be displayed in messages, such as in the job execution log, and will also be used as part of file names created by JP1/Advanced Shell.

Job step names can be duplicated within a job.

-successRC return-code-definition[,return-code-definition]...

Specifies definitions for the return codes from commands that execute in the job step normal block that will be considered to signify normal termination of the command. If you specify multiple return code definitions delimited by the comma (,), normal termination will be assumed if any of the definitions is satisfied.

If a command to be executed in the step normal block receives a signal and terminates, its termination will still be regarded as an error termination, regardless of this specification. A command executed within a step normal block might have returned a return code that does not match the return code of the command defined with the successRC attribute. Nevertheless, if the command matches the command name specified by the #-adsh_rc_ignore command, the specification by the #-adsh_rc_ignore command takes precedence regardless of the value specified for the successRC attribute.

return-code-definition

~<unsigned integer>((0 to 255))

You can specify a maximum of eight return code definitions.

• return-code

  Terminate normally when the return code that is returned matches the specified return code.

• return-code-1:return-code-2

  Terminate normally when the return code that is returned is in the range of the specified return codes, inclusive.

• return-code:

  Terminate normally when the return code that is returned is equal to or greater than the specified return code.

• :return-code

  Terminate normally when the return code that is returned is less than the specified return code.

-stepVar shell-variable-name[,shell-variable-name ...]

Specifies shell variables that are to be valid only within the job step. You can specify a maximum of 32 shell variable names delimited by the comma (,).

• shell-variable-name

  ~<environment variable name>((1 to 255 bytes))

  Specifies the name of a shell variable that is to be valid only within the job step. Names of function information arrays cannot be specified.

-run{normal|abnormal|always}

Specifies whether execution of the job step is to depend on the status of preceding job steps and commands in the job definition script. If this specification is omitted, normal is assumed.

• normal

  Execute the job step only if no earlier job step terminated with an error and no command in the previous portion of the job definition script terminated with an error.

• abnormal

  Execute the job step even if an earlier job step terminated with an error or a command in the previous portion of the job definition script terminated with an error.

• always

  Always execute the job step, regardless of the results of earlier job steps or the preceding portion of the job definition script.

-onError{cont|stop}

Specifies whether branching to the job step error block is to occur when a command in the job step normal block terminates with an error. When stop is specified, processing branches to the job step error block, and the subsequent portion of the job definition script in the job step normal block is not executed. When cont is specified, branching does not occur, and the subsequent portion of the job definition script in the job step normal block is executed. If this specification is omitted, stop is assumed.

• cont

  Execute the subsequent portion of the job definition script in the job step normal block.

• stop

  Execute the portion of the job definition script in the job step error block, without executing the subsequent portion of the job definition script in the job step normal block.

To Page Top

Return codes

For #-adsh_step_start and #-adsh_step_error

Return code	Meaning
0	Normal termination
1	Error termination

For #-adsh_step_end

Return code	Meaning
Return code of the last command that executed in the job step normal block	Job step terminated normally.
	Job step terminated with an error.
Argument to the exit command	Executed the exit command with an argument specified within the job step error block and terminated.
1	#-adsh_step_end itself terminated with an error.

Note:

You cannot use an environment setting parameter to change the return code when a job step that contains the #-adsh_step_end command terminates normally or when a job step terminates with an error.

To Page Top

Notes

• If you specify a job step within the block of a control statement (if, for, while, until, or case), you must specify #-adsh_step_start through #-adsh_step_end within the same block; if you violate this rule, a syntax error will occur before execution.

• Do not define a job step within the block of a for, while, or until statement. If there is an external script expansion in such a block, the external script cannot include a job step. If it does, a pre-execution syntax error will result.

• You can define a job step within the block of an if or case statement. However, you cannot then specify abnormal or always in the run attribute.

• A job step cannot be defined inside another job step.

• If the command that executed last in a block terminates normally with a non-zero return code because of the specification of the #-adsh_rc_ignore command, the return code for the job step might be non-zero even though the job step terminates normally.

  Job definition script

    #-adsh_rc_ignore cmdA
    #-adsh_step_start S1 -onError cont
      cmdA    #rc=4 command
      cmdA    #rc=4 command
    #-adsh_step_end

  Execution log

    KNAX6117-I Execution of the command /home/hitachi/bin/cmdA (line=3) finished. exit status=4 execution time=0.001s CPU time=0.000s
    KNAX6117-I Execution of the command /home/hitachi/bin/cmdA (line=4) finished. exit status=4 execution time=0.001s CPU time=0.000s
    KNAX6597-I ADSH152257.S1 step succeeded. exit status=4 execution time=0.005s CPU time=0.000s

• When a batch job is interrupted and the KNAX6584-I message is output, the successRC attribute will not have been applied to the command that executed last.

• When you define a function in a job step normal block or job step error block, you can use the defined function even if the job step is skipped using the run attribute.

To Page Top

Usage examples

• An error results if #-adsh_step_start is specified within the block of an if control statement and the corresponding #-adsh_step_end is specified outside the block.

  if  [ [ $a = $b ]]; then
    #-adsh_step_start S1
  fi
    #-adsh_step_end

• An error results if you define a job step in the block of a while control statement.

  while  [ [ $a = $b ]] do
    #-adsh_step_start S1
    #-adsh_step_end
  done

• Define a job step in the block of an if control statement.

  if  [ [ $a = $b ]]; then
    #-adsh_step_start S1
    #-adsh_step_end
  fi

To Page Top