21.1.2 Details of execution agent profile

(a) @SYS_RESTRICT_START

The setting on this line is the fixed value @SYS_RESTRICT_START, which indicates the start of the execution agent restriction settings.

The information enclosed by this line and the corresponding @SYS_RESTRICT_END constitutes the settings for one unit. To specify information for multiple units, repeatedly specify the information for each enclosed by a @SYS_RESTRICT_START and a @SYS_RESTRICT_END. You can specify information for a maximum of 128 units.

This item must be set.

Cautionary note

If a large amount of information is set in the execution agent profile, the memory used by the execution agent profile might be insufficient. Use the AGENTPROFMEMSIZE environment setting parameter to set the amount of memory that can be used for the execution agent profile. Use the formula below to estimate the required amount of memory, then round the result to the next whole number and set the resulting value in hexadecimal. Note, however, that if the resulting value is smaller than 512, set dword:00000200 (512 in decimal).

Amount of memory in kilobytes required for the execution agent profile = (a + 256) / 1,024

a

Result of the following calculation performed for each unit (the information enclosed by a @SYS_RESRTICT_START and a @SYS_RESTRICT_END):

b + 1,280

b

Result of the following calculation performed for the execution entities (the information between @SYS_AGENTLIST_START and @SYS_AGENTLIST_END):

length-of-target-name-permitted-for-definition-or-execution + 128

For example, the execution agent profile might contain the following settings:

@SYS_RESTRICT_START
unit_path=/net1
View=on
ViewCheckLevel=warning
JobExec=on
@SYS_AGENTLIST_START
@SYSTEM
AGT01
@SYS_AGENTLIST_END
@SYS_RESTRICT_END
 
@SYS_RESTRICT_START
unit_path=/net2
View=on
ViewCheckLevel=warning
JobExec=on
@SYS_AGENTLIST_START
AGT02
AGT03
@SYS_AGENTLIST_END
@SYS_RESTRICT_END

For unit /net1, @SYSTEM and AGT01 are specified as execution targets. Therefore, the value of b is as follows:

(7 + 128) + (5 + 128) = 268

For unit /net2, AGT02 and AGT03 are specified as execution targets. Therefore, the value of b is as follows:

(5 + 128) + (5 + 128) = 266

The value of a is as follows:

(268 + 1,280) + (266 + 1,280) = 3,094

The amount of memory in kilobytes required for the execution agent profile is as follows:

(3,094 + 256) / 1,024 = Approx. 3.27

Because the value obtained from the above calculation is smaller than 512, set the AGENTPROFMEMSIZE environment setting parameter to 512.

For details about the AGENTPROFMEMSIZE environment setting parameter, see 20.4.2(98) AGENTPROFMEMSIZE.

(b) unit_path=full-name-of-the-unit

Use a character string of no more than 930 bytes to specify the full name of the unit. unit_path= is fixed. Specify this setting after @SYS_RESTRICT_START.

You can specify one of the following types of unit:

• Any unit contained in a scheduler service (a forward slash (/) is set in the unit name)

• Job group

• Root jobnet

• Nested jobnet

• Unix job

• PC job

• Event job

• Action job

• Custom job

• Flexible job^#

• HTTP connection job

#

A flexible job uses a relay agent, not an execution agent.

This item must be set.

(c) View=restriction-check-when-a-unit-is-defined

Specify whether you want to display the selected execution agents and check the restrictions for the specified execution agents when a unit is defined in the JP1/AJS3 - View Define Details dialog box. You can set either of the following values:

• on

  The selected execution agents are displayed and the restrictions are checked.

• off

  The selected execution agents are not displayed and the restrictions are not checked.

View= is fixed. Set this information on a line between unit_path= full-name-of-the-unit and @SYS_AGENTLIST_START.

This item is optional. If it is not specified, on is assumed.

(d) ViewCheckLevel=operation-when-a-unit-is-defined

Specify the operation to be performed if an execution entity that is not permitted is encountered during restriction checking when a unit is defined in the JP1/AJS3 - View Define Details dialog box. You can set either of the following values.

• error

  The dialog box cannot be closed by clicking the OK button if an execution entity that is not permitted is specified.

• warning

  If an execution target that is not permitted is specified, the KAVV1501-Q message is output. Depending on the response to the message, the unit definition is registered in JP1/AJS3 - Manager even when an execution entity that is not permitted is specified.

ViewCheckLevel= is fixed. Set this information on a line between unit_path=full-name-of-the-unit and @SYS_AGENTLIST_START. This setting is valid only when on is set for View=restriction-check-when-a-unit-is-defined.

This item is optional. If it is not specified, error is assumed.

(e) JobExec=restriction-check-at-job-execution

Set either of the following values to specify whether restriction checking is to be performed for execution agents when a job is executed.

• on

  Restrictions are checked.

• off

  Restrictions are not checked.

JobExec= is fixed. Set this information on a line between unit_path=full-name-of-the-unit and @SYS_AGENTLIST_START.

This item is optional. If it is not specified, on is assumed.

(f) @SYS_AGENTLIST_START

The setting on this line is the fixed value @SYS_AGENTLIST_START, which indicates the start of the specification of entities for which definition or execution is permitted. The information between this line and the corresponding @SYS_AGENTLIST_END holds the settings of the execution entities that are permitted to perform definition or execution.

This item must be set.

(g) entity-for-which-definition-or-execution-permitted

On one line, specify the execution agent, execution agent group, or execution host for which definition or execution is to be permitted. Use a character string of no more than 255 bytes for an execution entity. A maximum of 2,048 execution entities can be set on the lines enclosed by @SYS_AGENTLIST_START and @SYS_AGENTLIST_END.

Note that the specified values are not case sensitive.

If you specify more than 255 bytes for an execution entity or specify more than 2,048 execution entities between @SYS_AGENTLIST_START and @SYS_AGENTLIST_END, a syntax error occurs in the execution agent profile and the settings are not applied.

To specify an execution entity that begins with a hash mark (#) or a backslash (\), do the following:

• If the execution entity begins with a hash mark (#):

  Use a backslash (\) as an escape character. The escape character is not required if the hash mark (#) is the second or a subsequent character.

• If the execution entity begins with a backslash (\):

  Use a backslash (\) as an escape character. The escape character is not required if the backslash is the second or a subsequent character.

If the specified execution entity begins with a backslash (\) and the second character is neither a hash mark (#) nor a backslash (\), a syntax error occurs in the execution agent profile.

The following table contains concrete examples.

Table 21‒1: How to specify permitted execution entities

No.	Permitted execution entity	Specification in the execution agent profile	Remarks
1	AGT1	AGT1	--
2	#AGT1	\#AGT1	--
		#AGT1	The line is treated as a comment line.
3	\AGT1	\\AGT1	--
		\AGT1	A syntax error for the execution agent profile occurs.
4	##AGT1	\##AGT1	Only the first character requires an escape character. The second and subsequent characters do not need one.
5	\\AGT1	\\\AGT1
6	\#AGT1	\\#AGT1
7	#\AGT1	\#\AGT1
8	AGT#1	AGT#1	The second and subsequent characters do not require as escape character.
9	AGT\1	AGT\1

Legend:

--: None

When permitting execution on the local host:

@SYSTEM must be specified. Note, however, that if you want to permit an execution agent that has the same name as the local host name, specify the execution agent name.

If you want to permit execution of queueless jobs on the local host, specify the local host name. Hereafter, local host name refers to names that can be checked by using the following methods.

• Physical host:

  The host name determined by executing the hostname command

• Logical host (Windows):

  On the host on which JP1/AJS3 is running, in Control Panel, either choose Services, or choose Administrative Tools and then Services. In the Services dialog box that opens, the host name is displayed as xxxxx in JP1/AJS3_xxxxx

• Logical host (UNIX):

  Execute the ps command. The host name is displayed after the jajs_spmd process.

When specifying an execution agent group as the execution agent for units:

To specify an execution agent group as the execution agent for units, set the name of the execution agent group.

When specifying a macro variable name as the execution agent for units:

To specify a macro variable name as the execution agent for units, set an execution agent name or a macro variable name according to the settings of View=restriction-check-when-a-unit-is-defined and JobExec=restriction-check-at-job-execution. The following table describes the information that needs to be set for this item.

Table 21‒2: Settings when a macro variable is specified

No.	View=restriction-check-when-a-unit-is-defined setting	JobExec=restriction-check-at-job-execution setting	Setting required for entity-for-which-definition-or-execution-permitted
1	off	On	Execution agent name
2	on	Off	Macro variable name
3	on	On	Macro variable name Execution agent name

For queueless jobs:

To use the execution agent restriction functionality for a queueless job, set the name of the host on which the queueless job will be executed.

If the target host with a class name is specified in Exec-agent in the Define Details dialog box, you do not need to set the !class-name portion in the execution agent profile.

If a logical host that has not been attached is specified as the execution host for the queueless job, the queueless job is executed on the physical host corresponding to the logical host when the following conditions exist:

• The logical host specified for the queueless job has been set in the execution agent profile.

• exec is set in the AJSQL_NOATTACHREQ environment setting parameter.

Whether the physical host is set in the execution agent profile does not matter. Even if the physical host is not defined in the execution agent profile, the queueless job can be executed on the physical host.

(h) @SYS_AGENTLIST_END

The setting on this line is the fixed value @SYS_AGENTLIST_END, which indicates the end of the specification of the execution entities permitted for definition or execution.

This item must be set.

(i) @SYS_RESTRICT_END

The setting on this line is the fixed value @SYS_RESTRICT_END, which indicates the end of the execution agent restriction settings.

This item must be set.

(a) When setting an execution agent profile for all units in the scheduler service

Suppose that an execution agent will be permitted for all units in the scheduler service as described in the following table.

Table 21‒3: Example 1

Target unit	Restriction check when a unit is defined	Restriction check at job execution	Permitted execution entity
All units in the scheduler service	Restriction checked	Restriction not checked	@SYSTEM and AGT01

Specify the execution agent profile as follows.

@SYS_RESTRICT_START
unit_path=/
View=on
JobExec=off
@SYS_AGENTLIST_START
@SYSTEM
AGT01
@SYS_AGENTLIST_END
@SYS_RESTRICT_END

(b) When setting an execution agent profile for multiple unit paths

Suppose that an execution agent will be permitted for multiple unit paths as described in the following table.

Table 21‒4: Example 2

Target unit	Restriction check when a unit is defined	Restriction check at job execution	Permitted execution entity
All units in job group /Grp1	Restriction checked	Restriction not checked	AGT01 and AGT02
Jobnet /net1 and subordinate units	Restriction checked	Restriction checked	AGT03

Specify the execution agent profile as follows.

@SYS_RESTRICT_START
unit_path=/Grp1
View=on
JobExec=off
@SYS_AGENTLIST_START
AGT01
AGT02
@SYS_AGENTLIST_END
@SYS_RESTRICT_END
 
@SYS_RESTRICT_START
unit_path=/net1
View=on
ViewCheckLevel=warning
JobExec=on
@SYS_AGENTLIST_START
AGT03
@SYS_AGENTLIST_END
@SYS_RESTRICT_END