basic.execute

'pushes a level' temporarily and performs any valid TCL expression, then continues execution of the FlashBASIC or Pick/BASIC program.

The TCL expression may be any valid TCL command, including Access sentences, verbs, macros, menus, PROC's, or other cataloged Pick/BASIC programs.

The results of the TCL command may be assigned to a variable for later processing by using the optional 'capturing' clause.

Input may be passed to the TCL statements using the 'data' statement prior to the 'execute' statement. After the 'execute' statement completes, the data queue, and any external 'active' lists, are reset. Multiple 'data' statements may be passed when they are separated by attribute marks.

An alternate method of stacking data is using 'execute' in the form:

execute 'TCL.command' : char(254) : 'input data'

The optional 'returning' clause directs any error message item-id(s) generated as a result of the 'execute' statement into a variable. Each error message item-id is separated by a space.

In the 'capturing' clause, Carriage return/linefeed combinations are converted to attribute marks, which allows the variable to be treated like a dynamic array. Clear screens and form-feeds are converted to nulls.

Certain Pick/BASIC statements, like 'input @' and 'crt', don't put anything into the capturing stream.

The 'capturing on' and 'capturing off' statements are provided to enable or disable the output from the 'capturing' portion of the 'execute' statement.

An active list that is created by the executed command is passed back to the program. The list may be used by the 'readnext' statement or it may be assigned to a specific variable using the 'select to' statement for later use with a 'readnext' 'from' statement.

An active list generated by a TCL statement may be passed to a another TCL statement executed from a Pick/BASIC program.

Control does not return from an execute that issues an 'off' command.

The 'to' and 'logto' verbs push a level, go to the new account, and return to the next statement in the Pick/BASIC program on the original account when complete.

The following verbs may alter the program environment when returning to the next program statement: Spooler verbs, tape control verbs, 'debug', 'charges', 'term', and 'tabs'.

Output printed from indexes and Pick/BASIC calls which are active during a file update are captured.

Each level of 'execute' builds a new process workspace area. As the number of levels increase, so do disk space requirements. The maximum number of levels in R83 is 5 and in AP is 16.

On release 6.2.0 and higher, a second version of execute is available which provides more control over data and select list handling. This is shown in the second line of the syntax. This additional syntax requires that the extended options be set. See '$options' for more information.

The 'stacking' clause allows the user to stack data for the TCL statement. This clause is identical to using a 'data' statement before the 'execute'.

The 'passlist' clause creates a copy of the select list and passes it to the TCL command. Note that select lists which are 'internally' linked to a file will be expanded to a standard list of item-id's so that the upper level may access the list.

The 'rtnlist' clause provides essentially the same functionality as a 'select to list.variable' done after the execute. The only difference is that rtnlist does not drop into the BASIC debugger if an external list is not available. Instead, it returns a null string in this case.