jprcollect (Windows and UNIX)

Organization of this page

Syntax
Description
Command directory
Options and arguments

Syntax

jprcollect
     unit-name
     output-file-name
     [  -b  year/month/day  -e  year/month/day
     |  [-L]  [-N]  [-T]
     |  {-l  month | -n  month | -t}  [-p  month]
     |  [-C]  [-G]  [-D] ] [-w]
     [-F  name-of-JP1/AJS-scheduler-service]
     [-A]  [-U]  [-y]

To Page Top

Description

The jprcollect command collects information about job operation from JP1/AJS. The command collects definition information and execution schedules and results for job network elements, and stores the information in a job operation information file. The information in these files is the basis for the documents output by JP1/AJS3 - Print Option.

The jprcollect command uses the ajsprint and ajsshow commands provided by JP1/AJS to collect job operation information.

Command name	Purpose
`ajsprint`	Collecting definition information
`ajsshow`	Collecting execution schedules and results

Before you use the jprcollect command, the environment (environment variables and other settings) must be configured to support the commands listed above. For details, see the manual JP1/Automatic Job Management System 3 Command Reference.

You can use unit names to specify the job operation information to collect. Use the full path of a JP1/AJS job, jobnet, or job group to specify a unit name. A full unit name begins with a forward slash (/) and consists of the names of the root jobnet down to the job network element, each separated by forward slashes.

To collect information for all units under the root job group, specify the -A option. If you use the -A option, you can specify / (the root job group) as the unit name.

The jprcollect command outputs the collected job operation information to the file (job operation information file) specified in output-file-name. Do not specify a file extension in output-file-name. JP1/AJS3 - Print Option creates a file with the extension .aoi when it outputs the information.

When collecting execution schedules and results, specify the period for which to collect the information. The collection period is defined by a start date and an end date. You can use date specification, monthly specification, relative month specification, or daily specification to specify the collection period.

The command collects information for units that are scheduled to execute or were executed within the collection period. It does not collect information for units in Now Running status.

The command does not collect execution schedules and results if the start or end date of the collection period falls after January 1st, 2037.

When you use monthly specification or relative month specification, specify the month for which to collect data. A month lasts from the base time on the first day of the month until a time 23 hours, 59 minutes, and 59 seconds after the base time on the last day of the month.

Examples of command specification:

When specifying a collection period by date specification and calendar date

To collect execution schedules and results for jobnet Net1 in job group Group1 for the period from January 1st, 2016 to January 31st, 2016 as a calendar date, and record the information in the file /tmp/file1.aoi, execute the command as follows:

jprcollect /Group1/Net1 /tmp/file1 -b 2016/01/01 -e 2016/01/31
When specifying a collection period by date specification and execution date

To collect execution schedules and results for jobnet Net1 in job group Group1 for the period from January 1st, 2016 to January 31st, 2016 as an execution date, and record the information in the file /tmp/file1.aoi, execute the command as follows:

jprcollect /Group1/Net1 /tmp/file1 -b 2016/01/01 -e 2016/01/31 -w
When specifying a collection period by monthly specification

To collect execution schedules and results for jobnet Net1 in job group Group1 using Last month as the collection period, and record the information in the file /tmp/file1.aoi, execute the command as follows:

jprcollect /Group1/Net1 /tmp/file1 -L

If you execute this command in April of 2016, the collection period will be from March 1st to March 31st, 2016.
When specifying a collection period by relative month specification and calendar date

To collect execution schedules and results for jobnet Net1 in job group Group1 using From 3 months ago for 2 months as the collection period, with the calendar date option specified, and record the information in the file /tmp/file1.aoi, execute the command as follows:

jprcollect /Group1/Net1 /tmp/file1 -l 3 -p 2

If you execute this command in April of 2016, the collection period will be from January 1st to February 28th, 2016.
When specifying a collection period by relative month specification and execution date

To collect execution schedules and results for jobnet Net1 in job group Group1 using From 5 months ago for 1 months as the collection period, with the execution date option specified, and record the information in the file /tmp/file1.aoi, execute the command as follows:

jprcollect /Group1/Net1 /tmp/file1 -n 5 -p 1 -w

If you execute this command in January of 2016, the collection period will be from June 1st to June 30th, 2016.
When specifying a collection period by relative month specification and execution date

To collect execution schedules and results for jobnet Net1 in job group Group1 using From 12 months ago for 12 months as the collection period, with the execution date option specified, and record the information in the file /tmp/file1.aoi, execute the command as follows:

jprcollect /Group1/Net1 /tmp/file1 -l 12 -p 12 -w

If you execute this command in December of 2017, the collection period will be from December 1st, 2016 to November 30th, 2017.
When specifying a collection period by daily specification and calendar date

To collect execution schedules and results for jobnet Net1 in job group Group1 using Last day as the collection period, with the calendar date option specified, and record the information in the file /tmp/file1.aoi, execute the command as follows:

jprcollect /Group1/Net1 /tmp/file1 -C

If you execute this command on December 8th, 2017, the collection period will be from December 7th, 2017 to December 7th, 2017.
When specifying a collection period by daily specification and execution date

To collect execution schedules and results for jobnet Net1 in job group Group1 using Today and Next day as the collection period, with the execution date option specified, and record the information in the file /tmp/file1.aoi, execute the command as follows:

jprcollect /Group1/Net1 /tmp/file1 -D -G -w

If you execute this command on December 8th, 2017, the collection period will be from December 8th to December 9th, 2017.

To Page Top

Command directory

In Windows:

installation-folder

In UNIX:

/opt/jp1ajs2pom/bin

To Page Top

Options and arguments

unit-name

Specify the name of the unit whose job operation information you want to collect. The command collects information for the specified unit and all its subordinate units.

This argument does not accept wildcards (such as * and ?).

Do not specify more than one unit name. If you do, an error occurs when you attempt to output a job operation document.

Unit names are case sensitive.

output-file-name

Specify the name of the job operation information file to which to output the collected job operation information, without the extension (.aoi).

You can specify the file name by absolute or relative path.

Do not use machine-dependent characters or any of the following symbols in the file name.

\ / : * ? " < > | $ ` -

If you use a hyphen (-), you can specify other than top of the file path name.

If you output the job operation information file by using JP1/AJS3 - Print Option, make sure that the folder path does not exceed 194 bytes, and the file name does not exceed 63 bytes.

In UNIX, make sure that the user who executes the command has write permission for the output directory.

-b year/month/day

Specify the start date of the period for which to collect execution schedules and results. The base time serves as the start time.

year

Specify a year as a value from 1994 to 2036.
month

Specify a month as a value from 1 (or 01) to 12.
day

Specify a date as a value from 1 (or 01) to 31.

This option must be specified together with the -e option. If you omit one or the other, the command will not collect execution schedules and results.

-e year/month/day

Specify the end date of the period for which to collect execution schedules and results. The date you specify must be the same as or later than the start date. The base time plus 23 hours, 59 minutes, and 59 seconds serves as the end time.

year

Specify a year as a value from 1994 to 2036.
month

Specify a month as a value from 1 (or 01) to 12.
day

Specify a date as a value from 1 (or 01) to 31.

This option must be specified together with the -b option.

-L

Specify this option when you want to collect execution schedules and results for the previous month.

You cannot specify this option with the -N option unless the -T option is also specified.

-N

Specify this option when you want to collect execution schedules and results for the next month.

You cannot specify this option with the -L option unless the -T option is also specified.

-T

Specify this option when you want to collect execution schedules and results for the current month.

-l month

Specify this option when you want to collect execution schedules and results for one or more months, starting from a past month.

You can specify the following values:

Month: 1 to 12

-n month

Specify this option when you want to collect execution schedules and results for one or more months, starting from a future month.

You can specify the following values:

Month: 1 to 12

-t

Specify this option when you want to collect execution schedules and results for one or more months, starting from the current month.

-p month

When collecting execution schedules and results on a monthly basis, specify the number of months for which you want to collect data.

You can specify the following values:

Month: 1 to 12

Specify this option together with the -l, -n, or -t option.

If you omit -p, then -p 1 is assumed and the command collects information for one month.

-C

Specify this option when you want to collect execution schedules and results for the previous day.

You cannot specify this option with the -G option unless the -D option is also specified.

-G

Specify this option when you want to collect execution schedules and results for the next day.

You cannot specify this option with the -C option unless the -D option is also specified.

-D

Specify this option when you want to collect execution schedules and results for today.

-w

Specify the start date and end date of the time period when execution schedules and results are collected as an execution date. If you omit this option, specify the start and end dates of the time period mentioned earlier as a calendar date.

-F name-of-JP1/AJS-scheduler-service

Specify the name of the JP1/AJS scheduler service to be accessed by the command.

-A

Allows you to specify the root job group (/) in unit-name.

-U

Specify this option to collect information about the last update times for the specified unit and its subordinate units. This information is only collected from JP1/AJS3 - Manager version 09-00 or later.

-y

Specify this option to collect jobnet information for each release ID when the registration information for the specified unit includes jobnet release information. This information is only collected from JP1/AJS3 - Manager version 09-00-04 or later.

For details on jobnet release, see the description of the jobnet release functionality in the manual JP1/Automatic Job Management System 3 Overview.

Return values

`0`	Normal termination
`4`	Ended with warning (the command collected definition information but not execution schedules and results)
`10`	Abnormal termination (argument specification error)
`20`	Abnormal termination (runtime error)

Supplementary note:

Each time you execute the jprcollect command, JP1/AJS3 - Print Option creates a file containing execution log information for the command in the same directory or folder as the job operation information file. The file has the same name as the output file but with the extension .log.

The jprcollect command does not validate its syntax before executing. If the command terminates abnormally, identify the problem by reviewing the execution log information.

The following shows an example of the information output to an execution log file:

[Figure]

Structure and contents of execution log information file:

Line 1: Product header

Line 2: Date and time when command was executed

Line 3: Options and arguments specified at command execution

Line 4 onward: Execution log and execution results of JP1/AJS3 or JP1/AJS2 command (ajsshow and ajsprint)

Cautionary notes:

If the unit you specify has not been registered for execution, the command will collect definition information but not execution schedules and results, even if you specify a collection period. The command will not collect execution schedules and results if the unit was not registered for execution within the specified collection period. In these situations, although the command terminates with a warning, you can still output documents based on the job operation information file. However, because execution schedules and results were not collected, you cannot output documents that contain execution schedules or results.

If you specify a job group that contains units that have been submitted for execution and those that have not, the command can only collect execution schedules and execution results for the units that have been submitted for execution.
In UNIX, make sure that the system where the command is executed uses the same character encoding as the JP1/AJS manager.

The character encoding is determined by a setting in the OS (such as the LANG environment variable) that is in effect when you execute the command.

If the system where the command is executed uses EUC encoding, the contents of the job operation information file are converted to Shift-JIS encoding. If a unit name or item value contains machine-dependent characters, a conversion error occurs.

If the system where the command is executed uses Shift-JIS or UTF-8 encoding, the job operation information file is output using the encoding of that system.
Specifying the -A option to collect job operation information for all units under the root jobnet can result in a large number of unit definitions and large amounts of schedule information being collected. The result is an extremely large job operation information file (.aoi file), which places significant demands on system resources. Displaying or printing such a file in the Job Operation Document Output window, or printing or outputting the file to a CSV file using the jprprint command, can take a very long time.
A job whose execution schedule and execution results exist within the range of the specified collection period is output. For a job whose execution started within the range of the collection period but ended beyond the range of the collection period, if you collect job operation information after the end of its execution, you can obtain the execution result data within the range of the collection period. You cannot obtain the execution result data beyond the range of the collection period.
The jprcollect command makes use of standard system commands to provide its functionality. Make sure that the following commands are able to be used:

In UNIX: sh, iconv, cp, rm, echo, hostname

In Windows: echo
When JP1/AJS3 - Manager is operating in a cluster environment, collect job operation information from the active node. To do so, specify the name of the scheduler service on the logical host as the service name.
If you specify the -L option, the -N option, the -T option, the -l option, the -n option, the -t option, the -p option, the -C option, the -G option, or the -D option, the collection period is determined based on the system time of the physical host, not the local time of the scheduler service. If the local time of the scheduler service differs from the system time of the physical host, specify a collection period based on the local time in the -b and -e options.
If a non-Administrator user executes the jprcollect command in a Windows server 2019, Windows Server 2016 or Windows Server 2012 environment with UAC enabled, an error occurs if a protected folder such as C:\Program Files is specified in the path of the output file. In this scenario, execute the command from a command prompt with Administrator privileges.
If you do not specify the -y option, the jprcollect command collects definition information, execution schedules, and execution results for units in Being Applied status. It cannot collect release information.
If you collect job operation information with the JP1/AJS3 environment setting parameter ADMACLIMIT set to yes, the KAVR1000-E error might occur. In that case, implement either of the following.

(In Windows)

Log on to the OS and create a JP1 user with the same name as the user account that executes the jprcollect command and set the JP1 permission level for the JP1 resource group of the target units for the ajsprint command and the ajsshow command.

For details about the JP1 permission levels that are required to execute the ajsprint command and the ajsshow command, see the documentation for JP1/AJS3.

(In UNIX)

Log in to the OS and create a JP1 user with the same name as the user account that executes the jprcollect command and set the JP1 permission level for the JP1 resource group of the target units for the ajsprint command and the ajsshow command.

For details about the JP1 permission levels that are required to execute the ajsprint command and the ajsshow command, see the documentation for JP1/AJS3.

If the JP1/AJS3 environment setting parameter AJSPRINTSORTUNITINF is set to yes, the related line information is output to the job operation information file in the character code ascending order for the preceding unit and succeeding unit. If the environment setting parameter AJSPRINTSORTUNITINF is set to no or a value is not set, the related line information is output in the creation order for the preceding unit and succeeding unit. For details, see the documentation for JP1/AJS3.

The jprcollect command uses the following information acquired by the JP1/AJS command ajsshow to determine the schedule information for jobs in the collection period:

- Scheduled execution start date and time obtained from a computed processing cycle

- Scheduled execution end date and time obtained from a computed processing cycle

If a job has finished executing, the command outputs the actual execution start and end times for the job, as shown in the example below

Figure 8‒1: Example of monthly schedule information (with timestamps) output after acquiring operation information for Feb 1 to 28 at 12:00 on Feb 16

You can make sure that a document does not include actual execution histories by specifying a future date as the start date of the collection period in the -b option.

When the jprcollect command is executed via the linkage with JP1/AJS3 - View, the information is collected using the calendar date or the KAVR5024-E error occurs if the destination is JP1/AJS3 - Print Option Manager 11-00 or earlier and the -w option is specified.
When the jprcollect command is executed via the linkage with JP1/AJS3 - View, the KAVR5024-E error occurs if the destination is JP1/AJS3 - Print Option Manager 11-10 or earlier and the number of months specified in the -l, -n, or -p option exceeds 6.
When the jprcollect command is executed via the linkage with JP1/AJS3 - View, the schedule information is not collected or the KAVR5024-E error occurs if the destination is JP1/AJS3 - Print Option Manager 11-10 or earlier and the -C, -D, and -G options are specified.
If you do not specify the -w option, the jprcollect command executes the ajsshow command with -b and -e options.

If you specify the -w option, the jprcollect command executes the ajsshow command with -v and -w options.
If you add new a unit or change a unit name on JP1/AJS during executing jprcollect command, the job operation information file has inconsistent data and an error occurs to output job operation information as documents.

Size of job operation information files

You can use the following equation to estimate the size of the job operation information file (aoi file) output by the jprcollect command.

Keep in mind that a certain amount of leeway is built into this equation.

Many of the factors governing file sizes depend on individual user settings. These include the length of unit names, the depth of the hierarchy, the position of the specified unit in the hierarchy, and the numbers of relation lines and schedule rules. For this reason, the result of the equation does not always reflect the actual file size.

Equation:

Number of units defined under specified unit x 4.5 kilobytes

+ Number of generations in specified collection period x 3.5 kilobytes

The amount of memory the jprcollect command will use is the same value as the above size.

How the Calendar date and Execution date options work differently

The following describes how the Calendar date and Execution date options work differently during collection:

Example 1: If Calendar date is selected in the Collecting Job Operation Information window to collect schedules on May 25, 2016:

jprcollect /grp1/net1 /tmp/file1 -b 2016/05/25 -e 2016/05/25

When this command is executed, the information of the job that is scheduled at 00:30 on May 26 and extends over two days is not collected.

[Figure]

Example 2: If Execution date is selected in the Collecting Job Operation Information window to collect schedules on May 25, 2016:

jprcollect /grp1/net1 /tmp/file1 -b 2016/05/25 -e 2016/05/25 -w

When this command is executed, the information of the job that is scheduled at 00:30 on May 26 and extends over two days is collected because the upper-level jobnet is scheduled to run on May 25.

[Figure]

Example 3: If Calendar date is selected in the Collecting Job Operation Information window to collect schedules of today:

jprcollect /grp1/net1 /tmp/file1 -D

When this command is executed on December 8, 2017, the information of the job that is scheduled at 00:05 on December 9 and extends over two days is not collected.

[Figure]

Example 4: If Execution date is selected in the Collecting Job Operation Information window to collect schedules of today:

jprcollect /grp1/net1 /tmp/file1 -D -w

When this command is executed on December 8, 2017, the information of the job that is scheduled at 00:05 on December 9 and extends over two days is collected because the upper-level jobnet is scheduled to run on December 8.

[Figure]

To Page Top