2.6.8 Defining job execution results and log output information

(a) Determining whether the spool job creation suppression functionality is to be used

The spool job creation suppression functionality enables you to prevent the spool directory's disk space usage from increasing continually. It also eliminates the need to delete unneeded directories and files from the spool directory.

Use the SPOOLJOB_CREATE parameter to enable the spool job creation suppression functionality. For details, see SPOOLJOB_CREATE parameter.

JP1/Advanced Shell always runs with the following settings while the spool job creation suppression functionality is in effect:

• #-adsh_conf EVENT_COLLECT NO

  Disables the operation information acquisition functionality.

• #-adsh_conf OUTPUT_MODE_CHILD MINIMUM

  Executes child jobs in the minimum output mode.

• #-adsh_conf OUTPUT_MODE_ROOT MINIMUM

  Executes root jobs in the minimum output mode.

• #-adsh_conf SPOOLJOB_CHILDJOB DELETE

  Deletes the spool jobs for child jobs when the child jobs are terminated.

• adshexec -m MINIMUM

  Executes the specified job in the minimum output mode regardless of the specified -m option.

• adshscripttool -exec -m MINIMUM

  Executes the specified child job in the minimum output mode regardless of the specified -m option.

Note that when the spool job creation suppression functionality is used, none of the following functions that use spool job directories can be used:

• #-adsh_spoolfile command

  If this command is used, the KNAX6385-E message is issued and the script is terminated.

• adshfile command

  If this command is used, the KNAX1880-E message is issued and the command is terminated.

• Collection of job execution logs

  Job execution logs are not collected.

• Operation results collection functionality

  Operation results are not collected.

Even when the spool job creation suppression functionality is in effect, spool directories are still needed.

When the spool job creation suppression functionality is in effect, the following environment setting parameters are ignored:

• EVENT_COLLECT

• JOBEXECLOG_PRINT

• JOBLOG_SUPPRESS_MSG

• OUTPUT_MODE_CHILD

• OUTPUT_MODE_ROOT

• OUTPUT_STDOUT

• PERMISSION_SPOOLJOB_DIR

• PERMISSION_SPOOLJOB_FILE

• SPOOLJOB_CHILDJOB

During CUI debugging, a DBG file with the name shown below is created. This file is deleted automatically when debugging is finished. If deletion of this file fails, an error message is output to the standard error output and to the system execution log.

temporary-file-directory/ADSH_DBG_process-ID_job-ID

• temporary-file-directory

  Temporary file directory defined in the TEMP_FILE_DIR parameter

• process-ID

  Process ID consisting of five or more digits

• job-ID

  Job ID consisting of six digits

(b) Defining the path name of the spool root directory

The following parameter is used for defining the path name of the spool root directory:

• SPOOL_DIR parameter: Defines the path name of the spool root directory.

If you will be using the user-reply functionality, define the SPOOL_DIR parameter only in the system environment file.

(c) Changing the spool job directory or file permissions (UNIX only)

When a job is terminated, its execution results are output to the spool job directory created for that job. You can use the following parameters to change the permissions for the directory or the files under that directory:

• PERMISSION_SPOOLJOB_DIR parameter

  Specify this parameter to change permissions for the spool job directory.

  The default is 700.

• PERMISSION_SPOOLJOB_FILE parameter

  Specify this parameter to change permissions for the files under the spool job directory.

  The default is 600 (in .DBG files, 666).

(d) Defining the standard output and standard error for spool jobs

When a job is executed, JP1/Advanced Shell's information messages, warning messages, and job execution logs are output in addition to the job execution results. The standard output and the standard error output are output to files under the spool job directory.

You specify the simple output mode or the minimum output mode to suppress output of the standard output and the standard error output to files under the spool job directory. You use the following parameters and command options for this specification:

• OUTPUT_MODE_ROOT parameter

  Specifies the expansion output mode, simple output mode, or minimum output mode for root jobs.

• OUTPUT_MODE_CHILD parameter

  Specifies the expansion output mode, simple output mode, or minimum output mode for child jobs.

• -m option of the adshexec command

  Specifies the expansion output mode, simple output mode, or minimum output mode for jobs.

• -m option of the adshscripttool command

  Specifies the simple output mode or minimum output mode for child jobs.

If these parameters and option are omitted, expansion output mode is assumed, in which case the standard output and the standard error are output to files under the spool job directory.

In the simple and minimum output modes, JP1/Advanced Shell's information and warning messages are not output to the standard output or the standard error output. Also, when jobs are terminated, job execution logs are not output to the standard error output. In addition, in the minimum output mode, messages whose output is suppressed are not output to the job execution logs under spool job directories.

For details about the difference in output information among the simple output mode, expansion output mode, and minimum output mode, see 3.3.4 Suppressing output of information and warning messages to job execution logs.

(a) Defining the types of job execution logs to be output to the standard error

When a job is terminated, the information listed below is output as job execution logs to the standard error. The output job execution logs are displayed on the terminal screen used when the adshexec command is executed, and in JP1/AJS - View's Execution Results Details dialog box.

• JOBLOG file (Messages indicating the job's execution status, including command execution results and file allocation results)

• Job definition script

• Contents of the standard error during job execution

To output only the contents of the standard error during job execution to the standard error, specify the parameter shown in the following to limit the contents of job execution logs to be output:

• JOBEXECLOG_PRINT parameter

If a job is executed in JP1/Advanced Shell - Developer or the job controller is started in the debugger mode, JOBLOG, standard output, and standard error are output to the console regardless of the specification of this parameter. When the job is terminated, the contents of the job execution log are not output to the standard error.

When a job is executed in the simple output mode or the minimum output mode, job execution logs are not output to the standard error output when the job is terminated regardless of the specification of the JOBEXECLOG_PRINT parameter.

(b) Merging the job execution logs for a root job and child jobs

The following parameter enables you to choose whether child jobs' spool jobs are to be deleted when the child jobs are terminated, or to be merged into the root job's spool jobs:

• SPOOLJOB_CHILDJOB parameter

If child jobs' spool jobs are merged into the root jobs spool jobs, the child jobs are output in the order they are terminated in such a format that the root job can be identified from the child jobs.

(a) Flow of output to the system execution log

The system execution log is the destination for log information about the batch jobs running in each job controller process. You can specify in the environment files the output destination for the system execution log, as well as parameters that control log file swapping (such as maximum file size and number of files). The following figure shows the flow of output to the system execution log.

Figure 2‒4: Flow of output to the system execution log

The system execution log is created as follows.

• Messages to be output to the system execution log are collected and output in CSV format.

  For details about the messages that are output, see 11.2 Message output destinations.

• In time, log file swapping is performed and a backup is created.

  • Just before it exceeds the file size specified in the LOG_FILE_SIZE parameter in the environment file, the current system execution log file is renamed so that it becomes a backup file, and a new system execution log is created and message output continues to it.

  • The file name of the backup will be AdshLog_N.log (where N is an integer). N is assigned a number in ascending order from the newest backup, starting from 1.

  • The maximum number of backups to be created is specified in the LOG_FILE_CNT parameter in the environment file. When the number of backup files exceeds this value, the oldest backup file is deleted.

(b) Parameters required to output the system execution log

The following parameters are used for outputting system execution logs:

• LOG_DIR parameter: Defines the path name of the directory to which system execution logs are to be output.

• LOG_FILE_CNT parameter: Defines the number of files used for backing up system execution logs.

• LOG_FILE_SIZE parameter: Defines the file size for output of system execution logs.

If multiple users output system execution logs to the same file, the LOG_FILE_CNT and LOG_FILE_SIZE parameter values specified by the last user who starts output of system execution logs take effect. Therefore, we recommend that you use the same value for LOG_FILE_CNT and LOG_FILE_SIZE.

(c) Contents of the system execution log

The following shows an example of a message output to the system execution log:

seqnum=1, date=2013-12-06T10:41:19.242+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX0004-I, msg="Job ID=000006, JP1NBQSQueueName=, scheduler job ID="
seqnum=2, date=2013-12-06T10:41:19.250+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX0091-I, msg="JOB1 The job started."
seqnum=3, date=2013-12-06T10:41:19.251+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX7901-I, msg="The adshexec command will wait for all asynchronous processes at the end of the job."
seqnum=4, date=2013-12-06T10:41:19.251+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX7902-I, msg="The adshexec command will run in tty stdin mode."
seqnum=5, date=2013-12-06T10:41:19.252+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX0092-I, msg="JOB1.STEP1 step started."
seqnum=6, date=2013-12-06T10:41:19.263+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX6116-I, msg="Execution of the command D:\bin\uap01.exe (line=5) finished successfully. exit status=0 execution time=0.008s CPU time=0.000s"
seqnum=7, date=2013-12-06T10:41:19.274+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX6597-I, msg="JOB1.STEP1 step succeeded. exit status=0 execution time=0.022s CPU time=0.015s"
seqnum=8, date=2013-12-06T10:41:19.274+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX0092-I, msg="JOB1.STEP2 step started."
seqnum=9, date=2013-12-06T10:41:19.289+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX6116-I, msg="Execution of the command D:\bin\uap02.exe (line=10) finished successfully. exit status=0 execution time=0.008s CPU time=0.015s"
seqnum=10, date=2013-12-06T10:41:19.290+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX6597-I, msg="JOB1.STEP2 step succeeded. exit status=0 execution time=0.016s CPU time=0.015s"
seqnum=11, date=2013-12-06T10:41:19.290+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX0092-I, msg="JOB1.STEP2 step started."
seqnum=12, date=2013-12-06T10:41:19.299+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX6116-I, msg="Execution of the command D:\bin\uap03.exe (line=15) finished successfully. exit status=0 execution time=0.008s CPU time=0.000s"
seqnum=13, date=2013-12-06T10:41:19.299+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX6597-I, msg="JOB1.STEP2 step succeeded. exit status=0 execution time=0.009s CPU time=0.000s"
seqnum=14, date=2013-12-06T10:41:19.300+09:00, pgmid=adshexec, jobid=6, pid=2720, msgid=KNAX0098-I, msg="JOB1 The job ended. exit status=0 execution time=0.053s CPU time=0.030s"

The following table lists and explains the data items that are added in front of the message texts in the system execution log:

Data items output to the system execution log	Meaning
seqnum	Message's serial number
date	Output date and time (in the format yyyy-mm-ddThh:mm:ss.sssTZD)
pgmid	Program ID In a job controller, adshexec is output.
jobid	Job ID
pid	Process ID
msgid	Message ID of the output message
msg	Message text of the output message