2.4.9 Passing information that changes dynamically to a succeeding unit (example of defining a jobnet that uses a passing information setting job)

(a) Preceding jobs of passing information setting job

The preceding jobs of a passing information setting job must satisfy the following criteria:

• The passing information setting job has at least one preceding job

• Only one preceding job meets all the following criteria:

  • The job is a PC job^#1, Unix job^#1, flexible job^#2, HTTP connection job or custom job

  • The job specifies a file name or $JP1AJS2_JPQSTDOUTTEMP$ as the name of the standard output file^{#3, #4}

  • The job outputs its results to the standard output file

  #1

  Excluding queueless jobs.

  #2

  When the contents of the standard output file are passed from a flexible job to a passing information setting job, the maximum size of data that can be passed is 4,096 bytes. If the size of the output data exceeds 4,096 bytes, only the first 4,096 bytes are available (data beyond this is ignored). The 4,096-byte limitation is applied on both the relay agent and the destination agent. Therefore, if the relay agent and the destination agent use different character encodings, the output data must not exceed 4,096 bytes in either character encoding. Note that if a multibyte character is split at the 4,096th byte, the multibyte character is replaced by a question mark (?).

  #3

  Specify a file name if you want the standard output file to remain on the agent host. The specified file remains on the agent host even if transferred to the manager host.

  If there is no need for the standard output file to remain on the agent host, specify $JP1AJS2_JPQSTDOUTTEMP$ as the file name. In this case, the standard output file is output to the agent host as a temporary file and transferred to the manager host. You cannot append data to such a file. You can check the name of the file transferred to the manager host by executing the ajsshow command with the -i option and specifying the 2-byte format indicator %so.

  #4

  For flexible jobs, you do not need to specify $JP1AJS2_JPQSTDOUTTEMP$ as the file name.

Cautionary notes

• If you define a passing information setting job as a dependent job of a judgment job, the preceding job of the judgment job is considered to be a preceding job of the passing information setting job. In this scenario, a standard output file name must be specified in the definition of the preceding job of the judgment job.

• If restrictions placed on file reception interrupt the transfer of the standard output file, the process will create an incomplete file. Make sure that the passing information setting job is still able to extract the necessary information from the incomplete file. Note that a newly installed JP1/AJS3 is initially set to discard the rest of the data in a file after receiving 5 MB of data. If this setting causes extraction of information to fail, adjust the value of the LimitReceiveFileSize environment setting parameter.

• If restrictions placed on file transmission interrupt the transfer of the standard output file, the process will create an incomplete file. Make sure that the passing information setting job is still able to extract the necessary information from the incomplete file. Note that a newly installed JP1/AJS3 is initially set to discard the rest of the data in a file after sending 3 MB of data. If this setting causes extraction of information to fail, adjust the value of the LimitSendFileSize environment setting parameter.

(b) Passing information setting job

Specify the following attributes for the passing information setting job:

Regular expressions

Specify the regular expressions used to extract information from the standard output file which is output by the preceding job.

Output macro variable

Specify the name of the macro variable to which the job assigns the information extracted according to the regular expression.

If no lines in the standard output file that is output by the preceding job match the regular expressions, a NULL character string is assigned to the output macro variable.

The following table describes the values a passing information setting job returns when it finishes executing.

Table 2‒20: Return values from passing information setting jobs

Return value of the preceding job	Return values from passing information setting jobs	Description
0	0	All regular expressions were matched
	1	At least one regular expression was not matched
	20 and higher	Other errors
Other than 0	Return value of the preceding job	If the value of the PassingInfoUsePreRc environment setting parameter is 1
	0	If environment setting parameter PassingInfoUsePreRc is set to 0, and all regular expressions match
	1	If environment setting parameter PassingInfoUsePreRc is set to 0, At least one regular expression was no matched
	20 and higher	If environment setting parameter PassingInfoUsePreRc is set to 0, Other errors

If you want to continue execution of the succeeding unit even if a regular expression does not match, perform the following procedure.

• If the value of the PassingInfoUsePreRc environment setting parameter is 0, set 1 as the abnormal threshold value for the passing information setting job.

• If the value of the PassingInfoUsePreRc environment setting parameter is 1, make settings so that the return value of the preceding job is 0, and set the abnormal threshold of the passing information setting job to 1.

If you rerun a passing information setting job that has finished executing, the information assigned to the output macro variable is set again based on the contents of the standard output file and the regular expressions that were current at the time the job was rerun.

Regular expressions specified in passing information setting jobs are treated as extended regular expressions regardless of whether the feature is enabled in JP1/Base. For details on extended regular expressions, see the JP1/Base User's Guide.

Take the following actions to specify an extended regular expression:

• Enclose the section to be extracted in parentheses.

• Use a period (.) to represent any character except a line break.

• A dollar sign ($) means the string must end with this pattern to match.

Cautionary notes

• If you specify more than one pair of parentheses, the character string matching the leftmost pair is extracted.

• If you do not specify parentheses, a character string that matches the entire extended regular expression is extracted.

• Information is extracted from each line contained in the standard output file using the extended regular expressions. The job cannot extract information spanning multiple lines.

• If there is an error in the syntax of an extended regular expression (for example, there is no closing parenthesis to match an opening one), the passing information setting job terminates abnormally.

• A line in the standard output file cannot exceed 1,024 bytes in length. If a passing information setting job attempts to extract information from a line that is longer than 1,024 bytes, the job terminates abnormally.

• If multiple character strings match the extended regular expression, the first match encountered from the beginning of the file is extracted.

The following table describes examples of the information extracted by extended regular expressions.

Table 2‒21: Examples of extended regular expressions

Target character string	Pattern	Extended regular expression	Extracted information
abcdefghi	One pair of parentheses	abc(...)ghi	def
	Multiple pairs of parentheses	abc(.)(.)(.)ghi	d
	No parentheses	...$	ghi

(c) Succeeding jobs of passing information setting units

Specify the name of the variable specified as the output macro variable for the passing information setting job.

(a) No relation lines

For a job that has no relation line drawn to the passing information setting job, you can check the passed information provided that the passing information setting job was executed first.

Figure 2‒99: Example of passed information for jobs with no relation line

The following table describes whether passed information can be referenced for the example in this figure.

Table 2‒23: Whether passed information can be referenced for jobs with no relation lines

Job	Whether passed information can be referenced
Job A	Can be referenced if the passing information setting job was executed before Job A. The same applies if the job is rerun. Passed information cannot be referenced if the passing information setting job was executed after Job A.
Job B	Can be referenced if the passing information setting job was executed before Job B. The same applies if the job is rerun. Passed information cannot be referenced if the passing information setting job was executed after Job B.
Job C	Cannot be referenced at execution of the root jobnet. Can be referenced if Job C is rerun.

(b) Nested jobnet

The jobs in a root jobnet can reference the information passed by a passing information setting job in a nested jobnet.

Figure 2‒100: Example of passed information for a nested jobnet

The following table describes whether passed information can be referenced for the example in this figure.

Table 2‒24: Whether passed information can be referenced for nested jobnets

Job	Whether passed information can be referenced
Job A	Cannot be referenced at execution of the root jobnet. Can be referenced if Job A is rerun.
Job B	Can be referenced.
Job C	Cannot be referenced at execution of the root jobnet. Can be referenced if Job C is rerun.
Job D	Can be referenced.

(c) Remote jobnet

The following describes whether passed information can be referenced when a passing information setting job is defined in a jobnet that includes a remote jobnet.

(d) Jobnet connector

The information passed by a passing information setting job defined in a jobnet with a jobnet connector or its connection-destination jobnet can only be referenced from the jobnet that contains the passing information setting job.

(e) Wait conditions

When a unit with wait conditions and its units whose ends are being waited for are in different root jobnets, passed information can only be referenced within the scope of the respective root jobnets.

Figure 2‒106: Example of passed information using wait conditions

The following tables describe whether passed information can be referenced for the example in this figure.

Table 2‒30: Whether passed information can be referenced (passing information setting Job A)

Job	Whether passed information can be referenced
Job A	Cannot be referenced at execution of Root Jobnet A. Can be referenced if Job A is rerun.
Job B	Can be referenced.
Job C	Cannot be referenced.
Job D	Cannot be referenced.
Job E	Cannot be referenced.

Table 2‒31: Whether passed information can be referenced (passing information setting Job B)

Job	Whether passed information can be referenced
Job A	Cannot be referenced.
Job B	Cannot be referenced.
Job C	Cannot be referenced at execution of Root Jobnet B. Can be referenced if Job C is rerun.
Job D	Can be referenced.
Job E	Can be referenced.