Loop - Processes

Declaration

<AMLOOP ACTIVITY="processes" DOMAINNAME="text" 
REMOTEMACHINE="text" USERNAME="text" 
PASSWORD="text (encrypted)" RESULTVARIABLE="text" 
RESULTDATASET="text" INCLUDE="text" EXCLUDE="text" 
SORT="text (options)">

Description: Loops through the processes (applications) that are currently running on the local system or remote machine and populates a variable with the file name of the current process. With each successive loop, the next process file name is retrieved. The loop ends after all the process file names have been retrieved or when a Break is encountered. Optionally, a dataset can be populated with extended process information. This activity supports scanning

Practical Usage

Mainly used to perform one or more activities on a single or multiple processes (applications) running on the system. For example, an administrator can retrieve the process ID of each instance of a running process. This number may be used as a parameter in various function calls allowing processes to be manipulated, such as adjusting the process's priority or killing it altogether.

General Parameters

Property	Type	Required	Default	Markup	Description
Store process name in variable	Text	Yes	(Empty)	RESULTVARIABLE="varname"	The name of an existing variable that should be populated with the next process name on each successive loop.
Discard path information	Yes/No	No	No	KEEPPATHS="yes"	If set to YES, the folder path is removed from the return value so that only the filename is returned (e.g., iexplore.exe). This parameter is set to NO by default.
Create and populate dataset	Text	No	(Empty)	RESULTDATASET="DSName"	The name of a dataset to be created and populated with process data. In addition to the standard dataset fields, this dataset will contain the fields specified below under Datasets.

Advanced Parameters

Property	Type	Required	Default	Markup	Description
Include processes	Text	No	(Empty)	INCLUDE="*Explorer"	Indicates a wildcard mask to designate the process names to be included in the loop. Asterisk () or question mark (?) can be used as wildcard characters. For example, if explorer* was entered, this activity would loop only processes that contains the text 'explorer' in its name. To specify multiple wildcard masks, separate each one with a pipe (\|) character (.txt\|.jpg).
Exclude processes	Text	No	(Empty)	EXCLUDE="*Explorer"	Indicates a wildcard mask to designate the process names to omit in the loop. Asterisk () or question mark (?) can be used as wildcard characters. For example, if notepad* was specified, the loop would omit processes that include the text notepad in its name. To specify multiple wildcard masks, separate each one with a pipe (\|) character (.txt\|.jpg).
Pre-sort list	Text (options)	No	Do not sort	SORT="ascending"	Specifies the sort order that should be applied towards the list of processes before the loop begins. The available options are: Do not sort (default) - No sorting will be applied. Ascending alphabetical order - The list will be sorted in ascending alphabetical order (A-Z). Descending alphabetical order - The list will be sorted in descending alphabetical order (Z-A).

Property

Type

Required

Default

Markup

Description

Include processes

Text

(Empty)

INCLUDE="*Explorer"

Indicates a wildcard mask to designate the process names to be included in the loop. Asterisk (*) or question mark (?) can be used as wildcard characters. For example, if *explorer* was entered, this activity would loop only processes that contains the text 'explorer' in its name. To specify multiple wildcard masks, separate each one with a pipe (|) character (*.txt|*.jpg).

Exclude processes

Text

(Empty)

EXCLUDE="*Explorer"

Indicates a wildcard mask to designate the process names to omit in the loop. Asterisk (*) or question mark (?) can be used as wildcard characters. For example, if *notepad* was specified, the loop would omit processes that include the text notepad in its name. To specify multiple wildcard masks, separate each one with a pipe (|) character (*.txt|*.jpg).

Pre-sort list

Text (options)

Do not sort

SORT="ascending"

Specifies the sort order that should be applied towards the list of processes before the loop begins. The available options are:

Do not sort (default) - No sorting will be applied.
Ascending alphabetical order - The list will be sorted in ascending alphabetical order (A-Z).
Descending alphabetical order - The list will be sorted in descending alphabetical order (Z-A).

Computer Parameters

Property	Type	Required	Default	Markup	Description
Local computer					If enabled, specifies that the processes to loop resides on the local machine. This parameter is enabled by default. If this parameter is selected, the Another computer parameter becomes inactive. This is a visual mode parameter used during design time only, therefore, it contains no markups.
Another computer					If enabled, specifies that the processes to loop resides on a remote machine. The parameters below become active if this parameter is enabled. This is a visual mode parameter used during design time only, therefore, it contains no markups.
Computer	Text	Yes	(Empty)	REMOTEMACHINE="pcname.domain.com" REMOTEMACHINE="xxx.xxx.xxx.xxx"	The host name (computername.domain.com) or IP address (xxx.xxx.xxx.xxx) of the remote machine where the processes to loop resides. This parameter is available only if the Another computer parameter is enabled.
Domain	Text	Yes	(Empty)	DOMAINNAME="netauto"	The domain name of the remote machine where the processes to loop resides. This parameter is available only if the Another computer parameter is enabled.
Username	Text	Yes	(Empty)	USERNAME="Bruce.Wayne"	A valid username used to log onto the remote machine in which the processes to loop resides. This parameter is available only if the Another computer parameter is enabled.
Password	Text	Yes	(Empty)	PASSWORD="encrypted"	The password corresponding to the username entered in the Username field. This parameter is available only if the Another computer parameter is enabled.

Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.

Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)

On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)

Datasets

A dataset is a multiple column, multiple row container object. This action creates a dataset table with the information listed below (assuming the dataset name selected is theDataset):

Name	Data Type	Return Value
theDataset.ProcessName	Text	Returns the path and file name of the .exe file of the process.
theDataset.ProcessID	Number	Returns the unique ID of the process.
theDataset.WindowTitle	Text	Returns the title of the main window associated to the process.
theDataset.WindowClass	Text	Returns the class of the process's main window. A window class is a set of attributes that the system uses as a template to create a window.
theDataset.WindowHandle	Number	Returns The handle of the process's main window. A window handle is a code that uniquely identifies the window.

Example

The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Description: This task closes all currently open Notepad processes. In order for this task to work properly, make sure to have one or more instances of Notepad open on the desktop.

<!-- Closes all Notepad processes -->
<AMVARIABLE NAME="currentprocess"></AMVARIABLE>
<AMLOOP TYPE="PROCESSES" RESULTVARIABLE="currentprocess" INCLUDE="*notepad.exe" 
RESULTDATASET="ProcessDataset">
<AMENDPROCESS PROCESS="%currentprocess%" />
</AMLOOP>

Copyright © Fortra, LLC and its group of companies.
All trademarks and registered trademarks are the property of their respective owners.
v10 | 202212080228 | December 2022