[next] [previous] [contents]

  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)