Processes - Get Information
Declaration
<AMPROCESSES DOMAINNAME="text" REMOTEMACHINE="text" USERNAME="text" PASSWORD="text (encrypted)" PROCESSNAME="text" RESULTDATASET="text" USEWMI="YES/NO" />
Description: Creates and populates a dataset with information about the specified process, such as process name, ID, start time, thread/handle count, system resource usage by the process, etc. (a full list is entered below under Additional Notes). This activity supports local or remote processes.
Practical Usage
Useful for gathering an assortment of information regarding a specific process that resides on the local machine or on a remote machine.
Process Parameters
|
Property |
Type |
Required |
Default |
Markup |
Description |
|---|---|---|---|---|---|
|
Do not filter |
|
|
|
|
If enabled, specifies that this activity will use no filters, therefore, information about all available processes will be retrieved and saved to a dataset. This is a visual mode parameter used during design time only, thus, contains no markups. If this parameter is selected, the Filter by name and Filter by process ID parameters become inactive. |
|
Filter by name |
Text |
No |
(Empty) |
PROCESSNAME="Photoshop.exe" |
If enabled, specifies the name of the process to retrieve information about. This can be entered manually or it can be selected from the provided drop-down list of available processes. If multiple instances of the same process exists, information about all instances will be retrieved. This parameter supports the absolute (full) path or relative (file name only) path of the process. If this parameter is selected, the Do not filter and Filter by process ID parameters become inactive. |
|
Filter by process ID |
Text |
No |
(Empty) |
PROCESSID="1234567" |
If enabled, specifies the unique identifier (a number used to uniquely identify a process) of the process to get information about. If this parameter is enabled, the Do not filter and Filter by Process Name parameters become inactive. |
|
Create and populate dataset |
Text |
Yes |
(Empty) |
RESULTDATASET="ProcessInfo" |
The name of a dataset to be created and populated with information about the specified process. More information about the dataset that this action creates can be found below under Additional Notes. |
|
Use WMI |
Yes/No |
No |
No |
USEWMI="YES" |
If set to YES,the WMI library is used to retrieve process information on the local machine. If set to NO (default), the .Net library is used instead. If the Another computer parameter is selected, this parameter is automatically grayed out. This is because only the WMI library can be used to get process information from a remote computer. Note: WMI (Windows Management Instrumentation) is the communication layer that Microsoft servers use to interact with remote machines on the network, however, it can be used to communicate with the local machine as well. |
Computer Parameters
|
Property |
Type |
Required |
Default |
Markup |
Description |
|---|---|---|---|---|---|
|
Local computer |
|
|
|
|
If enabled, specifies that the process to retrieve information about 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 process to retrieve information about 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) |
|
The host name or IP address of the remote machine in which to retrieve process information from. 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 to get process information from. This parameter is available only if the Another computer parameter is enabled. |
|
Username |
Text |
Yes |
(Empty) |
USERNAME="Bruce.Wayne" |
A valid use name used to log onto the remote machine in which to get process information from. This parameter is available only if the Another computer parameter is enabled. |
|
Password |
Text |
Yes |
(Empty) |
PASSWORD="batman" |
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.)
Dataset
This activity creates and populates a dataset with property information about the specified process. For processes that reside on the local machine, information can differ depending on whether the Use WMI parameter is set to YES or NO. If set to YES, retrieves process information via the Win32 Process WMI class. If set to NO, retrieves the information via the .Net Framework class library. Processes that reside on another machine default to the Win32 Process WMI class. This is because only the WMI library can be used to get process information from a remote computer.
WMI Library
The table below represents the complete list of dataset fields populated during runtime and their description as derived from the Win32 Process WMI class.
|
Name |
Description |
|---|---|
|
Caption |
Short description of an object—a one-line string. |
|
CommandLine |
Command line used to start a specific process, if applicable. This property is new for Windows XP. |
|
CreationClassName |
Name of the first concrete class in the inheritance chain that is used to create an instance. You can use this property with other key properties of the class to uniquely identify all of the instances of the class and its subclasses. |
|
CreationDate |
Date the process begins executing. |
|
CSCreationClassName |
Creation class name of the scoping computer system. |
|
CSName |
Name of the scoping computer system.. |
|
Description |
Description of an object. |
|
ExecutablePath |
Path to the executable file of the process. |
|
ExecutionState |
This property is not implemented and does not get populated for any instance of this class. This property is always NULL. |
|
Handle |
Process identifier. |
|
HandleCount |
Total number of open handles owned by the process. HandleCount is the sum of the handles currently open by each thread in this process. A handle is used to examine or modify the system resources. Each handle has an entry in a table that is maintained internally. Entries contain the addresses of the resources and data to identify the resource type. |
|
InstallDate |
Date a process is installed. The process may be installed without a value being written to this property. |
|
KernelModeTime |
Time in kernel mode, in 100 nanosecond units. If this information is not available, use a value of 0 (zero). |
|
MaximumWorkingSetSize |
Maximum working set size of the process. The working set of a process is the set of memory pages visible to the process in physical RAM. These pages are resident, and available for an application to use without triggering a page fault. |
|
MinimumWorkingSetSize |
Minimum working set size of the process. The working set of a process is the set of memory pages visible to the process in physical RAM. These pages are resident and available for an application to use without triggering a page fault. |
|
Name |
Label for an object. When inherited by a subclass, the property can be overridden to be a key property. |
|
OSCreationClassName |
Creation class name of the scoping operating system. |
|
OSName |
Name of the scoping operating system. |
|
OtherOperationCount |
Number of I/O operations performed that are not read or write operations. |
|
OtherTransferCount |
Amount of data transferred during operations that are not read or write operations. |
|
PageFaults |
Number of page faults that a process generates. |
|
PageFileUsage |
Amount of page file space that a process is using currently. This value is consistent with the VMSize value in TaskMgr.exe. |
|
ParentProcessId |
Unique identifier of the process that creates a process. Process identifier numbers are reused, so they only identify a process for the lifetime of that process. It is possible that the process identified by ParentProcessId is terminated, so ParentProcessId may not refer to a running process. It is also possible that ParentProcessId incorrectly refers to a process that reuses a process identifier. You can use the CreationDate property to determine whether the specified parent was created after the process represented by this Win32_Process instance was created. |
|
PeakPageFileUsage |
Maximum amount of page file space used during the life of a process. |
|
PeakVirtualSize |
The peak paged memory size. |
|
PeakWorkingSetSize |
Peak working set size of a process. |
|
Priority |
Scheduling priority of a process within an operating system. The higher the value, the higher priority a process receives. Priority values can range from 0 (zero), which is the lowest priority to 31, which is highest priority. |
|
PrivatePageCount |
Current number of pages allocated that are only accessible to the process represented by this Win32_Process instance. |
|
ProcessId |
Global process identifier that is used to identify a process. The value is valid from the time a process is created until it is terminated. |
|
QuotaNonPagedPoolUsage |
Quota amount of nonpaged pool usage for a process. |
|
QuotaPagedPoolUsage |
Quota amount of paged pool usage for a process. |
|
QuotaPeakNonPagedPoolUsage |
Peak quota amount of nonpaged pool usage for a process. |
|
QuotaPeakPagedPoolUsage |
Peak quota amount of paged pool usage for a process. |
|
ReadOperationCount |
Number of read operations performed. |
|
ReadTransferCount |
Amount of data read. |
|
SessionId |
Unique identifier that an operating system generates when a session is created. A session spans a period of time from logon until logoff from a specific system. |
|
Status |
This property is not implemented and does not get populated for any instance of this class. It is always NULL. |
|
TerminationDate |
Process was stopped or terminated. To get the termination time, a handle to the process must be held open. Otherwise, this property returns NULL. |
|
ThreadCount |
Number of active threads in a process. An instruction is the basic unit of execution in a processor, and a thread is the object that executes an instruction. Each running process has at least one thread. |
|
UserModeTime |
Time in user mode, in 100 nanosecond units. If this information is not available, use a value of 0 (zero). |
|
VirtualSize |
Current size of the virtual address space that a process is using, not the physical or virtual memory actually used by the process. Using virtual address space does not necessarily imply corresponding use of either disk or main memory pages. Virtual space is finite, and by using too much, the process might not be able to load libraries. This value is consistent with what you see in Perfmon.exe. |
|
WindowsVersion |
Version of Windows in which the process is running. |
|
WorkingSetSize |
Amount of memory in bytes that a process needs to execute efficiently—for an operating system that uses page-based memory management. If the system does not have enough memory (less than the working set size), thrashing occurs. If the size of the working set is not known, use NULL or 0 (zero). If working set data is provided, you can monitor the information to understand the changing memory requirements of a process. |
|
WriteOperationCount |
Number of write operations performed. |
|
WriteTransferCount |
Amount of data written. |
.Net Library Parameters
The table below contains the complete list of dataset fields populated during runtime and their description as derived from the .NET Framework class library.
|
Name |
Description |
|---|---|
|
BasePriority |
The base priority of the associated process. |
|
CanRaiseEvents |
A value indicating whether the component can raise an event. |
|
Container |
The IContainer that contains the Component. |
|
DesignMode |
A value that indicates whether the Component is currently in design mode. |
|
EnableRaisingEvents |
Gets or sets whether the Exited event should be raised when the process terminates. |
|
Events |
The list of event handlers that are attached to this Component. |
|
ExitCode |
The value that the associated process specified when it terminated. |
|
ExitTime |
The time that the associated process exited. |
|
Handle |
The native handle of the associated process. |
|
HandleCount |
The number of handles opened by the process. |
|
HasExited |
A value indicating whether the associated process has been terminated. |
|
Id |
The unique identifier for the associated process. |
|
MachineName |
The name of the computer the associated process is running on. |
|
MainModule |
The main module for the associated process. |
|
MainWindowHandle |
The window handle of the main window of the associated process. |
|
MaxWorkingSet |
Gets or sets the maximum allowable working set size for the associated process. |
|
MinWorkingSet |
Gets or sets the minimum allowable working set size for the associated process. |
|
Modules |
The modules that have been loaded by the associated process. |
|
NonpagedSystemMemorySize |
The nonpaged system memory size allocated to this process. |
|
NonpagedSystemMemorySize64 |
The amount of nonpaged system memory allocated for the associated process. |
|
PagedMemorySize |
The paged memory size. |
|
PagedMemorySize64 |
The amount of paged memory allocated for the associated process. |
|
PagedSystemMemorySize |
The paged system memory size. |
|
PagedSystemMemorySize64 |
The amount of pageable system memory allocated for the associated process. |
|
PeakPagedMemorySize |
The peak paged memory size. |
|
PeakPagedMemorySize64 |
The maximum amount of memory in the virtual memory paging file used by the associated process. |
|
PeakVirtualMemorySize |
The peak virtual memory size. |
|
PeakVirtualMemorySize64 |
The maximum amount of virtual memory used by the associated process. |
|
PeakWorkingSet |
The peak working set size for the associated process. |
|
PeakWorkingSet64 |
The maximum amount of physical memory used by the associated process. |
|
PriorityBoostEnabled |
Gets or sets a value indicating whether the associated process priority should temporarily be boosted by the operating system when the main window has the focus. |
|
PriorityClass |
Gets or sets the overall priority category for the associated process. |
|
PrivateMemorySize |
Gets the private memory size. |
|
PrivateMemorySize64 |
Gets the amount of private memory allocated for the associated process. |
|
PrivilegedProcessorTime |
PrivilegedProcessorTime Gets the privileged processor time for this process. |
|
ProcessName |
Gets the name of the process. |
|
ProcessorAffinity |
Gets or sets the processors on which the threads in this process can be scheduled to run. |
|
Responding |
A value indicating whether the user interface of the process is responding. |
|
SessionId |
The Terminal Services session identifier for the associated process. |
|
Site |
Gets or sets the ISite of the Component. (Inherited from Component.) |
|
StandardError |
A stream used to read the error output of the application. |
|
StandardInput |
A stream used to write the input of the application. |
|
StandardOutput |
A stream used to read the output of the application. |
|
StartInfo |
Gets or sets the properties to pass to the Start method of the Process. |
|
StartTime |
The time that the associated process was started. |
|
SynchronizingObject |
Gets or sets the object used to marshal the event handler calls that are issued as a result of a process exit event. |
|
Threads |
The set of threads that are running in the associated process. |
|
TotalProcessorTime |
The total processor time for this process. |
|
UserProcessorTime |
The user processor time for this process. |
|
VirtualMemorySize |
The size of the process's virtual memory. |
|
VirtualMemorySize64 |
The amount of the virtual memory allocated for the associated process. |
|
WorkingSet |
The associated process's physical memory usage. |
|
WorkingSet64 |
The amount of physical memory allocated for the associated process. |
Examples
The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.
Sample task 1: This sample task retrieves process information in regards to Internet Explorer (iexplore.exe) and displays the information in a message box. Internet Explorer must be running on the local machine to ensure proper examination of this task.
<AMGETPROCESSINFO USEWMI="YES" PROCESSNAME="iexplore.exe" RESULTDATASET="theProcess"/> <AMSHOWDIALOG>Process Information">Process Name: %theProcess.Name% Process Path: %theProcess.ExecutablePath% Process ID: %theProcess.ProcessId% Process Virtual Size: %theProcess.VirtualSize% Process Session ID: %theProcess.SessionId%</AMSHOWDIALOG>
Sample task 2: Retrieve information about a remote process with name "Photoshop.exe" and populate dataset named "theID" with the results. Displays information such as process path, ID, size and session ID in a message box.
<AMPROCESSES DOMAINNAME="computer.domain.com" REMOTEMACHINE="computerName" USERNAME="userame" PASSWORD="AM2ooXWPhaelJPRhbI+ZZ7nkw==aME" PROCESSNAME="Photoshop.exe" RESULTDATASET="theID" USEWMI="YES" /> <AMSHOWDIALOG WINDOWTITLE="Process Information">Process Name: %theProcess.Name% Process Path: %theProcess.ExecutablePath% Process ID: %theProcess.ProcessId% Process Virtual Size: %theProcess.VirtualSize% Process Session ID: %theProcess.SessionId%</AMSHOWDIALOG>