Topic group Related topics

Runs a program or function.

Syntax

DO <filename> | ? | <filename skeleton> |
 <function name>
[WITH <parameter list>]

<filename> | ? | <filename skeleton>

The program file to execute. The ? and options display a dialog box from which you can select a file. If you specify a file without including its path, in the IDE, dBASE Plus looks for the file in the current directory, then in the search path in search order. See "Search path and order" later in this section for more information. Whether or not a path or source alias is included, when executing an application .exe, dBASE follows the "Runtime search path" described below.

If you specify a file without including its extension, dBASE Plus assumes a .PRO extension (a compiled object file). If dBASE Plus can't find a .PRO file and its running within the IDE, it looks for a .PRG file (a source file), which, if found, it compiles. By default, dBASE Plus creates the .PRO in the same directory as the .PRG, which might not be the current directory.

<function name>

The function name in an open program file to execute. The function must be in the program file containing the DO command that calls it, or in a separate open file on the search path. The search path is described later in this section.

WITH <parameter list>

Specifies memory variable values, field values, or any other valid expressions to pass as parameters to the program or function. See the description of PARAMETERS for information on parameter passing.

Description

Use DO to run program files from the Command window or to run other programs from a program. If you enter DO in the Command window, control returns to the Command window when the program or function ends. If you use DO in a program to execute another program, control returns to the program line following the DO statement when the program ends.

Although you may use DO to execute functions, common style dictates the use of the call operator (the parentheses) when calling functions, and the DO command when running a program file. The DO command supports the use of a file path and extension, and the ? and <filename skeleton> options. The call operator supports calling a function by name only. In the not-recommended situation where you have a program file that has the same name as a function loaded into memory, the DO command will execute the program file, and the call operator will executed the loaded function. Other than these differences, the two calling methods behave the same, and follow the same search rules described later in this section.

You may nest routines; that is, one routine may call another routine, which may call another routine, and so on. This series of routines, in the order in which they are called, is referred to as the call chain.

When dBASE Plus executes or loads a program file, it will automatically compile the program file into object code when either:

There is no object code file, or

SET DEVELOPMENT is ON, and program file is newer than the object code file (the source code file’s last update date and time is later than the object code file’s)

When dBASE Plus encounters a function call in a program file, it looks in that file for a FUNCTION or PROCEDURE of the specified name. If the current program file contains a FUNCTION and a PROCEDURE with the same name, dBASE Plus executes the first one declared. If dBASE Plus doesn't find a FUNCTION or PROCEDURE definition of the specified name in the same program file, it looks for a program file, FUNCTION, or PROCEDURE of the specified name on the search path in search order.

Search path and order

If the name you specify with DO doesn't include a path or a file-name extension, it can be a file, FUNCTION, or PROCEDURE name. To resolve the ambiguity, dBASE Plus searches for the name in specific places (the search path) in a specific order (the search order) and runs the first program or function of the specified name that it finds. The search path and order dBASE Plus uses within the IDE is as follows:

 

IDE Search Order

  1. The executing program's object file (.PRO, .WFO, CO, etc)

  2. Other open object files (.PRO, .WFO, .CO, etc) in the call chain, in most recently opened order

  3. The file specified by SYSPROC = (in PLUS.ini)

  4. Any files opened with SET PROCEDURE, SET PROCEDURE...ADDITIVE, or SET LIBRARY statements, in the order in which they were opened

  5. The object file (.PRO, .WFO, .CO, etc.) with the specified name in the search path

  6. The program file (.PRG, .WFM, .CC, etc.) with the specified name in the search path, which dBASE Plus automatically compiles.

NOTE: The search path is controlled with the SET PATH command.

 

Runtime Search Order

When executing a dBASE Plus application .exe, the dBASE Runtime uses a modified search order (compared with "IDE Search Order" above) in order to handle the various ways an application can be built and deployed. Object files may be built into the application .exe file and/or deployed into one or more locations to be loaded using the DEO (Dynamic External Objects) mechanism.

If a path is specified in a DO command, the dBASE Runtime will ignore the path when searching for the specified file's object file. This applies no matter how the path is specified, whether explicitly, or via a source code alias, or by constructing a path and concatenating it onto the filename. Further note that source code aliases are not normally defined in an application's .ini file and, therefore, cannot be resolved when executing a deployed application .exe.

If a file extension is specified in a DO command, and the extension is for a dBASE source code file (.PRG,.WFM, .CC, etc.) dBASE will substitute the corresponding object file extension. For example, .PRG will be changed to .PRO, .WFM will be changed to .WFO, .CC will be changed to .CO, and so on.

The _app object's allowDEOEXEOverride property can be used to modify, at runtime, the object file search order used to either allow or disallow object files built into the application .exe from being overridden or not by external object files of the same name. This can be done either program wide by setting allowDEOExeOverride once during program startup, or it can be changed on a case by case basis where needed.

The first part of the search order is the same as in the IDE search order and is as follows:

  1. The executing program's object file (.PRO, .WFO, .CO, etc.)

  2. Other open object files (.PRO, .WFO, .CO, etc.) in the call chain, in most recently opened order

  3. The file specified by SYSPROC = (in application's .ini file)

  4. Any files opened with SET PROCEDURE, SET PROCEDURE...ADDITIVE, or SET LIBRARY statements, in the order in which they were opened

  5. The object file (.PRO, .WFO, .CO, etc.) with the specified name in the runtime search path (See below).

(Note that the runtime cannot compile any source files so the next step in the IDE case, compiling a source file automatically, does not apply to the runtime case)

 

The runtime search path is as follows:

 

When _app.allowDEOExeOverride = true (the default)

  1. "home" folder; location of the executable

  2. DEO paths found in the .ini file

  3. Paths set via set path

  4. Inside the application's .exe file

 

When _app.allowDEOExeOverride = false
  

  1. Inside the application's .exe file

  2. "home" folder; location of the executable

  3. DEO paths found in the .ini file

  4. Paths set via set path.