The execute statement temporarily pushes a level and performs any valid TCL expression, then continues execution of the FlashBASIC or BASIC program.
Syntax
execute tcl.exp {returning var} {capturing var} execute tcl.exp {[stacking|,//in.<] exp} {[passlist|,//select.<] list.var} {[rtnlist|,//select.>] list.var } {[returning|setting] var} {[capturing|,,//out.>] var} |
Description
The tcl.exp can be any valid TCL command, including AQL sentences, commands, macros, menus, Procs, or other cataloged FlashBASIC or BASIC programs.
The results of the TCL command can be assigned to a variable for later processing by using the optional capturing clause.
Input can 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 can 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" |
If exec-stacking-on is enabled, and you use attributes to stack multiple commands with the execute statement, then you must use value marks to separate the data. For example, note the use of char(253):
execute "tcl.command" : char(253) : "input data" |
The optional returning clause directs any error message item-IDs generated as a result of the execute statement into the specified variable. Each error message item-ID is separated by a space.
In the capturing clause, CR/LF 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 or BASIC statements, such as input @, do not put anything into the capturing stream.
The capturing on and capturing off statements are provided to enable or disable the output from the capturing clause of the execute statement.
An active list that is created by the executed statement is passed back to the program. The list can be used by the readnext statement or it can 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 can be passed to a another TCL statement executed from a FlashBASIC or BASIC program.
WARNING |
If a subsequent execute statement is run (that does not directly process the items selected in the active list), the active list will be discarded. |
Control does not return from an execute that issues an TCL off command.
The TCL to and logto commands push a level, go to the new account, and return to the next statement in the FlashBASIC or BASIC program on the original account when complete.
The commands below can alter the program environment when returning to the next program statement: spooler commands, tape control commands, debug, charges, term, and tabs.
Output printed from indexes and FlashBASIC or BASIC calls that are active during a file update are captured.
Each level of execute builds a new process workspace area. As the number of levels increase, disk space requirements increase. The maximum number of levels is 16.
The second version of the execute statement provides more control over data and select list handling. The additional syntax in this version requires that the extended options be set.
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 that are internally linked to a file are expanded to a standard list of item-IDs to allow the upper level access to the list.
The rtnlist clause provides essentially the same functionality as a select to list.var done after the execute. The only difference is that rtnlist does not drop into the FlashBASIC or BASIC debugger if an external list is not available. Instead, it returns a null string in this case.
Example(s)
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/02"\ execute "sselect staff by hire.date by name" execute "save-list staff.list" execute "get-list staff.list" execute "list staff name hire.date" |
See Also