9.3.27 trap command (specifies the action when signals and forced termination requests are received)

Syntax

trap  [action]  [signal...] 

Description

This command sets the action to be taken when signals are received. If the shell receives a specified signal for signal, the behavior specified for action is executed.

If the command is executed without specifying an argument, the behavior that is set for signal is output to the standard output in the following format:

Signal type	Output format
For signals with a defined name:	trap -- action "Signal name without the leading SIG"
For signals without a defined name:	trap -- action UNKNOWN SIGNAL

Actions for signals in which multiple names are defined for a single signal number are as follows:

[Only for Linux]

Signal name	Alternate name	Setting of the action by the trap command
SIGSYS	SIGUNUSED	SIGSYS	Can be set.
		SIGUNUSED	Can be set.

Note:

Because extended functions use SIGSYS instead of SIGUNUSED as the main signal name, the trap command also treats SIGSYS as the signal name.

[Only for AIX]

Signal name	Alternate name 1	Alternate name 2	Setting of the action by the trap command
SIGABRT	SIGLOST	SIGIOT	SIGABRT	Can be set.
			SIGLOST	Can be set.
			SIGIOT	Can be set.
SIGIO	SIGPOLL	None	SIGIO	Can be set.
			SIGPOLL	Can be set.

[Only for HP-UX and Solaris]

Signal name	Alternate name	Setting of the action by the trap command
SIGABRT	SIGIOT	SIGABRT	Can be set.
		SIGIOT	Can be set.
SIGIO	SIGPOLL	SIGIO	Can be set.
		SIGPOLL	Can be set.

When an action is specified with the trap command for a signal for which multiple names are defined under a single signal number, one of the specified signal names is output.

Arguments

action

This command specifies the action to be taken when the specified signals are received.

If a hyphen (-) is specified for action, the previously-specified traps for the specified signal are reverted to their default settings. If action is not specified and a signal number is specified for signal, the previously specified traps for the specified signals are also reverted to their default settings.

If "" is specified for action, the signal specified for signal is ignored (SIG_IGN).

However, for SIGTERM, the signal is not ignored (SIG_IGN) even when "" is specified for the action.

If "" is specified, the trap command finishes normally without changing the currently configured action.

signal

This command specifies the signal that is to be trapped.

You can specify a signal number or a signal name for signal. When you specify a signal name, this must be specified without the SIG at the beginning (for example, specify INT for SIGINT). For specifications of each signal, see the documentation of the OS being used.

The operation that is performed when SIGTERM is specified depends on the specification of the TRAP_ACTION_SIGTERM environment setting parameter. See 7. Parameters Specified in the Environment Files > TRAP_ACTION_SIGTERM parameter (defines the job controller's action when a request for a forced termination is received).

For signal, you can specify multiple signals delimited by a space. You can also specify 0, "EXIT", or "ERR" for signal.

When specifying 0 or "EXIT" for signal and executing the trap command:

You can execute the command specified for action when a shell ends.

When specifying "ERR" for signal and executing the trap command:

When the following command that is executed after the trap command finishes with a return code other than 0, the action specified for action is executed.

- Regular built-in command

- typeset command

- return command that results in an error in a function or external script because of an invalid format

In AIX, you cannot specify SIGWAITING for signal. If you execute this command in AIX with SIGWAITING specified, the command ends in an error.

Return codes

Return code	Meaning
0	Normal termination
1	Termination with an error

Notes

• If you specify a value that is smaller than 0 for the signal argument, the trap command treats this as an invalid signal. If you specify a numeric value for the signal argument, specify a value that is within 0 to the permissible range of the signal.

• If the adshread extended shell command is specified in the operation defined by the trap command, the job waits for an entry even when a forced termination request is received and the job will not be terminated. If you specify TERM for the operand in the TRAP_ACTION_SIGTERM parameter, or if you specify AUTO in the TRAP_ACTION_SIGTERM parameter and start a job from JP1/AJS, do not specify the adshread extended shell command in the operation that is defined by the trap command.

• If the shell operation command adshjava is specified for the operation that is defined by the trap command and the command is forcibly terminated, you can execute Java batch applications in the trap action. However, if a forced termination is executed while executing the trap action, the asshjava command will not be forced to terminate. If you specify TERM for the operand in the TRAP_ACTION_SIGTERM parameter, or if you specify AUTO in the TRAP_ACTION_SIGTERM parameter and start a job from JP1/AJS, do not use the adshjava command in the trap action. If you run Java batch applications as post-processing that is unique to a user, use the cjexecjob command and cjkilljob command.

• If the command syntax of this special built-in command is invalid, the shell that is executing the command will be terminated.

• If the argument action is omitted and only a signal number is specified for the signal argument, the trap command resets the action specified for signal to the default setting. If only a signal name without SIG is specified, the trap command terminates itself without resetting the action specified for the signal argument.

  Example: trap 15

  --> The command resets the action for signal number 15 to the default setting.

  Example: trap TERM

  -->The command does not reset the action.

Examples

• The message "trapped." is output by the echo command when the INT signal is received.

  trap 'echo trapped.' INT

• Displays the action that is set for the signal.

  Contents of the job definition script

  trap 'echo Hangup.' HUP
  trap 'echo trapped.' INT
  trap

  Contents of the STDOUT file of the execution job

  ********   Contents of the STDOUT file of the executable job    ********
  trap -- 'echo Hangup.' HUP
  trap -- 'echo trapped.' INT

Syntax

trap [action][method]

Description

This command sets the action to be taken when a forced termination request is received.

When specifying TERM with the TRAP_ACTION_SIGTERM parameter:

You can set the action to take when the job controller receives a forced termination request. If the job controller receives a forced termination request specified for method, the job controller executes the action specified for action.

If a forced termination request with neither TERM nor 15 is specified for method, the specified action is not set and the job controller outputs the message KNAX6718-I and terminates after returning the return code 0.

When the command is executed without specifying an argument, the action that is set for the forced termination request is output to the standard output in the following format:

Output format

trap -- action "character-string-that-indicates-the-method-of-forced-termination"

When specifying DISABLE in the TRAP_ACTION_SIGTERM parameter:

The command issues the KNAX6710-I message and always terminates normally with the return code of 0. The command does not perform processing for forced termination requests.

Arguments

action

This command specifies the action to be taken when a forced termination request is received.

If a hyphen (-) is specified for action, the command resets the previously specified action that matches method, disables the behavior definition for method(action), and no settings become available. If action is omitted and 15 is specified for method, the command also resets the behavior definition for method (action) and no settings become available.

If "" is specified for action, the trap command finishes normally without changing the current setting for action.

method

Specifies the forced termination method that is to be trapped.

Specify TERM or 15 for method.

TERM or 15

Specifies that immediate process termination is to be performed by a function such as TerminateProcess (such as forced termination from JP1/AJS or the taskkill command).

Return codes

Return code	Meaning
0	Normal termination
1	Termination with an error

Notes

• When kill -KILL process-ID is executed to terminate adshexec.exe for a job, the action defined in the terminated job's "trap action TERM" is executed.

• If TERM is specified in the TRAP_ACTION_SIGTERM parameter, the trap command with an option specified results in an error. If a value other than TERM is specified in the TRAP_ACTION_SIGTERM parameter, the trap command with an option specified will not result in an error.

• If the adshread extended shell command is specified in the operation defined by the trap command and a forced termination request is received, the job will wait for an entry and will not be terminated. Do not specify the adshread command for the operation definition of the trap command if TERM has been specified for the operand in the TRAP_ACTION_SIGTERM parameter.

• If the shell operation command adshjava is specified for the operation that is defined by the trap command and the command is forcibly terminated, you can execute Java batch applications in the trap action. However, if a forced termination is executed while executing the trap action, the adshjava command will not be forced to terminate. For this reason, when specifying TERM for the operand in the TRAP_ACTION_SIGTERM parameter or when specifying AUTO in the TRAP_ACTION_SIGTERM parameter and starting a job from JP1/AJS, do not use the adshjava command in the trap action. If you operate Java batch applications as post-processing that is unique to a user, use the cjexecjob command and cjkilljob command.

• If the command syntax of this special built-in command is terminated with an error due to an incorrect syntax, the shell that is executing the command will end.

• If the argument action is omitted and 15 is specified for the argument method, the trap command resets the action specified for immediate process termination by using a function such as TerminateProcess so that the method is not associated with any action settings. However, if only TERM is specified, the trap command terminates itself without resetting the action specified for immediate process termination.

  Example: trap 15

  The command resets the action specified for immediate process termination by using a function such as TerminateProcess so that the method is not associated with any action settings.

  Example: trap TERM

  -->The command does not reset the action.

• If two or more values are specified for method and at least one of these values is TERM or 15, the command sets action for TERM or 15 without issuing the KNAX6718-I message. For any other method, action is not set.

  Example: If you execute "trap date 28 15", the trap command sets the date command as the action for 15 without issuing the KNAX6718-I message.

• The process that is being executed in the background when the forced termination request is received is terminated before executing the action defined with "trap action TERM".

Examples

• This example outputs the message "trapped." with the echo command when a forced termination request is received.

  trap 'echo trapped.' TERM

• This example displays the action that is set for forced termination requests. The example outputs TERM for the method of forced termination even if 15 is specified for method with the trap command in which action is set.

  Contents of the job definition script

  trap 'echo trapped.' 15
  trap

  Contents of the STDOUT file of the execution job

  ********   JOB SCOPE STDOUT    ********
  trap -- 'echo trapped.' TERM