# execute statement

The execute statement temporarily pushes a level and performs any
 valid TCL expression, and 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}
```

 Spaces are also allowed between // and
 select.< or select.> in the
 execute
 statement:
```
 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}
```

The following optional clauses can be in any order:

- {[capturing|,,//out.>] var}

- {[passlist|,//select.] list.var}

- {[stacking|,//in.<] exp}

## 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 following 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
 allow 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 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 a TCL off
 command.

 Note: The to and logto go to the new account, and
 then return to the original account before executing the next line in the FlashBASIC
 or BASIC program. To remain in the logged-to account, use the (f
 option or the (k option on the to and
 logto commands.

 The following commands can alter the program environment when returning to the next
 program statement:

- spooler commands

- tape control commands

- debug command

- charges command

- term command

- tabs command

 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 clause does not drop into the FlashBASIC or BASIC
 debugger if an external list is not available. Instead, it returns a null
 string.

## 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

- [capturing statement](https://d3codex.com/pickbasic-flashbasic/capturing-statement/)
- [exec-stacking-on macro](https://d3codex.com/tcl/exec-stacking-on-macro/)
- [exec-stacking-off macro](https://d3codex.com/tcl/exec-stacking-off-macro/)

---
Source: https://d3codex.com/pickbasic-flashbasic/execute-statement/ - part of the D3Codex reference.