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

PREP_PROCESS_AGENTGROUP

Script functionPre-defined run book template in the Automation Engine. One single step only, e.g. Start Windows Service, Copy file,…: Uses selection criteria to retrieve the agents of an AgentGroup objectAutomation Engine controlled activities and processes are structured in the form of objects. See also: Task and provides the result for further processing in the form of an internal listShows entities in a grid view (data sequenceAn internal listing of Console outputs or lines of Variable objects, etc. The lines of a data sequence can be accessed by using a PROCESS loop or the script element GET_PROCESS_LINE. The script elements PREP_PROCESS* generate data sequences.). 

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 agentA program that enables the de-centralized execution of processes (such as deployments) on target systems (computers or business solutions) or a service that provides connectivity to a target system (such as for databases or middleware). An agent is also an object type in the Automation Engine. [Formerly called "Executor."] See also: host name
Format: scriptA particular Automation Engine object type. literal or script variableA placeholder for a value within a script.
Maximum 32 characters
Default value: "*"

The wildcard charactersThese are placeholders for characters when you specify filters. ? stands for exactly one character, * for any number of characters. "*" and "?" can be used. "*" stands for any number of characters, "?" for exactly one.

Selection option

Method to be used for retrieving the agent groupAn agent group combines agents of the same platform. The agents that should be included in an agent group are specified by entering the agent name or via filters. A task that runs in an agent group is processed on one or all of the agent group's agents, depending on the specified mode. A particular Automation Engine object type. '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 taskAn executable object that is running. Tasks are also referred to as activities. will run.
"ALL" - All the agent group's agents are retrieved.
"RUNNR" - The retrieved agent(s) depend on a particular task. The RunIDShort for "run number". It is a number that provides unique information about a task's execution. The RunID can include 7 to 10 digits. It is assigned by the Automation Engine component . 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 codeThe value that represents the result of tasks and script functions. 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 statusThis represents the condition of a task (such as active, blocked, generating). 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 variableIt stores or retrieves values dynamically at runtime. An individual Automation Engine object type. 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

 


Automic Documentation - Tutorials - Automic Blog - Resources - Training & Services - Automic YouTube Channel - Download Center - Support

Copyright © 2016 Automic Software GmbH