| BREAK ON | Index Level | CAPTURING |
| Syntax |
CALL cataloged.program.name{(argument{,argument...})}
CALL @program.name.variable{(argument{,argument...})} CALL "file.reference program.name"{(argument{,argument...})} |
| Category | BASIC |
| Type | Statement |
| Description |
transfers control to an external FlashBASIC subroutine and optionally passes a list of arguments to it.
Arguments must be separated by commas (,). When passing arguments, the same number must occur in the "CALL" statement as are declared in the "SUBROUTINE" statement, which must occur as the first executable line of the external subroutine. There is a maximum of about 200 arguments. The subroutine can return values to the calling program in variable arguments. The external subroutine must ultimately execute a "RETURN" statement to continue program execution at the statement immediately following the "CALL" statement. Subroutines which do not return will simply terminate execution. The "CALL @", or "indirect call" form allows the statement to use the subroutine name assigned to a specific variable. Called subroutines must be compiled and cataloged separately from the calling program. The arguments passed between (to and from) the program and subroutine are not label-sensitive, but are order-sensitive. The arguments listed in the "SUBROUTINE" statement and the arguments listed in the "CALL" statement may be different. The subroutine receives the results of arguments in the order that they are specified in the argument list. Variable arguments are passed to the subroutine at "CALL" time and from the subroutine at "RETURN" time. Arrays may be passed between programs and subroutines. The array in the program and called subroutine must contain the same number of elements. If dimensioned arrays are used, the arrays should be dimensioned exactly the same in both the program and subroutine (see the "DIM" statement). Alternately, a "DIM" statement may be specified without the actual number of elements. The array is properly initialized at run-time. Arguments listed in both the "CALL" and "SUBROUTINE" statements should not be duplicated in the argument lists. Arguments that are also defined as "COMMON" variables in both calling programs and subroutine programs should not be used in argument lists since the data is already accessible through the common allocations. Violation of these rules can result in unpredictable values being passed between the programs. On release 6.1.0 and above, it is possible to specify the file path name followed by a space followed by the actual subroutine name. To do this, the file path and program name can be passed via a variable to an indirect call, or the string can be enclosed in quotes and embedded directly into the program text. Specifying a direct file reference and program name eliminates the need for cataloging subroutines when an application is used from other accounts. On release 6.1.0 and above, if the subroutine is not catalog'ed, then BASIC will attempt to locate the subroutine in the current program's dictionary. This eliminates the need to catalog most subroutines. |
| Options | |
| See Also | statements & functions SUBROUTINE DIM PRECISION TCL ENTER CHAIN date.iconv RETURN u31a2 COMMON FlashBASIC Differences |
| Example |
direct call:
call process.lines(id,order.item(1)) -or- call "process.lines"(id,order.item(1)) With or without quotes, this example still calls the "process.lines" subroutine. indirect call: program.variable = "process.lines" call @program.variable(id,order.item(1)) This example calls the subroutine name held as a string in the variable "program.variable". indirect call with full path name program.variable = "dm,bp, process.lines" call @program.variable(id,order.item(1)) |
| Warnings |
The initial overhead for a external subroutine call requires the program name be found in the master dictionary. This item points to the object code file. The object pointer is read next and it points to the actual object code.
Dynamic array elements passed to subroutines are treated as function results and are therefore not updated after the call returns. |
| Compatibility | D3 7.0 AP AP 6.1 R83 |
| BREAK ON | Index Level | CAPTURING |