PREP_PROCESS_AGENTGROUP

Use the PREP_PROCESS_AGENTGROUP script function to retrieve the Agents in an Agent Group object. The script function lets you define criteria by which to select Agents from the group. The script function returns a reference to a data sequence that you can use for further processing by assigning the return code to the :PROCESS script statement. Use the GET_PROCESS_LINE script function to access each comment in the task.

The data sequence includes two columns:

Name of the Agent
Status of the Agent

Tip: The status is important for Agent Groups with the Mode: All active and inactive setting. For these Agent Groups, the script function always returns all Agents, regardless of their status. Use the status information to retrieve Agents on which tasks can actually be processed.

Possible values:
- Y
  
  Agent is active
- N
  Agent is inactive

Note: You cannot assign a new value to the script variable that contains the reference to the data sequence. Use :CLOSE_PROCESS to discard the existing data sequence, and then assign a new value.

More Information:

Syntax

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

Parameters

PREP_PROCESS_AGENTGROUP or PREP_PROCESS_HOSTGROUP
Retrieves Agents from an Agent Group object
AgentGroup
Name of the Agent Group object
Format: AE name, script literal or script variable
Host
(Optional) Filters by Agent name
Note: Use the wildcard character * to stand for any number of characters, or ? for a single character.
Format: script literal or script variable
Maximum length: 32 characters
Default: *
Selection option
(Optional) Criteria for selecting Agents from the Agent Group
Format: AE name, script literal or script variable
Allowed values:
- BY_RULE (default)
  Returns the Agent on which the next task will run
  Note:If the Agent Group is set to Mode: All active and inactive, the options BY_RULE and ALL supply the same result. For more information, see Defining Agent Groups.
- ALL
  Returns all Agents in the Agent Group
- RUNNR
  Retrieves Agents on which a particular task has run
  Note: You must specify the RunID of the Agent Group container.
RunID
(Optional) RunID of the Agent Group container
Note: Only specify the RunID when you use the RUNNR option to select Agents.
Format: script literal, script variable or number

Note: Set all commas, even when you do not use the optional parameters.

Examples

The following example retrieves all Agents in Agent Group objects whose name starts 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#

In the following example, the SYS_ACT_ME_NR script function returns the RunID of the execution of a task. The script uses the task RunID to retrieve the RunID of the Agent Group container, and read the values of the Agents on which the task ran.

: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#

The following example retrieves the status of all Agents in an Agent Group:

:SET &HND# = PREP_PROCESS_AGENTGROUP("AGENTGROUP",,ALL)

:PROCESS &HND#

:SET &AGENT# = GET_PROCESS_LINE(&HND#,1)

:SET &STATUS# = GET_PROCESS_LINE(&HND#,2)

:ENDPROCESS

:CLOSE_PROCESS