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:

  1. Name of the agent
  2. 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#

 

See also:

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.

Script Element - Data Sequences

About Scripts
Scrip Elements - Alphabetical Listing

Script Elements - Ordered by Function