Run

Declaration

<AMRUN FILE="text" DEFAULTFOLDER="text" PROCESSIDVARIABLE="text" WAITFORINPUT="YES/NO" WAITFOREND="YES/NO" OUTPUTVARIABLE="text" OUTPUTFILE="text" OVERWRITEOUTPUTFILE="YES/NO" TERMINATEAFTERTIMEOUT="YES/NO" TERMINATEAFTERTIMEOUTLENGTH="number" TERMINATEAFTERTIMEOUTSCALE="test (options)" RESULTVARIABLE="text" WINDOWSTARTUP="text (options)" SINGLEINSTANCE="YES/NO" DOS="YES/NO" RESULTDATASET="text" />

Related Topics   

Description

Runs the program, application or document specified. If a document is specified, the application associated with the document will be used to open it. This action comprises some built in conveniences, such as the ability to wait for an application to finish loading (that is, be ready for input) or wait for it to complete its operation before continuing to the next step.

Practical usage

Commonly used to start an application or open a document in preparation to send keystrokes, mouse clicks or other interactive steps. Note that you can also specify documents in this action, so for many applications it is not necessary to first start the application and then use a separate step to open the document, as it can all be done in this one step.

Parameters

General

Property Type Required Default Markup Description
Run Text Yes (Empty)

  • FILE="C:\Temp\File.exe"

  • FILE="Notepad.exe"

 The path and file name of the file to run. If necessary, this parameter should include the full path to the EXE, COM, BAT, or CMD file you wish to run. To specify a document, click the folder icon or use the Start button (Windows logo) to browse to the desired item. The properly formatted command line including the associated application for the document will be automatically built.
Run only if another instance isn't running Yes/No No No SINGLEINSTANCE="YES" If selected, denotes that the application specified in the Run parameter should not start if another instance of that application is already running on the system. Instead, the step will be ignored and no error is generated. If disabled (default), the specified application will run despite other running instances.
Match processes by name (for compatibility with 64-bit applications) Yes/No NO (Empty) COMPAREBYNAME="YES" If selected, the method of comparing processes will be by the name of each process. This parameter is active only if the Run only if another instance isn't running parameter is enabled.
Initial window state Text (options) No Normal

  • WINDOWSTARTUP="normal"

  • WINDOWSTARTUP="maximized"

  • WINDOWSTARTUP="minimized"

  • WINDOWSTARTUP="hidden"

 In certain situations, a specific application may be more convenient to have running in the background, minimized or out of the way of other programs. This property allows you to control the state that the application's window should adhere to upon startup. The available options are:

  • Normal (Default) - The application's window will start in a normal state.

  • Maximized - The application's window will start maximized (fill the entire screen).

  • Minimized - The application's window will start minimized to the taskbar (or notification tray) .

  • Hidden - The application's window will start hidden. This is ideal for running batch files or console applications without the unwanted DOS window appearing.

NOTE: If an application is set to start Hidden, execution occurs without a visible window, thus, any interactive actions that try to interact with the hidden application will fail.
Startup folder Text No (Empty) DEFAULTFOLDER="C:\Program Files\AutoMate 2024\" The application's startup folder (if one is required). This option is not required and is available primarily for legacy (older) applications. When not specified, the folder that the application resides in is used.

Wait

Property Type Required Default Markup Description
Do not wait Yes/No No No WAITFORINPUT="NO" If selected, the step will not wait until the application is finished loading. Selecting this option could result in the task moving to the next line too early which would cause any interactive steps to be sent into nothing. This parameter is disabled by default.

If the Wait until application completes parameter is selected then this parameter is ignored.
Wait until application is ready for input Yes/No No Yes WAITFORINPUT="NO" If selected (default), the step will wait until the application is finished loading and is ready to receive input such as keystrokes or mouse clicks. Setting this parameter to NO could result in the task moving to the next step too early which would cause any interactive steps to be sent into nothing (because the application hasn't fully loaded yet). If the Wait until application completes parameter is selected then this parameter is ignored.
NOTE: DOS applications, batch files, and certain console applications may not function correctly with this parameter selected because such applications do not support standard Windows event messaging that enables this kind of integration. For these applications, you may need to use a Pause action or other method of waiting for the application to be ready for input.
Wait until application completes Yes/No No No WAITFOREND="YES" If selected, the step should wait until after the application has either closed itself (in the case of batch files, scripts, or console applications) or is closed by the user (in the case of Windows applications).
Populate variable with return code Text No (Empty) RETURNCODEVARIABLE="code" If enabled, specifies an already existing variable to be populated with the application-provided return code. This parameter is only available if the Wait until application completes parameter is selected.
NOTE: Not all applications use return codes, so the functionality of this action may vary depending on the application.
Terminate process after Number No No TERMINATEAFTERTIMEOUT="YES" If selected, the running process will be terminated when the timeout period is reached. This parameter is disabled by default and only available if the Wait until application completes parameter is selected.
Timeout length Number No No TERMINATEAFTERTIMEOUTLENGTH="50" The length of the timeout period. This value is used along with the Timeout scale parameter below in order to entirely display a timeout value.
Timeout scale Options No No

  • TERMINATEAFTERTIMEOUTSCALE="milliseconds"

  • TERMINATEAFTERTIMEOUTSCALE="seconds"

  • TERMINATEAFTERTIMEOUTSCALE="minutes"

  • TERMINATEAFTERTIMEOUTSCALE="hours"

The scale used to specify the timeout period. This parameter is used along with the Timeout length entered in order to entirely display a timeout value. The available options are:

  • Milliseconds - The timeout value will be measured by milliseconds.
  • Seconds (default) - The timeout value will be measured by seconds.
  • Minutes -  The timeout value will be measured by minutes.
  • Hours -  The timeout value will be measured by hours.

Data

Property Type Required Default Markup Description
Populate variable with process ID Text No (Empty) PROCESSIDVARIABLE="ID" If enabled, specifies an already existing variable to be populated with the application's process ID.
Create and populate Dataset Text No (Empty) RESULTDATASET="myDataset" If enabled, specifies the name of a dataset to be created and populated with data from the window of the application that was run. More information about the dataset that this action creates can be found below under Datasets.
Populate variable with window class Text No (Empty) WINDOWCLASSVARIABLE="myvar" If enabled, specifies an already existing variable to be populated with the window class of the application that is launched. If the Do not wait parameter is selected under the Wait properties, this parameter becomes unavailable.
Populate variable with window handle Text No (Empty) WINDOWHANDLEVARIABLE="handle" If enabled, specifies an already existing variable to be populated with the window handle of the application that is launched. If the Do not wait parameter is selected under the Wait properties, this parameter becomes unavailable.
Populate variable with window title Text No (Empty) WINDOWTITLEVARIABLE="title" If enabled, specifies an already existing variable to be populated with the window title of the application that is launched.  If the Do not wait parameter is selected under the Wait properties, this parameter becomes unavailable.

Advanced

Property Type Required Default Markup Description
Run application as Yes/No No No

  • DOS="YES"

  • ASEXPLORER="YES"

 Specifies how the application should be launched as. The available options are:

  • Standard Windows application (default) - The application will run as a standard Windows application.

  • Document - The application will run as a document such as MS Word.

  • Console application - The application will run as a console application that takes input and displays output at a command line console. Selecting this option enables the following parameters.
Capture standard output stream to variable Text No (Empty) OUTPUTVARIABLE="theVariable" If enabled, specifies that an existing variable will be populated with the console output. Valid only if the Run application as parameter is set to Console application.
NOTE: These settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.
Capture standard  output stream to file Text No (Empty) OUTPUTFILE="C:\Temp\filename.txt If enabled, specifies a file to which the console output should be written. Valid only if the Run application as parameter is set to Console application.
NOTE: These settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.
Overwrite if file already exists Yes/No No No OVERWRITEOUTPUTFILE="YES" If selected, specifies that if the file being written to already exists, it will be overwritten. If disabled (default) and the file already exists, it will not be overwritten, however, the step will fail as a result. Valid only if the Run application as parameter is set to Console application.
NOTE: These settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.
Capture standard error stream to variable Text No (Empty) ERRORVARIABLE="theVariable" If enabled, specifies that an existing variable will be populated with the console error code (if any). Valid only if the Run application as parameter is set to Console application.
NOTE: These settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.
Capture standard error stream to file Text No (Empty) ERRORFILE="C:\Temp\filename.txt If enabled, specifies a file to which the console output should be written. Valid only if the Run application as parameter is set to Console application.
NOTE: These settings have no effect unless the Wait for application to complete option is enabled in the Wait properties.

Description

Error Causes

On Error

Additional notes

Datasets

A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset containing a specific set of fields in addition to the standard dataset fields. The table below describes these fields (assuming the dataset assigned was named theDataset).

Name Type Return Value
theDataset.Title Text Returns the window title.
theDataset.Class Text Returns the window class.
theDataset.Handle Text Returns the window handle.
theDataset.ProdcessID Text Returns the process ID.
theDataset.ReturnCode Number Returns the Return Code.

Example

NOTE:
  • 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

This sample task runs Notepad and sends keystrokes to it.

Copy 
<AMRUN FILE="Notepad" />
<AMINPUT KEYSTROKES="Sending keystrokes to Notepad." PREDELAY="500" STAYFOCUSED="YES" DELAYBETWEENKEYS="50" />