EXECUTE command

Executes an application or process external to Analytics. Emulates the Windows Run command. Can be used to interact with the Windows command prompt.

Note

Because the EXECUTE command gives you the ability to interact with the operating system and applications external to Analytics, technical issues may arise that are beyond the scope of Analytics's native functionality.

Support can assist with operation of the EXECUTE command inside Analytics, but issues that arise with processes and applications external to Analytics are not covered under Support.

Syntax

EXECUTE Windows_Run_command_syntax <ASYNC>

Parameters

Name Description
Windows_Run_command_syntax

The name of the application to execute, the folder or file to open, or the command to run, followed by any required arguments or command switches.

Requires valid Windows Run command syntax enclosed by quotation marks.

ASYNC

optional

Runs the command in asynchronous mode.

In asynchronous mode, the Analytics script continues running without waiting for the process started by the EXECUTE command to complete.

If you omit ASYNC, then the process started by the EXECUTE command must complete before the Analytics script continues. Analytics is inaccessible while external processes are running.

Note

When running EXECUTE from the Analytics command line, you must specify ASYNC.

Analytics output variables

Name Contains
RETURN_CODE

The code returned by an external application or process run using the EXECUTE command.

What are return codes?

Return codes are numbers generated by the external application or process and sent back to Analytics to indicate the outcome of the external process. Analytics does not generate the return code, it only receives it.

Typical return codes

Typical return codes are integer values that map to specific notifications or error messages. For example, the return code "0" could mean "The operation completed successfully". The return code "2" could mean "The system cannot find the file specified".

The meaning of specific return codes

Specific return codes and their meanings vary depending on the external application or process. Lists of return codes, also called 'error codes' or 'exit codes', and their meanings, can often be found in the documentation for the associated external application. Lists of return codes can also be found on the Internet.

Variable created in default mode only

The RETURN_CODE variable is created when the EXECUTE command is run in default mode. The variable is not created when the command is run in asynchronous mode.

Examples

Open an application

Opens Microsoft Excel:

EXECUTE "Excel"

Opens Adobe Acrobat Reader:

EXECUTE "AcroRd32.exe"

Close an application

Closes Microsoft Excel:

EXECUTE "TASKKILL /f /im Excel.exe"

Note

Use the /f switch with caution. It forces an application to close without presenting any dialog boxes, such as those for saving changes.

Open a file

Opens the Excel workbook AP_Trans.xlsx:

EXECUTE '"C:\ACL Projects\Source Data\AP_Trans.xlsx"'

Create a new folder

Creates a new folder named Source Data:

EXECUTE 'cmd /c MD "C:\ACL Projects\Source Data"'

Run external scripts or non-Analytics batch files (.bat)

Runs the script My_Batch.bat:

EXECUTE '"C:\ACL Projects\Batch Files\My_Batch.bat"'

Pass parameters to a non-Analytics batch file

Passes two parameters to My_Batch.bat. Parameters can be literals or Analytics variables:

EXECUTE '"C:\ACL Projects\Batch Files\My_Batch.bat" param1%v_param2%'

Run Analytics scripts in other Analytics projects

Runs "AP_Trans_script" in AP Trans Tests.acl"

EXECUTE 'aclwin.exe "C:\ACL Projects\AP Trans Tests.acl" /b AP_Trans_script'

Note

Running an Analytics script in another project launches a second instance of Analytics. The script in the second project should end with the QUIT command so that the second instance of Analytics closes and control is returned to the initial instance of Analytics.

Incorporate a waiting period in an Analytics script

Both examples create a waiting period of 30 seconds:

EXECUTE "TIMEOUT /t 30"
EXECUTE "cmd /c PING -n 31 127.0.0.1 > nul"

Remarks

Use EXECUTE to perform useful tasks

The EXECUTE command allows you to run Windows and DOS commands from the Analytics command line or from an Analytics script.

You can use this ability to increase the automation of Analytics scripts by performing a variety of useful tasks that are not possible using ACLScript syntax alone.

Examples of tasks that can be started using EXECUTE

Open other programs and applications and perform tasks required by the Analytics script Pass parameters to a batch file Access data from network locations Incorporate Active Directory account lists
Open any file in its default application Run Analytics scripts in other Analytics projects Use FTP to access data from remote locations Integrate with VBScript
Perform file and folder administrative tasks such as copying, moving, creating, deleting, or comparing files or folders that exist outside of Analytics Incorporate waiting periods in Analytics scripts Zip or unzip data Integrate with SQL databases
Run external scripts or non-Analytics batch files (.bat) Incorporate Windows task scheduling in Analytics scripts Encrypt or decrypt data Open web pages

Note

Specific details of how to perform any of these tasks are beyond the scope of Galvanize Help documentation. For assistance, consult appropriate Windows operating system documentation, or other third-party documentation.

Default mode and asynchronous mode

You can run the EXECUTE command in either default mode or asynchronous mode:

  • Default mode the process started by EXECUTE must complete before the Analytics script can continue.

    Analytics is inaccessible while external processes are running.

  • Asynchronous mode the Analytics script continues to run without waiting for the process started by EXECUTE to complete.

    Analytics continues to be accessible while external processes are running.

    If you specify ASYNC, the EXECUTE command runs in asynchronous mode.

Which mode should I use?

When you create Analytics scripts that use the EXECUTE command you need to consider which mode of operation is appropriate.

Use default mode Use asynchronous mode / ASYNC
  • file and folder administrative tasks
  • specifying waiting periods
  • any task that subsequent tasks depend on
  • subsequent script execution depends on the result in the RETURN_CODE variable
  • external tasks cause an application interface or pop-up dialog box to open

Analytics scripts that run unattended

If you want an Analytics script that contains the EXECUTE command to run unattended, use one of the following methods:

  • use asynchronous mode for any tasks that cause an application interface or pop-up dialog box to open
  • avoid opening interface elements in unattended scripts

Note

Until interface elements are closed, they represent processes that are still running. If these interface elements are opened with EXECUTE in default mode, they prevent subsequent lines in an Analytics script from executing, and cause the script to hang.

EXECUTE command in analytic scripts

If you want to use the EXECUTE command in analytic scripts in Robots or on AX Server, you must specifically configure the command to run. For more information, see:

Quotation marks

The Windows Run command syntax that you use with the EXECUTE command must be enclosed by either single or double quotation marks.

The following example uses the Windows MD command to create a new folder:

EXECUTE 'cmd /c md C:\New_Data_Folder'

Nested quotation marks

If any paths within the Run command syntax contain spaces, the paths must also be enclosed within quotation marks.

You have two options when enclosing paths within quotation marks:

  • Double quotation marks inside single quotation marks Use single quotation marks to enclose the entire Run command string, and use double quotation marks internally to enclose paths:
    EXECUTE 'cmd /c md "C:\New Data Folder"'

    You may find this method easier to read than the second method.

    Note

    Reversing the order of the nesting – using double quotation marks to enclose the entire string, and single quotation marks to enclose paths – does not work.

  • Two double quotation marks Use double quotation marks to enclose the entire Run command string, and use two double quotation marks internally to enclose paths:
    EXECUTE "cmd /c md ""C:\New Data Folder"""

    If you use this second method, the two double quotation marks used internally must be immediately adjacent and cannot have a space between them.

Internal and external commands

Windows commands can be either internal or external.

  • Internal commands can be run from the command prompt only, which means that you have to open the command shell using cmd /c or cmd /k before specifying the command.
  • External commands can be run from either the command prompt or directly using the EXECUTE command, which means opening the command shell is an option, but not required.

The example below uses the internal Windows DIR command (displays the contents of a directory), and the external Windows COMP command (compares two files), to illustrate the difference:

EXECUTE 'cmd /k dir "C:\ACL DATA\Sample Data Files"' 
EXECUTE 'comp C:\File_1.txt C:\File_2.txt'

You can avoid this complication by creating external scripts or batch files to contain Windows commands, and by using the EXECUTE command only to start the batch file. For example:

EXECUTE 'C:\My_Batch.bat'

Multi-line Run command syntax

The EXECUTE command does not support multi-line Run command syntax. To incorporate multi-line Run commands in an Analytics script, use one of the following methods:

Method Example
Repeat the EXECUTE command for each Run command. 
EXECUTE 'cmd /c md "C:\New Data Folder"' 
EXECUTE 'cmd /c copy C:\File_1.txt "C:\New Data Folder"'
Combine Run commands using '&'. 
EXECUTE 'cmd /c md "C:\New Data Folder" & copy C:\File_1.txt "C:\New Data Folder"'
Create an external script or batch file to contain multi-line Run commands, and use the EXECUTE command only to start the batch file. 
EXECUTE 'C:\My_Batch.bat'