...

...

• Traps are used in shell jobs for the situation that a job should not be aborted immediately, but should be terminated after having performed some a cleanup operation , for examplesuch as:
  
  • removing
  • to remove temporary files created by the job,
  • to disconnect disconnecting from a database.
• Traps are available for the Unix Shell, not for JVM Jobs and not for Windows Shell Jobs..

• Display feature availability
  StartingFromRelease 2.1.1

...

• Line 6 - 50: a sample shell script $HOME/test-trap.sh is created by the job shell script, that . This is started later on started for background execution with in line 54.
  • Line 11 - 23: the exitOnSigterm() function is defined that . This is called should if the trap be is triggered , - see line 36.
  • Line 25 - 33: the cleanupTermporaryFiles() function is defined that removes a temporary file that has previously been created by the job shell script.
    • This function is called by the exitOnSigterm() function of the trap with in line 19. The intention is to perform some a cleanup in case that a SIGTERM signal triggers the trap.
    • This function is called in line 47. This It is intended for normal termination of the job shell script when no trap is triggered.
  • Line 36: a trap is defined that which is triggered by a SIGTERM signal and that calls the exitOnSigterm() function.
  • Line 39 - 41: the sample shell script starts a sleep command that which is executed in the background and that touches a temporary file that which should be removed by the cleanupTermporaryFiles() function.
  • Line 44: the sample shell script waits for termination of the sleep command.
  • Line 47: the cleanupTermporaryFiles() function is called to remove temporary files in case of normal termination without the trap being triggered.
• Line 53 - 54: the sample shell script is made executable and is started in background.
• Line 59: the job shell scripts waits for termination of the sample shell script.

...

In Unix environments jobs receive the following signals from the Agent:

• When a job should is to be killed then , the Agent sends a SIGTERM signal.
  • This signal can be ignored or can be handled by a job. For shell scripts a trap can be defined to e.g. , for example, perform cleanup tasks such as disconnecting from a database or removing temporary files.
• The job configuration includes the Grace timeout setting:
  • The Grace Timeout duration is applied after a SIGTERM signal (corresponding to kill -15) has been sent by the Agent. This allows the job to terminate on its own, for example after some a cleanup is has been performed.
  • Should If the job is still run running after the specified Grace Timeout duration then the Agent sends a SIGKILL signal (corresponding to kill -9) that aborts the OS process.

Job scripts frequently spawn child processes that have to be killed accordingly to in accord with their parent process.

• By default the OS removes child processes if the parent process is killed. However, this mechanism is not applicable for all situations, depending on the way how the child processes have been spawned.
• To reliably kill child processes the Agent makes use of the kill_task.sh script from its var_<port>/work directory.
  • This script retrieves the process tree of the job shell script and tries to kill any child processes.
• Though the Agent is platform independent it is evident that retrieval of a process tree does not necessarily use the same command (ps) and options for any all Unixes.
  • The Agent therefore allows to specify an individual kill script to be specified from a command line option should if the built-in kill_task.sh script is not be applicable to your Unix platform.

...

It is important to keep in mind that a trap interrupts the currently executed command in a script, but does not terminate the script.

• When the respective relevant OS signal is received then the current command of the job shell script is aborted and instead the trap is executed.
  • This is why you find two trap definitions with in the above example:
    • When cancelling a job then the SIGTERM signal is sent by the Agent to the process running the job shell script.
    • As the job shell script process spawns another shell script to be executed in background, the trap in line 4 of the above example example above is added:
      • the job shell script's trap forwards the SIGTERM signal to the sample shell script.
      • the sample shell script defines its own trap with line 36 that . This then receives the job shell script's signal.
• After execution of the trap the sample shell script is resumed with the next command after line 44. 
  • The assumption is that the SIGTERM signal is received while waiting for the sleep command to be completed with line 44.
  • With the wait command being interrupted the cleanupTermporaryFiles() function is called by the sample shell script with line 47.
• As a result the sample shell script is completed with line 49 and control is returned to the job shell script that . This then continues with the line following the wait command in line 59 that basically exits the job shell script and provides the exit code of the most recently executed command.
  • This exit code is only informational only as the Agent will set the job's exit code to the value 1 to indicate failure of the job independently from of whether the trap being has been completed successfully or not.

Further Resources

• JS7 - FAQ - Does JS7 reliably kill running jobs?