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:

• Agent Groups (HOSTG)
• :PROCESS... :TERM_PROCESS... :ENDPROCESS
• GET_PROCESS_LINE

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

See also: