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 (i.e. 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)

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

  2. FILE="Notepad.exe"

The path and filename 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 set to YES, 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 set to NO (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 set to YES, 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

  1. WINDOWSTARTUP="normal"

  2. WINDOWSTARTUP="maximized"

  3. WINDOWSTARTUP="minimized"

  4. 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\Network Automation\AutoMate 10\"

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 set to YES, 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 set to NO by default.

If the Wait until application completes parameter is set to YES then this parameter is ignored.

Wait until application is ready for input

Yes/No

No

Yes

WAITFORINPUT="NO"

If set to YES (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 set to YES then this parameter is ignored.

NOTE: DOS applications, batch files, and certain console applications may not function correctly with this parameter set to YES 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 set to YES, 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 set to YES.

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 set to YES, the running process will be terminated when the timeout period is reached. This parameter is set to NO by default and only available if the Wait until application completes parameter is set to YES.

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

  1. TERMINATEAFTERTIMEOUTSCALE="milliseconds"

  2. TERMINATEAFTERTIMEOUTSCALE="seconds"

  3. TERMINATEAFTERTIMEOUTSCALE="minutes"

  4. 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 set to YES 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 set to YES 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 set to YES under the Wait properties, this parameter becomes unavailable.

Advanced

Property

Type

Required

Default

Markup

Description

Run application as

Yes/No

No

No

  1. DOS="YES"

  2. 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 set to YES, specifies that if the file being written to already exists, it will be overwritten. If set to NO (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: The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Description

This sample task runs Notepad and sends keystrokes to it.

<AMRUN FILE="Notepad" />

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