20.2.3 Calling the Routine
Once you have declared an external routine, you can invoke
it. To invoke a procedure, you use the CALL statement. To
invoke a function, you use the function name in an expres-
sion. You must specify the name of the routine being invoked
and all parameters required for that routine. Make sure the
data types and passing mechanisms for the actual param-
eters you are passing match those you declared earlier, and
those declared in the routine.
If you do not want to specify a value for a required param-
eter, you can pass a null argument by inserting a comma
as a placeholder in the argument list. If you are passing a
parameter using a mechanism other than the default pass-
ing mechanism for that data type, you must specify the
passing mechanism in the CALL statement or the function
invocation.
The following example shows you how to call the external
subprogram allocate declared in Section 20.2.2. When allo-
cate is called, it is called as a procedure. The first parameter
must always be a valid LONG INTEGER value; the second
and third parameters can be of any valid BASIC data type.
EXTERNAL SUB allocate(LONG, ANY,)
.
.
.
CALL allocate (entity%, a$, 1%)
This next example shows you how to call the Run-
Time Library routine LIB$LOOKUP_KEY declared in
Section 20.2.2. When the routine LIB$LOOKUP_KEY is
called, it is invoked as a function. The first two parameters
are required; all remaining parameters are optional.
EXAMPLE: Click to display example.
Note that if the actual parameter's data type in the CALL
statement does not match that specified in the EXTERNAL
statement, BASIC reports the compile-time informational
message ``Mode for parameter of routine changed to match
declaration''. This tells you that BASIC has made a local copy
of the value of the parameter, and that this local copy has the
data type specified in the EXTERNAL declaration. BASIC
warns you of this because the change means that the param-
eter can no longer be modified by the subprogram. If BASIC
cannot convert the data type, BASIC signals the error ``Mode
for parameter of routine not as declared''.
The routine being called receives control, executes, and then
returns control to the calling routine at the next statement
after the CALL statement or function invocation.
BASIC provides the built-in function LOC to allow you to
access the address of a named external function. This is es-
pecially useful when passing the address of a callback or
AST routine to an external subprogram. In the following ex-
ample, the address of the function compare is passed to the
subprogram come_back_now using the LOC function:
EXTERNAL LONG FUNCTION compare (LONG, LONG)
EXTERNAL SUB come_back_now (LONG BY VALUE)
CALL come_back_now (LOC(compare) BY VALUE)