3.2.3 Running job definition scripts as child jobs

This subsection explains how to run job definition scripts as child jobs and the operation of child jobs. For details about priority, see 5.1.11(3) Priority of command execution methods and 5.1.11(4) Priority of child jobs or external commands that have the same name as the function.

Organization of this subsection

(1) How to execute child jobs
(2) Functional comparison with root jobs and external scripts
(3) Behavior of child jobs when signals are received
(4) Notes about child jobs that are executed from another child job

(1) How to execute child jobs

(a) Executing child jobs by specifying parameters in environment files

In job definition scripts that are run as descendant processes of root jobs, the jobs that are executed by using one of the parameters listed below or its default definition are called child jobs:

CHILDJOB_EXT parameter
CHILDJOB_PGM parameter
CHILDJOB_SHEBANG parameter

The following figure shows an example operation for starting a child job by specifying the CHILDJOB_SHEBANG parameter.

Figure 3‒3: Example operation for starting a child job

This example specifies job definition script childjob.ash in the root job's job definition script. Because childjob.ash satisfies the CHILDJOB_SHEBANG parameter definition, JP1/Advanced Shell starts JP1/Advanced Shell's job as a child process and executes childjob.ash as a child job.

If the root job that starts the child job is executed on a logical host, the child job is also executed on the logical host.

(b) Executing child jobs by using a default definition for the parameter

By using a default definition for the CHILDJOB_SHEBANG parameter, you can start child jobs without having to specify the parameter in environment files.

The following two values have been defined as defaults for the CHILDJOB_SHEBANG parameter:

Default definition	Output mode when the child job is started
`/opt/jp1as/bin/adshexec`	Operation is performed according to the specified `OUTPUT_MODE_CHILD` parameter.
`/opt/jp1as/bin/adshexec` `-mMINIMUM`	Operation is performed in the minimum output mode.

If you specify a job definition script whose first line is #! /opt/jp1as/bin/adshexec in another job definition script, the former can be run as a child job. If you want to execute only a specific child job in the minimum output mode, specify #! /opt/jp1as/bin/adshexec -mMINIMUM on the first line of that job definition script.

The operation of a child job executed by a default definition is the same as for a child job started by the method described in (a) Executing child jobs by specifying parameters in environment files.

Note that the CHILDJOB_SHEBANG parameter specified in the environment file takes precedence over the CHILDJOB_SHEBANG parameter's default definitions. If a value that is the same as a default definition is specified in the CHILDJOB_SHEBANG parameter in the environment file, the following takes effect:

Contents of the environment variable

#-adsh_conf CHILDJOB_SHEBANG "/opt/jp1as/bin/adshexec -mMINIMUM"

Job definition script that is started by the child job

#! /opt/jp1as/bin/adshexec -mMINIMUM
                 :

In this example, /opt/jp1as/bin/adshexec -mMINIMUM specified in the job definition script satisfies the definition of the CHILDJOB_SHEBANG parameter in the environment file. Therefore, the output mode for the child job depends on the specified OUTPUT_MODE_CHILD parameter.

To Page Top

(2) Functional comparison with root jobs and external scripts

The following table compares the functions of root jobs, child jobs, and external scripts:

Function	Type of job		External script
Function	Root job	Child job	External script of . (dot) command	External script of #-adsh_script
Relationship of processes with the calling job	Runs in the child process of the calling job.	Runs in the child process of the calling job.	Runs in the same process as the calling job.	Runs in the same process as the calling job.
Job controller to be started	In UNIX `adshexec` command In Windows `adshexec.exe` command + `adshexecsub.exe` command	In UNIX `adshexec` command In Windows a`dshexecsub.exe` command	None	None
Spool job directory	Created	Created in the root job's spool job directory and deleted when the job terminates. The user selects one of the following about the job execution log: Output only `JOBLOG` to `stderr`. Merge into the root job's job execution log.	Not created. (outputs command execution results to the calling job's `JOBLOG` and does not output script images).	Not created. (outputs command execution results to the calling job's `JOBLOG` and outputs script images to the calling job's `SCRIPT`).
Job start and termination messages	Provided (`KNAX0091-I` and `KNAX0098-I`)	Provided (`KNAX6571-I` and `KNAX6578-I`)	None	None
Loading of environment files	Loaded	Loaded	Not loaded. (depends on the calling job's processing).	Not loaded. (depends on the calling job's processing).
Whether standard input can be used	Can be used.	Can be used.	Can be used.	Can be used.
Destination of standard output	Depends on the specification of the `-s` option, the `-m` option, the `OUTPUT_STDOUT` parameter, and the `OUTPUT_MODE_ROOT` parameter.	Output destination inherited from its parent process.	Depends on the calling job's processing.	Depends on the calling job's processing.

To Page Top

(3) Behavior of child jobs when signals are received

This subsection explains the behavior of descendant jobs when signals are received.

The following example jobs are used to explain the behavior of descendant jobs when termination request signals are sent to the root job, descendant jobs, and an external command:

adshexec(1)-adshexec(2)-adshexec(3)-sleep

The following table describes the behaviors when forced termination is performed from JP1/AJS (by sending SIGTERM from JP1/AJS to adshexec(1)) and SIGTERM is sent from the login shell to adshexec(1), adshexec(2), adshexec(3), and sleep.

Timing	adshexec(1)	adshexec(2)	adshexec(3)	sleep
Forced termination from JP1/AJS	Terminates with error `rc=143`.	Terminates with error `rc=143` due to signal.	Terminates with error `rc=143` due to signal.	Terminates with error `rc=143` due to signal.
Sending `SIGTERM` from the login shell to `adshexec(1)`	Terminates with error `rc=143` due to signal.	Terminates with error `rc=143` due to signal.	Terminates with error `rc=143` due to signal.	Terminates with error `rc=143` due to signal.
Sending `SIGTERM` from the login shell to `adshexec(2)`	If a job step is specified The job step terminates with error `rc=143` and executes a step error block and the step following `run` `abnormal/always`. If a job step is not specified Performs the next processing.	Terminates with error `rc=143` due to signal.	Terminates with error `rc=143` due to signal.	Terminates with error `rc=143` due to signal.
Sending `SIGTERM` from the login shell to `adshexec(3)`	Depends on the result of `adshexec(2)`	If a job step is specified The job step terminates with error `rc=143` and executes a step error block and the step following `run` `abnormal/always`. If a job step is not specified Performs the next processing.	Terminates with error `rc=143` due to signal.	Terminates with error `rc=143` due to signal.
Sending `SIGTERM` from the login shell to `sleep`	Depends on the result of `adshexec(2)`	Depends on the result of `adshexec(3)`	If a job step is specified The job step terminates with error `rc=143` and executes a step error block and the step following `run` `abnormal/always`. If a job step is not specified Performs the next processing.	Terminates with error `rc=143` due to signal.

To Page Top

(4) Notes about child jobs that are executed from another child job

If a descendant job that was executed from another descendant job is terminated abruptly through the intermediate job by a means such as SIGKILL in UNIX or TerminateProcess in Windows, the root job might terminate without waiting for all its descendant jobs to finish. To prevent such an outcome, do not execute an abrupt termination of this type. However, should such occur, check the execution results of the relevant root job and its descendant jobs.

For the descendant jobs other than the abruptly terminated job, the spool job directory might have been deleted or it might remain after a failed attempt to delete it. Even if it has been deleted, the logs will still be preserved, because the contents of JOBLOG will have been output to the standard error output.

Example:

This example illustrates the case where a descendant job is executed from another descendant job (the chain of one job calling the next is indicated by [Figure] ):

[root job]  [descendant job (child)]  [descendant job (grandchild)]

In this case, if [descendant job (child)] terminates abruptly, [root job] might terminate earlier than [descendant job (grandchild)]. In such a case, the behavior of each job and the status of the spool job directory are as follows:

Item	Type of job
Behavior of the job	The job behaves as though the descendant job (child) had terminated with an error. The behavior is the same as when a user program terminates abruptly due to an error.	The job is terminated abruptly.	The job terminates normally. However, in Windows, it might behave as if it was forcibly terminated, depending on the status of other, related jobs.
Status of the spool job directory	In Windows, if the descendant job (grandchild) has already opened the job execution log, the renaming of the spool job directory will fail. Otherwise, or in the case of UNIX, the spool job directory will be renamed as per normal.	Directory remains without being deleted.	If the root job has successfully renamed its spool job directory, the renaming of this spool job directory will fail. Otherwise, the contents of `JOBLOG` will be output to `stderr` and will be deleted as per normal.

Item

Type of job

Root job

Descendant job (child)

Descendant job (grandchild)

Behavior of the job

The job behaves as though the descendant job (child) had terminated with an error.

The behavior is the same as when a user program terminates abruptly due to an error.

The job is terminated abruptly.

The job terminates normally.

However, in Windows, it might behave as if it was forcibly terminated, depending on the status of other, related jobs.

Status of the spool job directory

In Windows, if the descendant job (grandchild) has already opened the job execution log, the renaming of the spool job directory will fail.

Otherwise, or in the case of UNIX, the spool job directory will be renamed as per normal.

Directory remains without being deleted.

If the root job has successfully renamed its spool job directory, the renaming of this spool job directory will fail.

Otherwise, the contents of JOBLOG will be output to stderr and will be deleted as per normal.

To Page Top