ajsagtadd
- Organization of this page
Format
ajsagtadd
[-h logical-host-name]
{-a execution-agent-name [-s execution-host-name]
[-c time-time=maximum-number-of-concurrently-executable-jobs,...]
[-t {e|i|h|b}] [-d description] |
-g execution-agent-group-name [-l execution-agent-name[:priority],...]
[-t {e|i|h|b}] [-d description] |
-f execution-agent-definition-file-name [-i]}Format1 (adding an execution agent)
ajsagtadd
[-h logical-host-name]
-a execution-agent-name
[-s execution-host-name]
[-c time-time=maximum-number-of-concurrently-executable-jobs,...]
[-t {e|i|h|b}]
[-d description]Format2 (adding an execution agent group)
ajsagtadd
[-h logical-host-name]
-g execution-agent-group-name
[-l execution-agent-name[:priority],...]
[-t {e|i|h|b}]
[-d description]Format3 (adding execution agents and execution agent groups all at one time)
ajsagtadd
[-h logical-host-name]
-f execution-agent-definition-file-name
[-i]Description
The ajsagtadd command adds an execution agent or an execution agent group.
You can also use the command to add execution agents and execution agent groups all at one time by using a file that specifies the items you want to add.
Execution privileges
This command can be executed by a user at the following JP1 permission level:
-
JP1_JPQ_Admin privilege
Arguments
-h logical-host-name
Specify the logical host name of the local host to which you want to add execution agents and execution agent groups.
You can specify a character string of 1 to 255 bytes.
If this option is omitted, the logical host name specified in the JP1_HOSTNAME environment variable is assumed. If the JP1_HOSTNAME environment variable is not specified, the physical host name is assumed.
For a physical host, make sure that you specify neither this option nor the JP1_HOSTNAME environment variable.
-a execution-agent-name
Specify the name of an execution agent you want to add.
You can specify a character string of 1 to 255 bytes.
-g execution-agent-group-name
Specify the name of an execution agent group you want to add.
You can specify a character string of 1 to 255 bytes.
-f execution-agent-definition-file-name
Specify the name of a file that specifies execution agents and execution agent groups that you want to add collectively.
You can specify a character string of 1 to 255 bytes.
For details about the format of this file, see Specifying the execution agent definition file settings below. The format of this file is the same as the format of the output result of the ajsagtprint command.
Note that, for the default execution agent (named @SYSTEM) specified in the execution agent definition file, you can change only the maximum number of concurrently executable jobs and the comment.
-s execution-host-name
Specify the name of the host on which the job will be executed.
You can specify a character string of 1 to 255 bytes.
If this option is omitted, the name of the execution agent is assumed.
You can specify this option only if the -a option is specified.
-c time-time=maximum-number-of-concurrently-executable-jobs,...
Specify a time period and the maximum number of concurrently executable jobs to be applied to the time period.
By specifying the maximum number of concurrently executable jobs, you can limit the number of jobs that can concurrently be executed on this execution agent. The specified limit is applied to UNIX, PC, flexible, HTTP connection, action, custom, and passing information setting jobs. If an attempt is made to execute a job when the number of concurrently executing jobs has already reached the maximum, the job is queued to wait until the number of concurrently executing jobs becomes smaller than the maximum.
The time period is specified by using the start and end times separated by a hyphen (-). Both times are specified in hh:mm format where mm is specified in units of 30 minutes.
For hh, you can specify 0 or a value in the range from 00 to 23 (hours).
For mm, you can specify 0, 00, or 30 (minutes).
For maximum-number-of-concurrently-executable-jobs, you can specify a value from 0 to 4,294,967,295.
If this option is omitted, 00:00-00:00=5, which applies 5 as the maximum number of concurrently executable jobs for all day, is assumed.
You can specify multiple combinations of time period and maximum number of concurrently executable jobs. To do this, use a comma (,) to separate each occurrence of time-time=maximum-number-of-concurrently-executable-jobs without inserting a space. You can specify a maximum of 48 time periods. If you specify overlapping time periods, the last specified value takes effect for the maximum number of concurrently executable jobs. For example, if you specify -c 1:00-2:30=5,2:00-4:00=10, the time period from 2:00 to 2:30 overlaps. For this time period, 10 is applied as the maximum number of concurrently executable jobs.
For the time periods that are not specified, 0 is assumed as the maximum number of concurrently executable jobs. For example, if you specify only -c 1:00-5:00=10, the maximum number of concurrently executable jobs are set as follows: 0 for the period from 0:00 to 1:00, 10 for the period from 1:00 to 5:00, and 0 for the period from 5:00 to 1:00.
If the command is executed during a specified time period, the maximum number of concurrently executable jobs for the time period immediately takes effect.
You can specify this option only if the -a option is specified.
-l execution-agent-name[:priority],...
Specify the name of an execution agent to be associated with the execution agent group. Following the execution agent name, you can also specify the priority of the execution agent in the execution agent group. If you specify the priority, place a colon (:) as a separator between the execution agent name and the priority.
Make sure that you specify an execution agent name that has already been registered.
You can use 1 to 255 bytes to specify an execution agent name.
As the priority value, you can specify 1 to 16 where 1 is lowest and 16 is highest. A job with a higher priority value is executed earlier. If the priority is omitted, 16 is assumed.
If you want to associate multiple execution agents to the execution agent group, specify multiple occurrences of execution-agent-name[:priority] by using a comma (,) to separate each occurrence, without inserting a space. The maximum number of execution agents that can be associated is 1,024 (or 2,048 if the value of the environment setting parameter AGENTLIMITEXTEND is 2).
You can specify this option only if the -g option is specified.
-t {e|i|h|b}
Specify the job transfer restriction status of the execution agent or execution agent group to be added.
|
Value |
Status |
Description |
|---|---|---|
|
e |
Effective |
Jobs are accepted and then delivered to the target host. |
|
i |
Ineffective |
New jobs are not accepted but the jobs that have already been accepted are delivered to the target host. |
|
h |
Hold |
Jobs are accepted but are not delivered to the target host. |
|
b |
Blockade |
Jobs are neither accepted nor delivered to the target host. |
If you omit this option, the system assumes e.
You can specify this option only if the -a or -g option is specified.
-d description
Specify a comment on the execution agent or execution agent group to be added.
You can specify a character string of 1 to 80 bytes.
You can specify this option only if the -a or -g option is specified.
-i
This option pertains to collective addition of execution agents and execution agent groups by using the execution agent definition file. If you specify this option, addition processing does not stop when an error occurs during the processing.
If you omit this option, the addition processing stops when an error occurs. If the addition processing stops, only the execution agents and execution agent groups processed before the error occurred are added.
This option takes effect only if the contents of the execution agent definition file are correct. If the contents are not correct, the command terminates without adding anything.
You can specify this option only if the -f option is specified.
After you specify this option to add execution agents and execution agent groups collectively, always execute the ajsagtshow or ajsagtprint command to confirm the result of addition. For details on the ajsagtshow command and the ajsagtprint command, see ajsagtshow in 3. Commands Used for Normal Operations and ajsagtprint in 3. Commands Used for Normal Operations.
Notes
-
The maximum number of concurrently executable jobs, the job transfer restriction status, and the execution agent priority specified by this command are not applied to event jobs.
-
This command cannot be used for a request from JP1/AJS3 to JP1/NQSEXEC or JP1/OJE for VOS3.
-
This command cannot be executed for JP1/AJS3 - Manager installed on another host.
-
If you specify an execution host name in the -s option and the name cannot be resolved from the manager host, the command might take a long time to execute.
-
When adding an execution host to an execution agent, the name of the execution host must be correctly resolved before you execute the command. Set the execution host name in the hosts file or DNS before executing the command. For details on name resolution, see 2.2.2(4) Notes on manager/agent system configurations in the JP1/Automatic Job Management System 3 System Design (Configuration) Guide.
-
Consecutive single-byte space characters at the end of explanatory text might become invalid. Do not end explanatory text with single-byte space characters.
-
The maximum number of ajsagtadd, ajsagtalt, and ajsagtdel commands that can be executed concurrently on the same host is five. If you attempt to execute more than five commands, the commands terminate abnormally.
Return values
|
0 |
Normal end. |
|
4 |
|
|
8 |
An argument specified in the command is incorrect. |
|
12 |
Memory became insufficient during command processing. |
|
20 |
An attempt to access shared memory failed because the access target was locked. |
|
24 |
Permission to execute the command is not granted. |
|
28 |
The contents of the execution agent definition file are incorrect. |
|
36 |
An error occurred while the command was accessing the execution agent definition file. |
|
40 |
A system limit was exceeded during allocation of shared memory, file descriptors, or resources for exclusive use. |
|
120 |
|
|
124 |
An unexpected error was detected in JP1/AJS internal processing. |
Additional information
The following shows examples of specifying the maximum number of concurrently executable jobs:
-
To set 1 as the maximum number of concurrently executable jobs for the time period from 1:00 to 5:00, specify the following:
-c 01:00-05:00=1
-
To set 1 as the maximum number of concurrently executable jobs for the time period from 23:00 to 24:00, specify the following:
-c 23:00-00:00=1
To indicate 24:00, specify 00:00 or 0:0.
-
To set 1 as the maximum number of concurrently executable jobs for the time period from 23:00 to 24:00 and the time period from 00:00 to 05:00 on the next day, specify the following:
-c 23:00-05:00=1
You can specify a time period that is across two days.
-
To set 1 as the maximum number of concurrently executable jobs for all day, specify the following:
-c 00:00-00:00=1
Specifying the execution agent definition file settings
The following are general rules that apply when you specify the execution agent definition file settings:
-
You can use one execution agent definition file to specify both execution agents and execution agent groups.
-
A single execution agent or execution agent group is entered on one line, and each element of one entry is separated with a comma (,). If you specify multiple entries, make sure that each entry is specified on a separate line.
-
A line beginning with a hash mark (#) is handled as a comment.
-
A blank line is ignored.
-
Each element of an entry must be enclosed in double quotation marks (").
-
No elements of an entry can be omitted. If you do not want to specify a value for an element, enter "".
The following describes how you can specify execution agents and execution agent groups in the file.
Specifying execution agents
- Format
"flag","execution-agent-name","target-host-system-name","maximum-number-of-concurrently-executable-jobs","job-transfer-restriction-status","description"
- Arguments
-
-
flag
Specify A, which indicates an execution agent definition.
-
execution-agent-name
Specify the name of an execution agent you want to add.
You can specify a character string of 1 to 255 bytes.
You cannot omit this element.
-
target-host-system-name
Specify the execution host name.
You can specify a character string of 1 to 255 bytes.
If you omit this element, the execution agent name is assumed.
-
maximum-number-of-concurrently-executable-jobs
Specify a time period and the maximum number of concurrently executable jobs for the time period.
The time period is specified by using the start and end times separated by a hyphen (-). Both times are specified in hh:mm format where mm is specified in units of 30 minutes.
For hh, you can specify 0 or a value in the range from 00 to 23 (hours).
For mm, you can specify 0, 00, or 30 (minutes).
For maximum-number-of-concurrently-executable-jobs, you can specify a value from 0 to 4,294,967,295.
If this option is omitted, 00:00-00:00=5, which applies 5 as the maximum number of concurrently executable jobs for all day, is assumed.
You can specify multiple combinations of time period and maximum number of concurrently executable jobs. To do this, use a comma (,) to separate each occurrence of time-time=maximum-number-of-concurrently-executable-jobs.
-
job-transfer-restriction-status
Use any of the following values to specify the job transfer restriction status of the execution agent to be added:
Value
Status
Description
Ef
Effective
Jobs are accepted and then delivered to the target host.
In
Ineffective
New jobs are not accepted but the jobs that have already been accepted are delivered to the target host.
Hd
Hold
Jobs are accepted but are not delivered to the target host.
Bl
Blockade
Jobs are neither accepted nor delivered to the target host.
If you omit this option, the system assumes Ef.
-
description
Write text as a description on the execution agent to be added.
You can specify a character string of 1 to 80 bytes.
-
- Example of coding
-
This example shows an entry that adds an execution agent under the following conditions:
-
execution-agent-name: AGT01
-
target host system name: HOST01
-
maximum number of concurrently executable jobs: 10 for the time period from 0:00 to 12:00, and 20 for the time period from 12:00 to 0:00
-
job-transfer-restriction-status: Jobs are neither accepted nor delivered to the target host.
-
description: AGT01 execution-agent
"A","AGT01","HOST01","00:00-12:00=10,12:00-00:00=20","Bl","AGT01 execution-agent"
-
Specifying execution agent groups
- Format
"flag","execution-agent-group-name","connection-destination-execution-agent-and-priority","job-transfer-restriction-status","description"
- Arguments
-
-
flag
Specify G, which indicates an execution agent group definition.
-
execution-agent-group-name
Specify the name of an execution agent group you want to add.
You can specify a character string of 1 to 255 bytes.
You cannot omit this element.
-
connection-destination-exec-target-and-priority
Specify the name of an execution agent to be associated with the execution agent group. Following the execution agent name, you can also specify the priority of the execution agent in the execution agent group. If you specify the priority, place a colon (:) as a separator between the execution agent name and the priority.
Make sure that you specify an execution agent name that has already been registered.
You can use 1 to 255 bytes to specify an execution agent name.
As the priority value, you can specify 1 to 16 where 1 is lowest and 16 is highest. A job with a higher priority value is executed earlier.
If you want to associate multiple execution agents to the execution agent group, specify multiple occurrences of exec-agent-name[:priority] by using a comma (,) to separate each occurrence, without inserting a space.
The maximum number of execution agents that can be associated is 1,024 (or 2,048 if the value of the environment setting parameter AGENTLIMITEXTEND is 2).
If you omit this element, the execution agent to be associated with the execution agent group is not set.
-
job-transfer-restriction-status
Use any of the following values to specify the job transfer restriction status of the execution agent group to be added:
Value
Status
Description
Ef
Effective
Jobs are accepted and then delivered to the target host.
In
Ineffective
New jobs are not accepted but the jobs that have already been accepted are delivered to the target host.
Hd
Hold
Jobs are accepted but are not delivered to the target host.
Bl
Blockade
Jobs are neither accepted nor delivered to the target host.
If you omit this option, the system assumes Ef.
-
description
Write text as a comment on the execution agent group to be added. You can specify a character string of 1 to 80 bytes.
-
- Example of coding
-
This example shows an entry that adds an execution agent group under the following conditions:
-
execution-agent-group-name: AGTGRP01
-
connection-destination-execution-agent and priority: AGT01(priority: 1), AGT02(priority: none)
-
job-transfer-restriction-status: Jobs are accepted but are not delivered to the target host.
-
description: AGTGRP01 execution-agent-group
"G","AGTGRP01","AGT01:1,AGT02","Hd","AGTGRP01 execution-agent-group"
-
Example 1
To add an execution agent with the same name as target host AP1, execute the following command:
ajsagtadd -a AP1
Example 2
To add an execution agent whose name is AP1 and whose maximum number of concurrently executable jobs for the time period from 01:00 to 05:00 is 1, execute the following command:
ajsagtadd -a AP1 -c 01:00-05:00=1
Example 3
To add execution agent group APG1 that contains execution agents AP1 (with a priority of 16), AP2 (with the default priority), and AP3 (with a priority of 5), execute the following command:
ajsagtadd -g APG1 -l AP1:16,AP2,AP3:5