Purpose
Identifies the name and parameter list of a sub procedure.
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 Sub sub_proc
[ ( [ ByVal ] parameter [ , parameter... ] As var_type [ , ... ] ) ] sub_proc is the name of a sub procedure.
parameter is the name of a sub procedure parameter.
var_type is a standard data type or a custom Type.
Syntax 2 (external routines in Windows DLLs)
Declare Sub sub_proc Lib "file_name" [WideChars] [ Alias "sub_alias" ]
[ ( [ ByVal ] parameter [ , parameter... ] As var_type [ , ... ] ) ] sub_proc is the name by which an external routine will be called.
file_name is a string; the DLL name.
WideChars is a flag, which if specified indicates that the string parameters to external windows DLL routine should be treated as wide strings, otherwise the string parameters are treated as MultiByte strings in current system charset.
sub_alias is an external routine's original name.
parameter is the name of a sub procedure parameter.
var_type is a data type: with Windows DLLs, this can be a standard variable type or a custom Type.
Description
The Declare Sub statement establishes a sub procedure's name and parameter list. Typically, each Declare Sub statement corresponds to an actual sub procedure which appears later in the same program.
A MapBasic program can use a Sub...End Sub statement to create a procedure. Every procedure defined in this manner must be preceded by a Declare Sub statement. For more information on creating procedures, see Sub...End Sub statement.
Parameters passed to a procedure are passed by reference unless you include the optional ByVal keyword.
Calling External Routines
Using Syntax 2 (above), you can use a Declare Sub statement to define an external routine. An external routine is a routine that was written in another language (for example, C or Pascal), and is stored in a separate file. Once you have declared an external routine, your program can call the external routine as if it were a conventional MapBasic procedure.
If the Declare Sub statement declares an external routine, the file_name parameter must specify the name of the file containing the routine. The file must be present at run-time.
Every external routine has an explicitly assigned name. Ordinarily, the Declare Sub statement's sub_proc parameter matches the explicit routine name from the external file. The Declare Sub statement can include an Alias clause, which lets you call the external routine by whatever name you choose. The Alias clause lets you override an external routine's explicit name, in situations where the explicit name conflicts with the name of a standard MapBasic function.
If the Declare Sub statement includes a WideChars clause then all the string parameters to the external routine are treated as wide strings. Use only wide string format for parameters when including the WideChars clause.
If the Declare Sub statement includes an Alias clause, the sub_alias parameter must match the external routine's original name, and the sub_proc parameter indicates the name by which MapBasic will call the routine. 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.
Example
Declare Sub Main
Declare Sub Cube(ByVal original As Float, cubed As Float)
Sub Main
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 Sub
Sub Cube (ByVal original As Float, cubed As Float)
'
' Cube the "original" parameter value, and store
' the result in the "cubed" parameter.
'
cubed = original ^ 3
End SubSee Also:
Call statement, Sub...End Sub statement