5.5.4 Shell variable in which to set the return code of an external command [Windows only]

(1) ADSH_RC_EXTERNAL shell variable

We recommend that you use a number from 0 to 255 for the return code of an external command run by the job controller of JP1/Advanced Shell. However, in a case where a batch file or program ends with a return code outside the range from 0 to 255, judge the execution result from the return code by using the ADSH_RC_EXTERNAL shell variable. The following table describes the ADSH_RC_EXTERNAL shell variable, and shows the range of values that can be set in the shell variable.

To Page Top

(2) Examples

The following shows examples of using the ADSH_RC_EXTERNAL shell variable.

In the following example, the shell variable stores a value returned by an external command that is outside the range from 0 to 255.

"D:\\bin\\uap01.exe"    ... User program that ends with a return code of 800
echo $?                 ... 32 is output to the standard output.#
echo $ADSH_RC_EXTERNAL  ... 800 is output to the standard output.

#: 800 = 0x320 The ? shell variable handles the low-order eight bits of the value returned by an external command as the return code.

In the following example, if an external command returns 512, the job ends with a return code of 2.

"D:\\bin\\uap02.exe"
if [ $ADSH_RC_EXTERNAL -eq 512 ]
then
  exit 2
fi

To Page Top

(3) Notes

• You cannot change the value and attribute of the ADSH_RC_EXTERNAL shell variable, and you cannot disable the shell variable.

• You cannot specify the ADSH_RC_EXTERNAL shell variable for the stepVar attribute of the #-adsh_step_start extended script command. If you do so, the command abnormally terminates with a KNAX6312-E message.

• The job controller updates the value of the ADSH_RC_EXTERNAL shell variable not only when running a job definition script, but also when running a command in an .env file, an initialization script, or an external script.

• The job controller initializes the ADSH_RC_EXTERNAL shell variable to 0 immediately before running the job definition script. Therefore, even if you define the ADSH_RC_EXTERNAL shell variable as an environment variable in the parent process, the job controller cannot receive the value of the ADSH_RC_EXTERNAL environment variable. The job controller cannot receive the value, either, even by defining ADSH_RC_EXTERNAL with the export parameter in the environment file.

• The ADSH_RC_EXTERNAL shell variable does not affect the result of judging whether an external command terminated normally or abnormally.

• In the job controller, whether the execution process of a command run via a pipe or command replacement is the current process or another process differs depending on the specification of the following environment setting parameters. Therefore, the time when the value of the ADSH_RC_EXTERNAL shell variable is updated might differ depending on the specification of the environment setting parameters even in the same job definition script.

  • PIPE_CMD_LAST parameter

  • CMDSUB_PROCESS parameter

• If a command is run by another process, the low-order eight bits of the value returned by the command might be set for the ADSH_RC_EXTERNAL shell variable. Do not use the ADSH_RC_EXTERNAL shell variable to obtain the result of a command run by another process.

To Page Top