CMDRC_THRESHOLD_DEFINE parameter (defines a return code threshold for a command)

Organization of this page

Format
Description
Operands
Notes
Example

Format

#-adsh_conf CMDRC_THRESHOLD_DEFINE command-name threshold

To Page Top

Description

This parameter defines a threshold value for the return code for a command executed from a job definition script. Normal termination will be considered to have occurred whenever the command's return code is equal to or smaller than the specified threshold value. You use this parameter when you want normal termination to be considered to have occurred even though the actual return code of the command was not 0.

If the command terminates by receiving a signal, an error termination will be considered to have occurred regardless of the specification of this parameter.

The CMDRC_THRESHOLD_DEFINE parameter can also be used to change the threshold for a UNIX-compatible command for which a threshold has been defined by specification of ENABLE in the CMDRC_THRESHOLD_USE_PRESET parameter.

To Page Top

Operands

command-name ~<command name>((1 to 255 bytes))

Specifies the name of the command for which the threshold of the return code is to be defined. In Windows, a command name with an extension can also be specified. A command path cannot be specified.

The command types that can be specified are listed below. Other commands are also affected by this parameter if they are executed in a separate process (using a pipe, command substitution, |& or &).

External command
UNIX-compatible command
Shell operation command
Shell script
Child job

If specification of a command extension is omitted in Windows, commands and batch files having the same name as the specified name become the targets for threshold control regardless of their extension.

To specify a command name containing a space in Windows, enclose the entire command name in double quotation marks (").

threshold ~<integer>((-1 to 255))

Specifies the threshold to be used for determining that the return code represents a normal termination. If the return code is greater than the value specified here, it will be assumed that an error termination has occurred.

If -1 is specified, execution of the command will always result in an error termination.

If 255 is specified, the execution result will always be regarded as a normal termination.

To Page Top

Notes

This parameter applies to the specified command following variable substitution or alias resolution.
The setting for the successRC attribute of the #-adsh_rc_ignore and #-adsh_step_start commands of the job definition script takes precedence for the command action based on the command threshold specified by this parameter and the return code of the executed command.
If this parameter is defined in both the system environment file and the job environment file, both definitions take effect. However, if different thresholds are defined for the same command, the last one defined in the job environment file takes effect.
Although there is no limit to the number of times this parameter can be specified, do not define it for unnecessary commands because specifying it too many times will affect adversely the execution performance of job definition scripts.
To define a return code threshold for a job definition script to be executed as a child job, use the CHILDJOB_EXT or CHILDJOB_SHEBANG parameter for the child job definition.

If you use the CHILDJOB_PGM parameter to define a child job, the specified return code threshold will not be applied to the child job.
In Windows, you can specify the command name with or without an extension.

However, if you specify a command name with an extension and the same command name without an extension, they will be not considered to be the same command.
- If you use this parameter to specify a threshold for a command name with an extension and another threshold for the same command name without an extension, the first one specified takes effect.
- The command names that are assumed when ENABLE is specified in the CMDRC_THRESHOLD_USE_PRESET parameter are the names with an extension. Therefore, to use this parameter to change a threshold, you must specify an extension. If the extension is omitted, the command will be registered as a different command.
Regardless of their specification order, the CMDRC_THRESHOLD_USE_PRESET parameter is always processed first when both it and the CMDRC_THRESHOLD_DEFINE parameter are specified.

To Page Top

Example

In this example, 10 is defined as the return code threshold for the CHILD_EXEC1.sh child job (normal termination whenever the return code is 10 or smaller):
```
#-adsh_conf  CHILDJOB_EXT sh
#-adsh_conf  CMDRC_THRESHOLD_DEFINE CHILD_EXEC1.sh 10
```
In this example, 1 is generally defined as the return code threshold for UNIX-compatible commands; for certain other UNIX-compatible commands (acmd, bcmd, ccmd), 20 is defined as the threshold:
```
#-adsh_conf CMDRC_THRESHOLD_USE_PRESET ENABLE
#-adsh_conf CMDRC_THRESHOLD_DEFINE acmd 20
#-adsh_conf CMDRC_THRESHOLD_DEFINE bcmd 20
#-adsh_conf CMDRC_THRESHOLD_DEFINE ccmd 20
```
(Windows only) In this example, 10 is defined as the return code threshold for the acmd.exe command, and 20 is defined as the threshold for the generic command name acmd:
```
#-adsh_conf  CMDRC_THRESHOLD_DEFINE acmd.exe 10
#-adsh_conf  CMDRC_THRESHOLD_DEFINE acmd 20
```
In this definition sequence, 10 is applied as the threshold for the acmd.exe command, and 20 is applied as the threshold for acmd commands whose extension is not .exe (such as acmd.bat).
(Windows only) In this example, 20 is defined as the threshold for the generic command name acmd, and 10 is defined as the return code threshold for the acmd.exe command.

20 is applied as the return code threshold for commands whose name is acmd (such as acmd.exe and acmd.bat):
```
#-adsh_conf  CMDRC_THRESHOLD_DEFINE acmd 20
#-adsh_conf  CMDRC_THRESHOLD_DEFINE acmd.exe 10
```
In this definition sequence, the definition for the acmd generic command name, which is described first, is also preferentially applied to the acmd.exe command. Therefore, the threshold for the acmd.exe command also becomes 20.
In this example, the acmd.exe command is specified twice in the same parameter, with 30 and 20 defined as the thresholds:
```
#-adsh_conf  CMDRC_THRESHOLD_DEFINE acmd.exe 30
#-adsh_conf  CMDRC_THRESHOLD_DEFINE acmd.exe 20
```
In this case, the threshold for the last parameter specified, which is 20, is applied.
In this example, the acmd.exe command is specified with a threshold of 10 in the system environment file and with a threshold of 20 in the job environment file:

System environment file specification:
```
#-adsh_conf CMDRC_THRESHOLD_DEFINE acmd.exe 10
```
Job environment file specification:
```
#-adsh_conf CMDRC_THRESHOLD_DEFINE acmd.exe 20
```
In this case, the threshold of 20 specified in the job environment file is applied.
(Windows only) In this example, 1 is generally defined as the return code threshold for UNIX-compatible commands and then the threshold for the cmp.exe command only is changed to 2:
```
#-adsh_conf CMDRC_THRESHOLD_USE_PRESET ENABLE
#-adsh_conf CMDRC_THRESHOLD_DEFINE cmp.exe 2
```
(Windows only) In this example, cmp 2 is specified by the CMDRC_THRESHOLD_DEFINE parameter for the cmp.exe command for which a threshold of 1 is defined by the CMDRC_THRESHOLD_USE_PRESET parameter. In this case, however, the threshold cannot be changed from 1 to 2:
```
#-adsh_conf CMDRC_THRESHOLD_USE_PRESET ENABLE
#-adsh_conf CMDRC_THRESHOLD_DEFINE cmp 2
```
In this case, cmp.exe and cmp are managed as separate commands for which different thresholds are effective.
If the CMDRC_THRESHOLD_USE_PRESET and CMDRC_THRESHOLD_DEFINE parameters are specified in different environment files, as shown below, the threshold of 2 specified by the CMDRC_THRESHOLD_DEFINE parameter is applied to the cmp.exe command.

System environment file specification:
```
#-adsh_conf CMDRC_THRESHOLD_DEFINE cmp.exe 2
```
Job environment file specification:
```
#-adsh_conf CMDRC_THRESHOLD_USE_PRESET ENABLE
```

To Page Top