Call statement - MapBasic - 2023

Purpose

Calls a sub procedure or an external routine (DLL, XCMD).

Restrictions

You cannot issue a Call statement through the MapBasic window.

Syntax

Call subproc [ ( [ parameter ] [ , ... ] ) ]

subproc is the name of a sub procedure.

parameter is a parameter expression to pass to the sub procedure.

Description

The Call statement calls a procedure. The procedure is usually a conventional MapBasic sub procedure (defined through the Sub...End Sub statement). Alternately, a program running under MapInfo Pro can call a Windows Dynamic Link Library (DLL) routine through the Call statement.

When a Call statement calls a conventional MapBasic procedure, MapBasic begins executing the statements in the specified sub procedure, and continues until encountering an End Sub or an Exit Sub statement. At that time, MapBasic returns from the sub procedure, then executes the statements following the Call statement. The Call statement can only access sub procedures which are part of the same application.

A MapBasic program must issue a Declare Sub statement to define the name and parameter list of any procedure which is to be called. This requirement is independent of whether the procedure is a conventional MapBasic Sub procedure, a DLL procedure or an XCMD.

Parameter Passing

Sub procedures may be defined with no parameters. If a particular sub procedure has no parameters, then calls to that sub procedure may appear in either of the following forms:

Call subroutine

or

Call subroutine()

By default, each sub procedure parameter is defined "by reference." When a sub procedure has a by-reference parameter, the caller must specify the name of a variable to pass as the parameter.

If the procedure then alters the contents of the by-reference parameter, the caller's variable is automatically updated to reflect the change. This allows the caller to examine the results returned by the sub procedure.

Alternately, any or all sub procedure parameters may be passed "by value" if the keyword ByVal appears before the parameter name in the Sub and Declare Sub declarations. When a parameter is passed by value, the sub procedure receives a copy of the value of the parameter expression; thus, the caller can pass any expression, rather than having to pass the name of a variable.

A sub procedure can take an entire array as a single parameter. When a sub procedure expects an array as a parameter, the caller should specify the name of an array variable, without parentheses.

Example

In the following example, the sub procedure Cube cubes a number (raises the number to the power of three), and returns the result. The sub procedure takes two parameters; the first parameter contains the number to be cubed, and the second parameter passes the results back to the caller.

Declare Sub Cube(ByVal original As Float, cubed As Float)
	Dim x, result As Float
	Call Cube( 2, result)
	' result now contains the value: 8 (2 x 2 x 2) 
	x = 1
	Call Cube( x + 2, result)
	' result now contains the value: 27 (3 x 3 x 3)
End Program 
Sub Cube (ByVal original As Float, cubed As Float)
	' Cube the "original" parameter, and store
	' the result in the "cubed" parameter. 
	cubed = original ^ 3
End Sub

See Also:

Declare Sub statement, Exit Sub statement, Global statement, Sub...End Sub statement