Run Action

Declaration

<AMRUN FILE="text" DEFAULTFOLDER="text SINGLEINSTANCE="yes/no" WAITFORINPUT="yes/no" WAITFOREND="yes/no" RESULTVARIABLE="text" PROCESSIDVARIABLE="text [variablename]" WINDOWTITLEVARIABLE="text [variablename]" WINDOWCLASSVARIABLE="text [variablename]" WINDOWHANDLEVARIABLE="text [variablename]" WINDOWSTARTUP="text [options]" SINGLEINSTANCE="yes/no" ASEXPLORER="yes/no" DOS="yes/no" RESULTDATASET="text" /> (Draftnote: Declarations missing for console options?)

See Also

Run Action-Setting Properties, Print, End Process, Close Window, Send Keystrokes, Open Web Page

Description

Runs the program or document specified. If a document is specified, the application associated with the document will be used to open it.

Practical Usage

Commonly used to start an application or open a document in preparation to send keystrokes, mouse clicks or other interactive steps. The Run action has built in conveniences such as waiting for the application to be ready for input (finished loading) before moving on to the next step. The properties dialog box has a built in Start menu for easy selection of the application.

Remember 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 Tab

Run

Text, Required
MARKUP:
a) FILE="C:\WINNT\system32\NOTEPAD.EXE"
b) FILE="NOTEPAD.EXE"
c) FILE="C:\Program Files\Network Automation\AutoMate 7\AM7.chm"

Specifies the command line to run. This parameter should specify the full path and file name to the EXE, COM, BAT, or CMD file you wish to run. To specify a document, use the browse button or Start menu emulator and select the document. The properly formatted command line including the associated application for the document will be automatically built.

Run Only if Another Instance is Not Running

Yes/No, Optional, Default: NO
MARKUP: SINGLEINSTANCE="YES"

If set to YES, specifies that the program specified on the Run [FILE] parameter should not be run if another instance of it is running on the current system already. If another instance is running when this option is enabled, the step will be ignored and it will not generate an error.

Initial Window State

Text, Optional, Default: "normal"
MARKUP: WINDOWSTARTUP="minimized"

Specifies the state of the application’s window at startup.

The available options are:

Startup Folder

Text, Optional, Default: (the folder of the application specified in Run)
MARKUP: DEFAULTFOLDER="C:\Program Files\Network Automation\AutoMate 7\"

Certain applications require a startup folder. 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 Tab

Do Not Wait

Yes/No, Optional, Default: NO
MARKUP: WAITFORINPUT="NO"

When set to YES, specifies that the step will not wait until the application is finished loading. Selecting this parameter could result in the task moving to the next line too early which would cause any Interactivity steps to be sent into nothing (the application would not be loaded yet).

NOTE: 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, Optional, Default: YES
MARKUP: WAITFORINPUT="NO"

When set to YES, specifies that the step should wait until the application is finished loading and is ready to receive input such as keystrokes or mouse clicks. Not enabling this parameter could result in the task moving to the next line too early which would cause any interactivity steps such as keystrokes or mouse clicks to be sent into nothing (the application would not be loaded yet).

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

DOS applications, batch files, and certain console applications may not function correctly with the Wait until application is ready for input [WAITFORINPUT] parameter. This is because these applications do not support standard Windows event messaging that enables this kind of integration. For these applications, you may need to use a Pause <AMPAUSE> action or other method of waiting for the application to be ready for input.

Wait until application completes

Yes/No, Optional, Default: NO
MARKUP: WAITFOREND="YES"

When set to YES, specifies that 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

Variable, Optional, Default: (blank)
MARKUP: RETURNCODEVARIABLE="variablename"

Specifies an already existing variable to be populated with the application-provided return code. This parameter is only available when the Wait until application completes [WAITFOREND] parameter is set to YES. Not all applications use return codes, so the functionality of this action may vary from application to application.

Terminate process after

Yes/No, Optional, Default: NO
MARKUP: TERMINATEAFTERTIMEOUT="YES"

Specifies that the running process will be terminated within the specified amount of time.

Data Tab

Populate variable with process ID

Variable, Optional, Default: (blank)
MARKUP: PROCESSIDVARIABLE="variablename"

When set to YES, specifies an already existing variable to be populated with the application's process ID.

Create and Populate Dataset

Text, Optional, Default: (blank)
MARKUP: RESULTDATASET="DatasetName"

When set to YES, specifies the name of a dataset to be created and populated with data from the window of the application that was launched. In addition to the standard dataset fields, the dataset will contain the following:

Populate variable with window class

Variable, Optional, Default: (empty)
MARKUP: WINDOWCLASSVARIABLE="myvarname"

When a variable is named, it will be populated with the window class of the application that is launched.

NOTE: This parameter is only available when the Wait until application is ready for input [WAITFORINPUT] parameter is "YES".

Populate variable with window handle

Variable, Optional, Default: (empty)
MARKUP: WINDOWHANDLEVARIABLE="myvarname"

When a variable is named, it will be populated with the window handle (which is a unique number) of the application that is launched.

NOTE: This parameter is only available when the Wait until application is ready for input [WAITFORINPUT] parameter is "YES".

Populate variable with window title

Variable, Optional, Default: (empty)
MARKUP: WINDOWTITLEVARIABLE="myvarname"

When a variable is named, it will be populated with the window title of the application that is launched.

NOTE: This parameter is only available when the Wait until application is ready for input [WAITFORINPUT] parameter is "YES".

Advanced Tab

Run Application As

Yes/No, Optional, Default: NO
MARKUP: DOS="YES"

Specifies whether a standard Windows application, document or console application is being launched.

The available drop-down options are:

Console output

NOTE: The Console output settings have no effect unless the Wait for application to complete [WAITFOREND] option is enabled in the Wait tab.

Capture Output and Populate Variable

Variable, Optional, Default: (blank)
MARKUP: OUTPUTVARIABLE="theVariable"

If set to YES, specifies an already existing variable to be populated with the console output. Valid only if Run application as is set to Console application [DOS="YES"].

Capture Output and Write to File

Text, Optional, Default: (blank)
MARKUP: OUTPUTFILE="C:\Temp\filename.txt

Specifies a file to which the console output should be written. Valid only if Run application as is set to Console application [DOS="YES"].

Overwrite if File Already Exists

Yes/No, Optional, Default: NO
MARKUP: OVERWRITEOUTPUTFILE="YES"

If set to YES, specifies that if the file being written to already exists, it will be overwritten. If set to NO and the file already exists, the step will fail.

Notes

Provided Start Menu Emulator

In the properties dialog box for this action, a Start menu emulator based on your Windows Start menu configuration is provided for easy selection of the application or document. When a document (as opposed to an EXE file) is specified using either the Start menu or the browse dialog, the associated application is automatically detected and retrieved, and a properly formatted command line is built and inserted. When specifying a document (as opposed to an EXE file), it is advisable to use this automatically constructed command line.

Custom Description

This action includes the Description tab for entering a custom step description.

More on setting custom step description

Standard Error Handling Options

This action also includes the standard Error Causes and On Error failure handling options/tabs.

More on Error Handling Options

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by pressing F2.

More on variables
More on expressions

More on the expression builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

<AMRUN FILE="notepad.exe" />

<AMRUN FILE="%SystemRoot%\system32\NOTEPAD.EXE " DEFAULTFOLDER="%HOMEDRIVE + HOMEPATH%" PROCESSIDVARIABLE="VariableName1" WINDOWCLASSVARIABLE="VariableName2" SINGLEINSTANCE="YES" RESULTDATASET="DatasetName" />