Declare Function statement - MapBasic - 2023

Purpose

Defines the name and parameter list of a function.

Restrictions

This statement may not be issued from the MapBasic window.

Accessing external functions (using syntax 2) is platform-dependent. DLL files may only be accessed by applications running on Windows.

Syntax 1

Declare Function fname 
	( [ [ ByVal ] parameter [ , parameter... ] As var_type ]
	 [ , [ ByVal ] parameter [ , parameter... ] As var_type... ] ) 
	As return_type

fname is the name of the function.

parameter is the name of a parameter to the function.

var_type is a variable type, such as integer; arrays and custom Types are allowed.

return_type is a standard scalar variable type; arrays and custom Types are not allowed.

Syntax 2 (external routines in Windows DLLs)

Declare Function fname 
	Lib "file_name" [WideChars] [ Alias "function_alias" ] 
	( [ [ ByVal ] parameter [ , parameter... ] As var_type ]
		[ , [ ByVal ] parameter [ , parameter... ] As var_type... ] ) 
	As return_type

fname is the name by which a function will be called.

file_name is the name of a Windows DLL file.

WideChars is a flag, which if specified indicates that the string parameters and the string return type from external windows DLL functions should be treated as wide strings, otherwise the string parameters and string return type are treated as MultiByte strings in current system charset.

function_alias is the original name of the external function.

parameter is the name of a parameter to the function.

var_type is a data type: with Windows DLLs, this can be a standard variable type or a custom Type.

return_type is a standard scalar variable type.

Description

The Declare Function statement pre-declares a user-defined MapBasic function or an external function.

A MapBasic program can use a Function...End Function statement to create a custom function. Every function defined in this fashion must be preceded by a Declare Function statement. For more information on creating custom functions, see Function...End Function statement.

Parameters passed to a function are passed by reference unless you include the optional ByVal keyword. For information on the differences between by-reference and by-value parameters, see the MapBasic User Guide.

Calling External Functions

Using Syntax 2 (above), you can use a Declare Function statement to define an external function. An external function is a function that was written in another language (for example, C or Pascal), and is stored in a separate file. Once you have declared an external function, your program can call the external function as if it were a conventional MapBasic function.

If the Declare Function statement declares an external function, the file_name parameter must specify the name of the file containing the external function. The external file must be present at run-time.

Every external function has an explicitly assigned name. Ordinarily, the Declare Function statement's fname parameter matches the explicit routine name from the external file. Alternately, the Declare Function statement can include an Alias clause, which lets you call the external function by whatever name you choose. The Alias clause lets you override an external function's explicit name, in situations where the explicit name conflicts with the name of a standard MapBasic function.

If the Declare Function statement includes a WideChars clause then all the string parameters and the string return type from external windows DLL functions are treated as wide strings. Use only wide string format for parameters when including the WideChars clause.

If the Declare Function statement includes an Alias clause, the function_alias parameter must match the external function's original name, and the fname parameter indicates the name by which MapBasic will call the routine.

Restrictions on Windows DLL parameters

You can pass a custom variable type as a parameter to a DLL. The custom type may be defined with the optional Align[n] keyword in the Type Statement to match the target DLL "structure packing". For information on custom variable types, see Type statement. See the MapBasic User Guide for more information.

Example

The following example defines a custom function, CubeRoot, which returns the cube root of a number (the number raised to the one-third power).

Declare Sub Main 
Declare Function CubeRoot(ByVal x As Float) As Float
Sub Main 
	Note Str$( CubeRoot(23) )
End Sub 
Function CubeRoot(ByVal x As Float) As Float
	CubeRoot = x ^ (1 / 3) 
End Function

See Also:

Declare Sub statement, Function...End Function statement