adshevtout command (outputs job definition script operation information)
- Organization of this page
Format
adshevtout [-s job-execution-start-time-lower-bound] [-e job-execution-start-time-upper-bound] [-c JP1/AJS-schedule-service-name] [-r JP1/AJS-root-jobnet-name] [-k JP1/AJS-job-execution-ID] [-n JP1/AJS-job-number] [-g JP1/AJS-job-name] [-u JP1/Advanced-Shell-execution-user-name] [-p job-definition-script-file-path-name] [-i JP1/Advanced-Shell-job-ID] [-j JP1/Advanced-Shell-job-name] [-t] [-d] [-m] [-z] [-h logical-host-name]
Description
This command searches the event file for job definition script operation information for jobs meeting specified conditions, and output the results in CSV format. The output destination is the standard output (stdout).
This command cannot be used in JP1/Advanced Shell - Developer.
Specification of output conditions
You use the following arguments to specify the jobs whose job definition script operation information is to be output:
[-s job-execution-start-time-lower-bound] [-e job-execution-start-time-upper-bound] [-c JP1/AJS-schedule-service-name] [-r JP1/AJS-root-jobnet-name] [-k JP1/AJS-job-execution-ID] [-n JP1/AJS-job-number] [-g JP1/AJS-job-name] [-u JP1/Advanced-Shell-execution-user-name] [-p job-definition-script-file-path-name] [-i JP1/Advanced-Shell-job-ID] [-j JP1/Advanced-Shell-job-name]
If multiple output conditions are specified, the command outputs job definition script operation information only for jobs that satisfy all the specified conditions.
If no output conditions are specified, the command outputs job definition script operation information for all jobs on the physical host or the specified logical host.
If you specify job attributes (such as start date, job ID, and job name) as output conditions for the jobs whose information is to be output, the job attributes are determined by the attribute values of the root job.
The command outputs the job definition script operation information for the root job that satisfies all the output conditions and for all its child jobs. You cannot output job definition script operation information that is limited only to the root job or only to specific child jobs.
What job definition script operation information is output
Normally, job definition script header information is output on the first line, and operation information and messages are output on the second and subsequent lines.
You select the output information by specifying the following arguments to the adshevtout command:
[-t] [-d] [-m] [-z]
For examples of the output of operation information, see 3.6.9 Job definition script operation information that is output.
When the following argument is specified, the command outputs operation information for jobs executed on the specified logical host:
[-h logical-host-name]
When this argument is not specified, the command outputs operation information for jobs executed on the physical host.
Arguments
- -s job-execution-start-time-lower-bound
-
Specifies a lower boundary for the job execution start date and time as a condition for determining the jobs whose job definition script operation information is to be output.
For details about the specification format of the date and time, see Job execution start date and time below.
If this argument is omitted, there is no limitation on the lower boundary for the execution start date of the jobs to be output.
- -e job-execution-start-time-upper-bound
-
Specifies an upper boundary for the job execution start date and time as a condition for determining the jobs whose job definition script operation information is to be output.
For details about the specification format of the date and time, see Job execution start date and time below.
If this argument is omitted, there is no limitation on the upper boundary for the execution start date of the jobs to be output.
- -c JP1/AJS-schedule-service-name
-
Specifies a JP1/AJS schedule service name as a condition for the jobs whose job definition script operation information is to be output.
You can output jobs that match either of the following as character strings:
-
The scheduler service name specified in this argument
-
The name of the JP1/AJS scheduler service that started the job (the value of the AJS_AJSCONF environment variable that was specified when JP1/AJS started the job)
-
- -r JP1/AJS-root-jobnet-name
-
Specifies a JP1/AJS root jobnet name as a condition for the jobs whose job definition script operation information is to be output.
You can output jobs that match either of the following as character strings:
-
The root jobnet name specified in this argument
-
The JP1/AJS root jobnet name at the time the job was started (the value of the AJSNETNAME environment variable that was specified when JP1/AJS started the job)
-
- -k JP1/AJS-job-execution-ID
-
Specifies a JP1/AJS job execution ID as a condition for the jobs whose job definition script operation information is to be output.
You can output jobs that match either of the following as character strings:
-
The job execution ID specified in this argument
-
The JP1/AJS job execution ID at the time the job was started (the value of the AJSEXECID environment variable that was specified when JP1/AJS started the job)
-
- -n JP1/AJS-job-number
-
Specifies a JP1/AJS job number as a condition for the jobs whose job definition script operation information is to be output.
You can output jobs that match either of the following as character strings:
-
The job number specified in this argument
-
The JP1/AJS job number at the time the job was started (the value of the JP1JobID environment variable that was specified when JP1/AJS started the job)
For example, to specify the job with job number 0000012345, you must specify -n 0000012345, with the leading zeros. If you specify -n 12345, it is not considered a match to the job number.
Note that job number formats might differ between platforms.
For details about job numbers, see the applicable JP1/AJS manual.
-
- -g JP1/AJS-job-name
-
Specifies a JP1/AJS job name as a condition for the jobs whose job definition script operation information is to be output.
You can output jobs that match either of the following as character strings:
-
The job name specified in this argument
-
The JP1/AJS job name at the time the job was started (the value of the AJSJOBNAME environment variable that was specified when JP1/AJS started the job)
-
- -u JP1/Advanced-Shell-execution-user-name
-
Specifies the execution user name of the process running the adshexec command that executed the job as a condition for the jobs whose job definition script operation information is to be output.
You can output jobs that match either of the following as character strings:
-
The user name specified in this argument
-
The user name for the process running the adshexec command that executed the job
-
- -p job-definition-script-file-path-name
-
Specifies the path name of the job definition script file specified in the adshexec command when the job was executed as a condition for the jobs whose job definition script operation information is to be output.
You can output jobs that match either of the following as character strings:
-
The path name specified in this argument
-
The path name of the job definition script file specified in the adshexec command
Even if the path name can be interpreted as being for a job's job definition script file, if there is no match as a character string, the job will not be considered as a job whose job definition script operation information is to be output. The following is an example:
- Example of when there is not a path name match:
-
Current directory when the adshexec command is executed: /home/user1
Path name specified in the adshexec command: ./test1.ash
Path name specified in the adshevtout command: /home/user1/test1.ash
-
- -i JP1/Advanced-Shell-job-ID
-
Specifies a JP1/Advanced Shell job ID as a condition for the jobs whose job definition script operation information is to be output.
You can output jobs that match either of the following as character strings:
-
The job ID specified in this argument
-
The JP1/Advanced Shell job ID of the job (the value of the ADSH_JOBID environment variable)
For example, to specify the job whose job ID is 000001, you must specify -i 000001. The leading zeros cannot be omitted.
-
- -j JP1/Advanced-Shell-job-name
-
Specifies a JP1/Advanced Shell job name as a condition for the jobs whose job definition script operation information is to be output.
You can output jobs that match either of the following as character strings:
-
The job name specified in this argument
-
The JP1/Advanced Shell job name (the value of the ADSH_JOB_NAME environment variable)
-
- -t
-
Specifies that output of the header information is to be suppressed when the job definition script operation information is output.
- -d
-
Specifies that output of the job definition script operation information is to be suppressed.
You use this argument when you want to output the header information only.
- -m
-
Specifies that only the messages are to be output as the job definition script operation information.
- -z
-
Specify that output of information about environment variables is to be suppressed when the job definition script operation information is output.
- -h logical-host-name
-
Specifies the name of a logical host that is executing jobs whose job definition script operation information is to be output.
The adshevtout command outputs job definition script operation information from the event files in the spool corresponding to the specified logical host.
In Windows, the length of the logical host name must not exceed 196 bytes, and it is recommended that it not exceed 63 bytes. If you specify a name that exceeds 63 bytes, the command might not function correctly.
This argument is for specifying an execution environment. It is not for specifying a condition for the jobs whose job definition script operation information is to be output.
The -h specification is ignored if the logical host name specified in this argument is not defined in an environment file.
Return codes
Return code |
Meaning |
---|---|
0 |
Normal termination |
1 |
There is an error in a command line specification. |
2 |
There is an error in an environment variable setting. |
3 |
The character encoding set in the LANG environment variable is not supported. |
4 |
There is an event file for which processing was skipped. Check the messages output by the command to determine the cause. |
5 |
An I/O error occurred in referencing the spool, and the spool could not be referenced. |
6 |
The spool could not be referenced because it is being accessed by another command. |
7 |
An error occurred during message output processing. |
8 |
An error occurred during processing of output to the standard output. |
10 |
An error occurred during acquisition of the date and time. |
11 |
A memory shortage occurred. |
12 |
An inconsistency in internal processing was detected. |
13 |
An error occurred during initialization processing. |
The return code will generally be the maximum value among the return codes for all events that occurred during command execution, except for return code 4, which is output only when no other events occurred.
Specifying the same argument more than once
If the same argument is specified multiple times, the last specification takes effect.
- Example:
-
The following case is treated as specifying -s 19900401:
adshevtout -s 20120411 -s 19900401
Combinations of different arguments
When multiple arguments for determining the information to be output are specified, the arguments are interpreted according to the priority order shown in the following table:
Argument priority# |
Argument |
Description |
---|---|---|
1 |
-d |
The operation information is not output. |
2 |
-m |
Only messages are output. |
3 |
-z |
Information about environment variables is not output. |
Job execution start date and time
The lower and upper boundaries for the job execution start date and time can be specified in any of the three formats listed and described in the table below.
The range of years that can be specified in YYYY is 1970 through 2038.
Specification format of the date and time |
Interpretation of the specification |
---|---|
YYYYMMDD,hhmmss |
Specifies the year, month, date, hour, minute, and second. An upper bound is interpreted as the specified time plus 1 second. If the time is specified as 235959, it is interpreted as 00:00:00 on the date following the specified date. |
YYYYMMDD |
Specifies the year, month, and date only. The hour, minute, and second are interpreted as follows.
|
, hhmmss |
Specifies the hour, minute, and second only. The year, month, and date are interpreted as the execution date of the command. An upper bound is interpreted as the specified time plus 1 second. If the time is specified as 235959, it is interpreted as 00:00:00 on the date following the specified date. |
Examples of interpreting the date and time are shown in the table below. For Nos. 5 through 7 in the table, it is assumed that the adshevtout command was executed on October 23, 2012.
No. |
Specification in the command |
Date and time interpreted by the command |
|
---|---|---|---|
Lower bound for the execution start date and time |
Upper bound for the execution start date and time |
||
1 |
20120501,000000 |
May 1, 2012, 00:00:00 |
May 1, 2012, 00:00:01 |
2 |
20120501,100000 |
May 1, 2012, 10:00:00 |
May 1, 2012, 10:00:01 |
3 |
20120501,235959 |
May 1, 2012, 23:59:59 |
May 2, 2012, 00:00:00 |
4 |
20120501 |
May 1, 2012, 00:00:00 |
May 2, 2012, 00:00:00 |
5 |
,000000 |
October 23, 2012, 00:00:00 |
October 23, 2012, 00:00:01 |
6 |
,100000 |
October 23, 2012, 10:00:00 |
October 23, 2012, 10:00:01 |
7 |
,235959 |
October 23, 2012, 23:59:59 |
October 24, 2012, 00:00:00 |
The date and time specified in the command are interpreted on the basis of the time zone set in the TZ environment variable at the time the command executes.
It is important to note that even if the same date and time character string is specified in two different commands, if those commands are executed in different time zones (according to the values set in the respective TZ environment variables), the dates and times will be interpreted differently.
The dates and times that can be specified are as follows:
-
Expressed in Coordinated Universal Time (UTC):
January 1, 1970, 00:00:00 through January 19, 2038, 03:14:07
-
Expressed in Japan Standard Time (UTC+9):
January 1, 1970, 09:00:00 through January 19, 2038, 12:14:07
For time zones not listed above, the representation of the specifiable range of dates and times depends on the time zone being used.
Note that there are time-related implementation differences among OSs, so errors might result even for dates that fall within the ranges listed above. The following circumstances will generate an error:
-
An invalid date or time is specified.
-
The lower bound for the execution start date and time is later than the upper bound.
TZ Environment variable
The time zone specified in the TZ environment variable is referred to for the following purposes:
-
Interpretation of the date and time specified in an argument of a command when the command executes
-
Representation of a date and time in job definition script operation information
For details about the relationship between time zones and the representation of dates and times, see 3.6.3 Relationship between dates and times and time zones in the operation information.
The TZ environment variable is specified in POSIX format as illustrated below. Note the use of the sign.
- Example:
export TZ=JST-9
The TZ environment variable cannot be specified in Time Zone Database format, as illustrated below.
- Examples of incorrect usage:
export TZ=Asia/Tokyo export TZ=Japan
Do not execute the adshevtout command with the TZ environment variable set to daylight saving time. The adshevtout command does not support daylight saving time.
For details about setting the TZ environment variable, see the specifications for the OS being used.
Lower bound of the job execution start date and time
If you specify a lower bound for the job execution start date and time with -s, the jobs whose job definition script operation information will be output must satisfy the following constraint:
ts tj
tj: Job execution start date and time
ts: Lower bound for the job execution start date and time interpreted by the adshevtout command
Upper bound of the job execution start date and time
If you specify an upper bound for the job execution start date and time with -e, the jobs whose job definition script operation information will be output must satisfy the following constraint:
tj < te
tj: Job execution start date and time
te: Upper bound for the job execution start date and time interpreted by the adshevtout command
Job definition script operation information that can be output
-
The job definition script operation information that can be output is what is stored in the event files that are accessible to the user who executed the command. If an applicable event file is not accessible to the user who executed the command, a message is output and job definition script operation information in the inaccessible event file is not output.
-
Job definition script operation information is not output for jobs that are executing or for jobs for which the adshexec command terminated with an error. This means that job definition script operation information is not output for a job whose name in the spool job directory name is in one of the following forms:
-
job-ID
-
job-ID-
-
-
Job definition script operation information is not output for deleted jobs.
A job is considered to have been deleted if the spool job management file indicated below does not exist immediately below the spool job directory:
-
UNIX: .sysout
-
Windows: sysout.ini
-
Concurrent execution with the adshhk command
-
The adshevtout command and the adshhk command (for deleting spool jobs) apply exclusive control to spool directories.
-
The adshevtout command and the adshhk command cannot run at the same time on the same spool directory.
-
More than one adshevtout command can be executed on the same spool directory at the same time.
-
If the adshevtout command cannot be executed because the spool directory is under exclusive control, an error message is output and processing terminates.
Notes
-
If there is a large quantity of job definition script operation information to be output, you can split it up by executing separate commands with output conditions that divide the information on the basis of dates or other criteria.
Usage example
-
Output to the out.csv file the job definition script operation information for JP1/Advanced Shell job ID 000100.
adshevtout -i 000100 > out.csv