EXECUTE

EXECUTE, PERFORM

Top  Previous  Next

 

The EXECUTE statement enables a QMBasic program to execute any command. The synonym PERFORM can be used in place of EXECUTE.

 

 

Format

 

EXECUTE expr {TRAPPING ABORTS}

{CAPTURING var}
{NO.TTY}
{PASSLIST {src.list }}
{RTNLIST tgt.list }
{SILENT}
{STACKLIST}
{SETTING status.var}  or  {RETURNING status.var}

 

where

 

exprevaluates to the command(s) to be executed. Multiple commands are separated by field marks.

 

varis a variable to receive captured output.

 

src.listis a select list variable holding a list to be passed into the executed command as list 0.

                 

tgt.listis a variable to receive a returned select list. This variable may be used in a subsequent READNEXT to extract  items from the list.

 

status.varis a variable to receive the value of @SYSTEM.RETURN.CODE after the command is executed.

 

 

The EXECUTE statement creates a new command level by starting a new version of the command processor and passing it the command line to be executed. On completion of the command, the command processor returns control to the calling program.

 

The value in expr may contain several commands delimited by field marks. These will be processed as a paragraph and may include DATA and LOOP constructs, etc.

 

An abort occurring in the command(s) processed by the EXECUTE statement is normally trapped by the command processor. The TRAPPING ABORTS qualifier to the EXECUTE statement causes aborts to return to the program issuing the EXECUTE without execution of the optional ON.ABORT paragraph. The @ABORT.CODE variable may be used to determine whether the command caused an abort to occur. This variable is initially zero and is reset to zero only by the EXECUTE statement.

 

The CAPTURING clause captures output that would otherwise have gone to the terminal or phantom log file, saving it in the named variable with field marks in place of newlines. Alternatively, all command output can be suppressed by use of the SILENT clause which is equivalent to using HUSH ON before the executed command and restoring the previous hush state afterwards.

 

The NO.TTY clause suppresses all @() function expansion in the executed command. Used with CAPTURING, this ensures that no control sequences will appear in the captured data.

 

The PASSLIST clause passes the list in the src.list select list variable into the executed command as list 0. If src.list is omitted, the default select list is passed to the executed command. If neither form of PASSLIST is present, the behaviour depends on the setting of the EXECUTE.CLEARLIST option of the $MODE compiler directive. If this mode is not set, the default select list is passed into the executed command. If the mode is set, the default select list is cleared prior to execution of the command.

 

The RTNLIST clause returns the named variable as the content of the default select list after execution of the command.

 

The STACKLIST option saves the current state of the default select list (list 0) before executing the command and restores the list on return to the program, thus allowing the executed command to use the default select list internally. This option cannot be used with either PASSLIST or RTNLIST.

 

The SETTING or RETURNING clause copies the value of @SYSTEM.RETURN.CODE to the named variable after the command has been executed.

 

The unnamed common area is saved by the EXECUTE statement and the new command level may define a new structure for this area. On return from the EXECUTE statement, the original unnamed common area is restored. Named common areas are not affected by the EXECUTE statement. Except as influenced by the PASSLIST and RTNLIST options described above, the numbered select lists are carried into the executed command and any changes will be visible on return.

 

Application designers should carefully consider the possible impact of EXECUTE inside a transaction.

 

The value of the STATUS() function after an EXECUTE is undefined.

 

If the executed command directly or indirectly changes account by performing a LOGTO, the process will continue to run in the new account on return from the EXECUTE. Setting the STACKED.ACCOUNT mode of the OPTION command causes the system to revert to the previous account on completion of the EXECUTE.

 

 

Examples

 

EXECUTE "LIST STOCK.FILE ITEMS QUANTITY"

 

This statement performs the LIST command from within the calling program. Control is returned to the program once the LIST command is complete.

 

 

EXECUTE "SELECT CLIENTS WITH BALANCE > 1000" : @FM : RUN PAYMENT.LETTER

 

This statement executes two related commands in a single step.