Automation Engine Script Guide > Ordered by Function > Data Sequences > PREP_PROCESS_AGENTGROUP

PREP_PROCESS_AGENTGROUP

Script function: Uses selection criteria to retrieve the agents of an AgentGroup object and provides the result for further processing in the form of an internal list (data sequence).

Syntax

PREP_PROCESS_AGENTGROUP(AgentGroup, [Host], [Selection option], [RunID])

Syntax	Description/Format
AgentGroup	Name of the AgentGroup object whose agents should be read Format: AE name, scrip literal or script variable
Host	Filter for the agent name Format: script literal or script variable Maximum 32 characters Default value: "" The wildcard characters "" and "?" can be used. "*" stands for any number of characters, "?" for exactly one.
Selection option	Method to be used for retrieving the agent group's agents Format: AE name, script literal or script variable Allowed values: "BY_RULE" (default value), "ALL" and "RUNNR" "BY_RULE" - The script function returns the agent on which the next task will run. "ALL" - All the agent group's agents are retrieved. "RUNNR" - The retrieved agent(s) depend on a particular task. The RunID of the agent group container must be specified in the parameter of the same name. In agent groups with the mode "All", the options BY_RULE and ALL supply the same result.
RunID	Run number (RunID) of the agent group container. Format: script literal, script variable or number The agent(s) on which the task has run is/are returned if this parameter is used. Only specify this parameter if you selected the selection option RUNNR.

Return code
Reference to the data sequence of the AgentGroup object

Comments

This script function reads the agents of an AgentGroup object. These agents can be limited with parameters. By default, the reference to the whole data sequence is returned.

The return code of this script function is the reference to a data sequence. It is assigned to the script statements :PROCESS and :ENDPROCESS as a start parameter. In combination with the script function GET_PROCESS_LINE, it is possible to access each individual line of the data sequence. Data sequences are divided into two columns which can be specifically read:

Name of the agent
Status of the agent ("Y" - agent is active, "N" - agent is not active)

The status is mainly important for agent groups of mode "All". The script function always supplies all agents for such agent groups without consideration of whether they are active or not. The status information can be used to retrieve agents on which tasks can actually be processed.

Commas must always be set even if you search only for the selection and/or the RUN#.

No new value can be assigned to the script variable containing the data sequence reference. The data sequence must first be discarded with the script statement CLOSE_PROCESS and then the variable can be re-used.

Example

The first example retrieves all agents of a agent groups whose names start with "WIN".

:SET &HND# = PREP_PROCESS_AGENTGROUP("AGENTGROUP_WINDOWS","WIN*",ALL)

:PROCESS &HND#
:   SET &AGENT# = GET_PROCESS_LINE(&HND#,1)
:   SET &STATUS# = GET_PROCESS_LINE(&HND#,2)
:   PRINT "Agent: &AGENT#"
:   PRINT "Status: &STATUS#"
:ENDPROCESS

:CLOSE_PROCESS &HND#

The following example restarts a task. The script function SYS_ACT_ME_NR returns the RUN# of the original execution which can be used to retrieve the RUN# of the agent group Container. Therefore, the agents on which a task had originally run can be retrieved.

:SET &T_RUNNR# = SYS_ACT_ME_NR()
:SET &P_RUNNR# = GET_PARENT_NR(&T_RUNNR#)
:SET &HND# = PREP_PROCESS_AGENTGROUP("AGENTGROUP_DB",,RUNNR,&P_RUNNR#)

:PROCESS &HND#
:   SET &AGENT# = GET_PROCESS_LINE(&HND#,1)
:   SET &STATUS# = GET_PROCESS_LINE(&HND#,2)
:   PRINT "Agent: &AGENT#"
:   PRINT "Status: &STATUS#"
:ENDPROCESS

:CLOSE_PROCESS &HND#

Script element	Description
:CLOSE_PROCESS	Discards an unnecessary data sequence
:PROCESS... :TERM_PROCESS... :ENDPROCESS	They are used to define a loop for line-by-line processing of data sequences such as the content of a sequential file or the text result of a command.
GET_PROCESS_LINE	This is used to retrieve content from the current line of a data sequence.