8.10.1 Exec (call an executable file on the local PC)

Purpose

Calls an executable file (EXE file, BAT file, COM file, SPT file, CMD file, or linked file) according to specified parameters. You can specify whether to wait for the called application to complete.

Linked files can be called in JP1/Script 05-00 and later versions.

Syntax

Exec (FileName, Flag [, Param1, Param2, ...])

Arguments

FileName

Specify the executable file as a character string or as a variable that stores this value.

You can specify any of the following types of files:

Executable file (.EXE)
MS-DOS batch file (.BAT)
MS-DOS executable file (.COM)
JP1/Script script file (.SPT)
Command script (.CMD)
Linked file

Flag

Specify True to wait for the specified executable file to complete; otherwise, specify False.

If you specified False in Flag, the script waits for the executable file to complete if it is still running when the script terminates. If you want to terminate the script without waiting for the executable file to complete, use the Exit command with Skip specified in Option. See Example 2.

Param1 to Param31

Specify the necessary parameters for executing the file specified in FileName. Write each parameter as a string or number or as a variable that stores this value.

In JP1/Script 06-00 and later versions, you can specify a one-dimensional array variable that stores all the required parameters.

For the parameter coding conventions, see 6.2 Rules for writing command lines.

If you specify one of the strings listed below as a parameter, the string is treated as the default when windows are displayed for an application executed by the Exec command. However, these parameters are not applicable to applications that control whether to hide, minimize, or maximize windows.

Parameter	Meaning
`/SPT:HIDE`	Hides the application window.
`/SPT:MIN`	Minimizes the application window to an icon.
`/SPT:MAX`	Maximizes the application window.

The parameters you specify in Param1 to Param31 are passed as command line parameters to the executable file. The strings /SPT:HIDE, /SPT:MIN, and /SPT:MAX are not passed as command line parameters.

Description

The Exec command executes a specified executable file.

If you specify True in Flag, the script waits for the called application to complete. If you specify False, the next command is processed without waiting for the application to complete.

The command returns True on successful execution, or False if an error occurs.

If you specify True in Flag and the execution result is True, the executable file's exit code is stored as a signed numeric in the _EXEC_RTN_ reserved variable. Nothing is stored in this reserved variable if you specify False in Flag or if the execution result is False.

If you specify False in Flag, the executable file ID is stored in the _EXEC_ID_ reserved variable.

Notes

Depending on the type of file called by the Exec command, the execution result may differ even with the same type of error. For example, the command returns False when a non-existent EXE file is called, but True when a non-existent SPT file is called.

To determine whether the Exec command was successful with Flag set to True, you must refer to the exit code stored in the _EXEC_RTN_ reserved variable in addition to the execution result. The fist example below illustrates the recommended procedure.
When you start an executable file that requires administrator permissions, the Windows User Account Control dialog box might appear. For details, see 1.8.2 Command behavior.
The work folder of the executable file called by the Exec command is the same as the work folder of the script file.
If double quotation marks (") are used in parameters, the values of the location variables that are passed to the executable file depend on whether the quotation marks are preceded by a space. See Example 3.

Example 1

' Call the script file "ABC.SPT".
rtn = Exec (_SCF_+"ABC.SPT", True)
rtnCode = _RTN_
 
' Determine the execution result.
If rtn = True Then
  If  _EXEC_RTN_ = 0  Then
       MessageBox ("Execution was successful.")
  Else
       MessageBox ("The script terminated abnormally. _
                    Exit code="_EXEC_RTN_)
       Exit  (_EXEC_RTN_)
  End
Else
    MessageBox ("The script terminated abnormally. _
                 Error code="+rtnCode)
    Exit (rtnCode)
End

Example 2

' Call "ABC.EXE" but do not wait for its termination.
rtn1 = Exec ("ABC.EXE", False)
    ...
' Terminate the script without waiting for ABC.EXE
' to terminate.
Exit (0, Skip)

Example 3

1. If the double quotation marks (") are not preceded by a space:

Parameter format

Exec ( "C:\Temp\Test.SPT", True, "ABC""XYZ""" )

Values set in the location variables

%0: C:\Temp\Test.SPT

%1: ABCXYZ

2. If the double quotation marks (") are preceded by a space:

Parameter format (: space)

Exec ( "C:\Temp\Test.SPT", True, "ABC [Figure] ""XYZ""" )

Values set in the location variables

%0: C:\Temp\Test.SPT

%1: ABC

%2: XYZ

JP1/Script version

Supported from JP1/Script 01-00.

To Page Top