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}

       {PASSLIST {src.list }}

       {RTNLIST tgt.list }

       {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. For compatibility with other multivalue environments, the PASSLIST clause is ignored if src.list is omitted.

                       

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 at the highest command processor level that took its command input from the keyboard or PHANTOMed paragraph. 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.

 

The PASSLIST clause passes the list in the named select list variable into the executed command as list 0.

 

The RTNLIST clause returns the content of the default select list in the named variable, removing the active numbered select list.

 

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.

 

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

 

 

Example

 

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.