| EXCHANGE | Index Level | EXECUTE (AP/DOS) |
| Syntax |
EXECUTE tcl.expression {RETURNING variable} {CAPTURING variable}
EXECUTE tcl.expression {[STACKING | ,//in.<] expression} {[passlist | ,//select.<] list.variable} {[rtnlist | ,//select.>] list.variable } {[RETURNING | SETTING] variable} {[CAPTURING | ,,//out.>] variable} |
| Category | BASIC |
| Type | Statement |
| Description |
"pushes a level" temporarily and performs any valid TCL expression, then continues execution of the FlashBASIC program.
The TCL expression may be any valid TCL command, including Access sentences, verbs, macros, menus, PROC's, or other cataloged FlashBASIC 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 FlashBASIC 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 FlashBASIC 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 FlashBASIC 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 FlashBASIC 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; in D3 it is 16. On release 7.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. |
| Options | |
| See Also | DEBUG :taskinit (R83) CAPTURING term statements & functions charges EXECUTE (D3/Unix) ENTER active list EXECUTE (AP/DOS) READNEXT CHAIN TCL RETURNING tabs SELECT CAPTURING capture-off SYSTEM capture-on FlashBASIC Differences Access DATA esc-level BEGIN WORK PERFORM |
| Example |
execute "sort staff by name name total salary (p)"
data "(qfile" execute "copy newac *" execute "listu" capturing output execute "sselect invoices" returning errnum execute \sort orders with date > "1/1/92"\ execute "sselect staff by hire.date by name" execute "save-list staff.list" execute "get-list staff.list" execute "list staff name hire.date" |
| Warnings | Capturing output printed from indexes and FlashBASIC calls which are active during a file update is new in release 6.1. |
| Compatibility | D3 7.0 R83 AP AP 6.1 D3 7.0 |
| EXCHANGE | Index Level | EXECUTE (AP/DOS) |