2.2.6 Considerations regarding the use of macro variables

You can use macro variables to automate tasks because succeeding units can use the values of parameters each time jobs are executed.

Organization of this subsection

(1) Definition items for which macro variables can be specified
(2) Checking macro variables
(3) Determining the JP1/AJS3 behavior if the passing of information via a macro variable fails
(4) Using macro variables
(5) Cautionary notes

(1) Definition items for which macro variables can be specified

To pass information using macro variables, specify macro variables in the Define Details dialog box or Detailed Definition dialog box of succeeding units.

The following table describes the definition items for which macro variables can be specified.

Table 2‒16: Definition items for which macro variables can be specified
Unit type	Definition item
Jobnet	Exec-agent^#
Unix job	Exec-agent^#
	Command statement
	Script file name
	Parameters
	Environment variables
	Environment file^#
	Working path^#
	Standard input^#
	Standard output^#
	Standard error^#
	File name for End judgment (when Normal if specified file exists or Normal if file was updated is selected in the Rule box)^#
	User name^#
	File to transfer^#
	Destination file^#
PC job	Exec-agent^#
	File name
	Parameters
	Environment variables
	Environment file^#
	Working path^#
	Standard input^#
	Standard output^#
	Standard error^#
	File name for End judgment (when Normal if specified file exists or Normal if file was updated is selected in the Rule box)^#
	User name^#
	File to transfer^#
	Destination file^#
QUEUE job	Host name^#
	Queue name^#
	Job name^#
	File name
	Parameters
	File to transfer^#
	Destination file^#
Judgment job	Variable
Flexible job	Destination
	Relay agent
	File name
	Parameters
	Environment variables
	File name for End judgment (when Normal if specified file exists or Normal if file was updated is selected in the Rule box)
HTTP connection job	Exec-agent
	Conn. configuration file name
	Trans. info. file name
	Trans. info. file name (URL parameter)
	Trans. info. file name (Message body)
	Status file name
	Received header file name
	Received body file name
	Standard output
	Standard error
	File name for End judgment (when Normal if specified file exists or Normal if file was updated is selected in the Rule box)
	User name
Receive JP1 Event job	Exec-agent^#
Receive JP1 Event job	Host name^#
Receive JP1 Event job - extended attributes	Arbitrary extended attribute^#
Monitoring Files job	Exec-agent^#
Monitoring Files job	Monitoring file^#
Receive Mail job	Exec-agent^#
Monitoring Log Files job	Exec-agent^#
Monitoring Log Files job	File to be monitored^#
Monitoring Event Log job	Exec-agent^#
Interval Control job	Exec-agent^#
Send JP1 Event job	Exec-agent^#
	Event destination host
	Message
	Extended attribute
Send Mail job	Exec-agent^#
	Recipients
	Subject
	Message text
	Message text - file name
	Profile name
Send Mail job - attached files	Attached file
Send Mail job - attached files	Attached file - list file name
Send MQ Message job - detailed definition	Message data file
Send MSMQ Message job	Path name
	Queue label
	Message label
Send MSMQ Message job - message text	Message body file
OpenView Status Report job	Exec-agent^#
OpenView Status Report job	Additional information
Local Power Control job	Exec-agent^#
Remote Power Control job	Exec-agent^#
Remote Power Control job	Remote host
Custom Unix job	Exec-agent^#
	Command statement
	Script file name
	Parameters
	Environment variables
	Environment file^#
	Working path^#
	Standard input^#
	Standard output^#
	Standard error^#
	File name for End judgment (when Normal if specified file exists or Normal if file was updated is selected in the Rule box)^#
	User name^#
	File to transfer^#
	Destination file^#
Custom PC job	Exec-agent^#
	File name
	Parameters
	Environment variables
	Environment file^#
	Working path^#
	Standard input^#
	Standard output^#
	Standard error^#
	File name for End judgment (when Normal if specified file exists or Normal if file was updated is selected in the Rule box)^#
	User name^#
	File to transfer^#
	Destination file^#
Standard custom job	Exec-agent^#
	Standard output^#
	Standard error^#
	File name for End judgment (when Normal if specified file exists or Normal if file was updated is selected in the Rule box)^#
	User name^#

#: You can specify macro variables when the version of JP1/AJS3 - View and JP1/AJS3 - Manager is 09-50 or later.

To Page Top

(2) Checking macro variables

The names of the macro variables used in a job can be checked, and the result of inheriting information via macro variables can be checked after the job has been executed.

(a) Listing the macro variables being used

You can list the macro variable names used in subordinate units in the Variables Used dialog box of JP1/AJS3 - View or by executing the ajsprint command with the -v option specified. For details, see 12.3.25 Variables Used dialog box in the JP1/Automatic Job Management System 3 Operator's Guide, and see ajsprint in 3. Commands Used for Normal Operations in the manual JP1/Automatic Job Management System 3 Command Reference.

The following figure shows an example of listing macro variables by using the ajsprint command.

Figure 2‒61: Example of listing macro variables used in subordinate units

(b) Viewing the result of inheriting information via macro variables

In the Inherit Result dialog box of JP1/AJS3 - View, you can view the macro variable names and passing information specified when a job is registered for execution. You can also view the names of the macro variables that the job inherits during execution and the result of inheriting those values. For details, see 12.7.10 Inherit Result dialog box in the JP1/Automatic Job Management System 3 Operator's Guide.

You can also use the ajsshow command to view the same information by specifying the %MV two-byte format indicator for the -i option. If there are two or more items to be displayed as the result, the items are separated with commas (,). If there are two or more generations to be displayed, the generations are output on separate lines.

The following shows an example of executing the ajsshow command.

ajsshow -F AJSROOT2 -g 2 -i "%MV" /net
 
"AJS2ENV:/jp1_data/Job_Report","AJS2COM:c:\temp\test.exe"
"AJS2ENV:/jp1_data/Job_Report","AJS2COM:c:\temp\test.exe"
 
ajsshow -F AJSROOT2 -i "%MV" /net2
 
"AJS2ENV:/jp1_data2/Job Report","AJS2COM:c:\temp\test2.exe"

For details about the ajsshow command, see the ajsshow in 3. Commands Used for Normal Operations in the manual JP1/Automatic Job Management System 3 Command Reference.

Note that whether the results of passing (inheritance) can be displayed differs according to the unit type and the unit status. The following table lists unit types, unit statuses, and whether the results of passing can be displayed.

Table 2‒17: Whether the results of passing can be displayed
Unit type	Unit status	Whether the results of passing can be displayed
Root jobnet	Not registered	No
Root jobnet	Other statuses	Yes^#1
Nested jobnet	--	No
Job^{#2, #3}	Not registered	No
	Not sched. to exe.	No
	Waiting for prev. to end	No
	Being held	No
	Now queuing	No
	Waiting to execute	No
	Now running	No
	Ended normally	Yes
	Normal end + False	Yes
	Ended with warning	Yes
	Ended abnormally	Yes
	Failed to start	Yes
	Unknown end status	Yes
	Killed	Yes
	Not executed	No
	Bypassed	No
	Interrupted monitoring	Yes
	Shutdown	No

Legend:

Yes: The results can be displayed.

No: The results cannot be displayed.

-- : Not applicable

#1

Remote jobnets are excluded.

#2

The following jobs are excluded:

- The jobs subordinate to remote jobnets

- The jobs deleted during suspension

- The jobs added during suspension (other than those added after suspension is canceled)

#3

If the job status is changed, whether results can be displayed depends on the new status.

When a job that uses a macro variable is re-executed, the information passed via the macro variable during the previous execution is passed again. Therefore, by checking the result of the previous passing operation before re-executing the job, you will know the information that will be passed.

Supplementary notes

The results of passing differ from the previous execution in the following cases:

When the preceding job from which information is passed is being-re-executed:

The information passed from the preceding job is not displayed.
When the preceding job from which information is passed was re-executed and the re-execution has finished:

The passing information after the preceding job is re-executed is displayed.
When the preceding job from which information is passed was deleted during suspension:

The information passed from the preceding job is not displayed.
When two or more passing information setting jobs that specify the same macro variable name are defined in a jobnet

The passing information set by the last executed passing information setting job is displayed, regardless of the relation lines.
When re-execution of a passing information setting job terminates after the regular expression specified in the job has been changed

The passing information extracted based on the new regular expression when the passing information setting job is re-executed is displayed.
When a passing information setting job is re-executed after the preceding job has been sent to a standard output file different from the one used during the previous execution

The passing information extracted from the new standard output file when the passing information setting job is re-executed is displayed.

To Page Top

(3) Determining the JP1/AJS3 behavior if the passing of information via a macro variable fails

If the passing of information via a macro variable fails during execution of a job, JP1/AJS3 either changes the job status to Failed to start or continues jobnet execution by using the macro variable name as a string value.

You can use the MACROCHANGEFAIL environment setting parameter to determine the JP1/AJS3 behavior when the passing of information via a macro variable has failed.

For details about how to set the MACROCHANGEFAIL environment setting parameter, see 6.2.10 Setting the action to be taken if the value of a macro variable cannot be passed in the JP1/Automatic Job Management System 3 Configuration Guide (Windows) or 15.2.10 Setting the action to be taken if the value of a macro variable cannot be passed in the JP1/Automatic Job Management System 3 Configuration Guide (UNIX).

To Page Top

(4) Using macro variables

The table below describes how to use macro variables. For details, see the subsections listed in the Reference column.

Table 2‒18: Using macro variables
No.	Purpose	Reference
1	Passing the event information received by an event job to a succeeding unit	2.4.4(6) Passing information received by an event job 7.6.7 Notes on defining passing information
2	Outputting information that changes according to the circumstances of job execution to the standard output file and passing the information to a succeeding unit	2.4.9 Passing information that changes dynamically to a succeeding unit (example of defining a jobnet that uses a passing information setting job)
3	Passing to lower-level units the values specified for a jobnet when it was registered for execution	4.1.2 Specifying macro variables during registration for execution in the manual JP1/Automatic Job Management System 3 Overview

To Page Top

(5) Cautionary notes

Make sure that the total size of macro variable names and passing information in one root jobnet does not exceed 4,096 bytes. If the total size exceeds 4,096 bytes, data after the 4,096th byte might not be passed or the passing information setting job might end abnormally. To estimate the total size of macro variable names and passing information in a root jobnet, use the following procedure:
1. List the names of all macro variables used by all units in the root jobnet.
2. For all macro variables listed in step 1, consider the maximum size of passing information, and then obtain the result of the following expression for each macro variable:
  
  macro-variable-name-size + maximum-passing-information-size + 5 (bytes)
3. Sum all the values obtained in step 2.
If the same macro variable name is specified in multiple subordinate units of a root jobnet, the value of the macro variable is determined according to the following priority:
1. The passing information of an event job (other than the one in the start conditions) in the jobnet
2. The passing information of an event job in the start conditions
3. The passing information specified during registration for execution
4. The passing information generated by a passing information setting job^#
#:

If the same macro variable name is specified in two or more passing information setting jobs in a root jobnet, the passing information generated by the passing information setting job executed later is valid.

We recommend that you do not specify the same macro variable name at multiple locations in one root jobnet.
For some definition items, the support of macro variables started with JP1/AJS3 version 09-50. If you execute a unit with a macro variable specified for a definition item such as these when the JP1/AJS3 - Manager version is earlier than 09-50, the macro variable is not replaced by the passing information. Instead, the macro variable name itself is passed as the passing information.

For details about the target definition items, see (1) Definition items for which macro variables can be specified or the descriptions of dialog boxes for definitions in 12. Windows and Dialog Boxes in the JP1/Automatic Job Management System 3 Operator's Guide.
Each generation has its own values (passing information) for macro variables, and these values (passing information) cannot be passed among different generations. As a result, passing information cannot be passed to a unit that will be executed by a different generation, and cannot be inherited from a unit executed by a different generation.

The units that can be executed by different generations are as follows:
- Units (root jobnet, or planning group) that are the connection-destination jobnets of jobnet connectors
- Units whose end is being waited for, and that are subordinate to other root jobnets
When you use a remote jobnet, passing information cannot be passed to a unit that is subordinate to the remote jobnet. In addition, passing information cannot be inherited from a unit that is subordinate to the remote jobnet.

To Page Top