EXECUTE Statement

The EXECUTE statement executes a specified TCL command from within the program, and then returns execution to the statement that follows the EXECUTE statement in the program.

Format

Parameter(s)

Optional Clauses

These option clauses are used to modify the way EXECUTE operates. As many as the user wishes may be used; the order of clauses is not required.

Description

The EXECUTE statement is a powerful statement for executing TCL commands from within an mvBASIC program.

The CAPTURING clause may be used to capture the output of the command into a string variable. The output is in the form of a dynamic array, with each line of output separated by attribute marks (CHAR(254)). This clause is particularly useful for programs that need to access information that is unavailable to the program directly (such as output from the SYSPROG commands WHAT and WHERE).

The RETURNING clause may be used to capture the error messages from the command into a string variable, which will be a string of error message numbers separated by spaces. If a Spooler hold file is created by the command, the hold file entry number is also entered into the returning variable.

The DATA statement can be extremely powerful when used with the EXECUTE statement. With the DATA statement, known responses can be stacked for subsequent EXECUTE commands that require operator input. Any leftover data on the stack is cleared upon return from the EXECUTE statement. See DATA Statement for more information.

EXECUTE may be used to run another mvBASIC program, which in turn may run a third mvBASIC program. Each of these institutes an execution level. The SYSTEM (103) function returns the current execution level. Up to 15 levels are supported.

In using the CAPTURING clause, be careful of TCL commands that clear the screen before displaying output. If the TCL command clears the screen, the screen-clearing character also appears in the capturing variable cvar. Other terminal manipulation characters might also appear. These characters may be stripped out of the string with CONVERT.

EXECUTE with Select-lists

The EXECUTE statement may be used to generate an external select-list that is used by a READNEXT statement in the program, providing an alternative to the SELECT statement. The SYSTEM(11) function determines whether an external select-list is present.

mvBase provides two methods for the way EXECUTE statement operates with select-lists. The default method is the traditional EXECUTE with select-lists functionality. Alternatively, the optional EXECUTE with select-lists functionality is available.

Traditional EXECUTE with Select-lists Functionality

When a select-list is produced by EXECUTE, the data stack is checked for input before control returns to the program. Any input in the stack is submitted to TCL as a command and executed with the select-list available to it.

Select-lists which have been returned to the mvBASIC program cannot be used by subsequent EXECUTE statements. If a list needs to be used both in and outside of the program, it should be saved with a SAVE-LIST command and retrieved by a GET-LIST command.

Optional EXECUTE with Select-lists Functionality

After loading the optional patch (refer to release notes for the appropriate patch), select-lists which have been returned to the mvBASIC program may be passed to subsequent EXECUTE statements for use.

Printing Output from EXECUTE

The output of EXECUTE is sent to the terminal unless otherwise specified with the P option to the command. If the P option is supported by the command, EXECUTE uses the default print file. If this file is already open, the output from EXECUTE is appended to it. The print file, however, is not closed upon completion of EXECUTE, but needs to be closed by the SP-CLOSE command from TCL, or by the PRINTER CLOSE statement in the program.

Examples

To select a list and then save it, the DATA and EXECUTE statements may be used together as follows:

After the SSELECT command is run, the data stack is examined and the SAVE-LIST command is executed before returning to the program. EXECUTE may be used later in the program to run the GET-LIST command and retrieve the select-list.

In the next example, the select-list generated by the first EXECUTE statement is passed to the subsequent EXECUTE statement and the SAVE-LIST command saves the list as NAMES:

In the next application the EXECUTE statement allows the operator to edit and compile another program until it successfully compiles. The RETURNING clause is used to determine if the compile was successful. The DCOUNT function supplies the number of errors which were returned.

The FIELD function extracts the last error. If the last error is "B100" (COMPILATION ABORTED; NO OBJECT CODE PRODUCED), then the program is edited and compiled again; otherwise, the program is executed.

In the next example the operator would like to know if a certain user is logged on. The EXECUTE statement executes "WHO A" and then searches through each line for the other user. The FIELD function is used to determine if the other user is logged on, and then the FIELD function is used again to isolate the process number. Thus all processes the other user is logged on to are reported.

Note in the next example that the CONVERT statement is used to remove the clear-screen character from the list of users.

See Also

Statement and Function Reference