Loop
- Processes
Declaration
<AMLOOP ACTIVITY="processes" DOMAINNAME="text" REMOTEMACHINE="text" USERNAME="text" PASSWORD="text (encrypted)" RESULTVARIABLE="text" RESULTDATASET="text" KEEPPATHS="yes/no" INCLUDE="text" EXCLUDE="text" SORT="text (options)" />
Overview
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 one or more processes (applications) running on the system. For example, an administrator can retrieve the process ID of each instance of a running process. This number can be used as a parameter in various function calls, allowing processes to be manipulated, such as adjusting the process priority or stopping it altogether.
Parameters
General
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Store process name in variable | Text | Yes | (Empty) | RESULTVARIABLE="varname" | The name of an existing variable populated with the next process name on each successive loop. |
| Discard path information | Yes/No | No | No | KEEPPATHS="yes" | If enabled, the folder path is removed from the return value so that only the file name is returned (for example, iexplore.exe). This parameter is disabled by default. |
| Create and populate dataset | Text | No | (Empty) | RESULTDATASET="DSName" | The name of a dataset to create and populate with process data. In addition to the standard dataset fields, this dataset contains the fields specified below under Datasets. |
Advanced
| 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. You can use asterisks (*) or question marks (?) as wildcard characters. For example, if *explorer* is entered, this activity loops only processes that contain explorer in its name. To specify multiple wildcard masks, separate each one with a pipe (|) (*.txt|*.jpg). |
| Exclude processes | Text | No | (Empty) | EXCLUDE="*Explorer" | Indicates a wildcard mask to designate the process names to omit in the loop. You can use asterisks (*) or question marks (?) as wildcard characters. For example, if *notepad* is specified, the loop omits processes that include notepad in its name. To specify multiple wildcard masks, separate each one with a pipe (|) (*.txt|*.jpg). |
| Pre-sort list | Text (options) | No | Do not sort | SORT="ascending" | Specifies
the sort order to apply toward the list of processes
before the loop begins. The available options are:
|
Computer
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Local computer | --- | --- | --- | --- | If enabled, specifies that the processes to loop reside on the local machine. This parameter is enabled by default. If this parameter is selected, the Another computer parameter is 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 are 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) |
| The hostname (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 reside. 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 into the remote machine where the processes to loop reside. 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. |
Additional notes
Datasets
A dataset is a multiple column, multiple row container object. This action creates a dataset table with the following information (assuming the dataset name selected is theDataset):
| Name | Data Type | Return Value |
|---|---|---|
| theDataset.ProcessName | Text | The path and file name of the .exe file of the process. |
| theDataset.ProcessID | Number | The unique ID of the process. |
| theDataset.WindowTitle | Text | The title of the main window associated to the process. |
| theDataset.WindowClass | Text | The class of the process main window. A window class is a set of attributes that the system uses as a template to create a window. |
| theDataset.WindowHandle | Number | The handle of the process's main window. A window handle is a code that uniquely identifies the window. |
Example
- Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
- To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.
Description
The following task closes all currently open Notepad processes. In order for this task to work properly, ensure you have one or more instances of Notepad open on the desktop.
<!-- Closes all Notepad processes -->
<AMVARIABLE NAME="currentprocess" VALUE="" />
<AMLOOP ACTIVITY="processes" RESULTVARIABLE="currentprocess" RESULTDATASET="ProcessDataset" INCLUDE="*notepad.exe" />
<AMPROCESSES ACTIVITY="end" PROCESSNAME="%currentprocess%" />
<AMLOOP ACTIVITY="end" />