Declare Statement

Description

Used at module level to declare references to external procedures in a dynamic-link library (DLL).

Syntax 1

[Public | Private] Declare Sub name Lib "libname" [Alias "aliasname"] [([arglist])]

Syntax 2

[Public | Private] Declare Function name Lib "libname" [Alias "aliasname"]
ú[([arglist])] [As type]

The Declare statement syntax has these parts

Part	Description

Public	Optional. Used to declare procedures that are available to all other procedures in all modules.
Private	Optional. Used to declare procedures that are available only within the module where the declaration is made.
Sub	Optional (either Sub or Function must appear). Indicates that the procedure doesn't return a value.
Function	Optional (either Sub or Function must appear). Indicates that the procedure returns a value that can be used in an expression.
name	Required. Any valid procedure name. Note that DLL entry points are case sensitive.
Lib	Required. Indicates that a DLL or code resource contains the procedure being declared. The Lib clause is required for all declarations.
libname	Required. Name of the DLL or code resource that contains the declared procedure.
Alias	Optional. Indicates that the procedure being called has another name in the DLL. This is useful when the external procedure name is the same as a keyword. You can also use Alias when a DLL procedure has the same name as a public variable, constant, or any other procedure in the same scope. Alias is also useful if any characters in the DLL procedure name aren't allowed by the DLL naming convention.
aliasname	Optional. Name of the procedure in the DLL or code resource. If the first character is not a number sign (#), aliasname is the name of the procedure's entry point in the DLL. If (#) is the first character, all characters that follow must indicate the ordinal number of the procedure's entry point.
arglist	Optional. List of variables representing arguments that are passed to the procedure when it is called.

(continue)

Part	Description

type	Optional. Data type of the value returned by a Function procedure; may be Byte, Boolean, Integer, Long, Currency, Single, Double, Decimal (not currently supported), Date, String (variable length only), or Variant, a user-defined type, or an object type.

The arglist argument has the following syntax and parts:

[Optional] [ByVal | ByRef] [ParamArray] varname[( )] [As type]

Part	Description

Optional	Optional. Indicates that an argument is not required. If used, all subsequent arguments in arglist must also be optional and declared using the Optional keyword. Optional can't be used for any argument if ParamArray is used.
ByVal	Optional. Indicates that the argument is passed by value.
ByRef	Indicates that the argument is passed by reference. ByRef is the default in Visual Basic.
ParamArray	Optional. Used only as the last argument in arglist to indicate that the final argument is an Optional array of Variant elements. The ParamArray keyword allows you to provide an arbitrary number of arguments. The ParamArray keyword can't be used with ByVal, ByRef, or Optional.
varname	Required. Name of the variable representing the argument being passed to the procedure; follows standard variable naming conventions.
( )	Required for array variables. Indicates that varname is an array.
type	Optional. Data type of the argument passed to the procedure; may be Byte, Boolean, Integer, Long, Currency, Single, Double, Decimal (not currently supported), Date, String (variable length only), Object, Variant, a user-defined type, or an object type.

Remarks

For Function procedures, the data type of the procedure determines the data type it returns. You can use an As clause following arglist to specify the return type of the function. Within arglist, you can use an As clause to specify the data type of any of the arguments passed to the procedure. In addition to specifying any of the standard data types, you can specify As Any in arglist to inhibit type checking and allow any data type to be passed to the procedure.

Empty parentheses indicate that the Sub or Function procedure has no arguments and that Visual Basic should ensure that none are passed. In the following example, First takes no arguments. If you use arguments in a call to First, an error occurs:

Declare Sub First Lib "MyLib" ()

If you include an argument list, the number and type of arguments are checked each time the procedure is called. In the following example, First takes one Long argument:

Declare Sub First Lib "MyLib" (X As Long)

Note You can't have fixed-length strings in the argument list of a Declare statement; only variable-length strings can be passed to procedures. Fixed-length strings can appear as procedure arguments, but they are converted to variable-length strings before being passed.

Note The vbNullString constant is used when calling external procedures, where the external procedure requires a string whose value is zero. This is not the same thing as a zero-length string (" ").

See Also

Call statement, Function statement, LastDLLError property, Sub statement.

Specifics (Macintosh)

On the Power, the Declare syntax is the same as in Windows, except that the CDecl keyword can be used to indicate that the procedure uses C language argument order, naming conventions, and calling conventions:

[Public | Private ] Declare Function name [CDecl] Lib "libname"
ú[Alias "aliasname"] [([arglist])] [As type]

The Alias keyword indicates that the procedure being called is in a Macintosh code resource. This is useful when the external procedure name is the same as a keyword.

Use the aliasname to specify the code resource type as follows:

"[resourcetype]$[resourcename]"

The resourcetype is any valid 4-character constant. If omitted, the default resourcetype is CODE. The resourcename is the procedure name in the code resource. If resourcename is omitted, it is assumed to be the same as name.

On the Power Macintosh, the Declare statement supports calls into native code for code fragments only. Calling into code resources is also supported, but only in 68000 emulation mode.

When used on the Power Macintosh, the Declare statement syntax is as follows:

Declare Function MyFunction Lib "hd:system folder:extensions: _
    MyCodeFragment" Alias "MyFunction" () As Long

For both code fragments and code resources, a full or partial path name may be specified for the Lib clause. If the specified Lib clause is ambiguous, it is resolved as follows:

If the file contains a 'cfrg' resource, it's treated as a code fragment.
If it doesn't contain a 'cfrg' resource, it is treated as a file containing code resources.

This allows the creation of "fat" code fragments, that is, files that contain both code fragments and 68000 code resources. When running Visual Basic for Applications on a 68000 Macintosh, the code resource is used. When running it on a Power Macintosh, the native code fragment is used.

The Macintosh toolbox can be accessed on the Power Macintosh using a declaration into the system code fragment.

Specifics (Microsoft Access)

In Microsoft Access, Declare statements are public by default. In a standard module, a public Declare statement is available to all procedures in the current database and in any referencing databases. You can preface a Declare statement with the Private keyword to ensure that it is not available outside of the current module.

To use a Declare statement in a class module, you must precede the statement with the Private keyword. If you fail to include the Private keyword, Microsoft Access generates a compile-time error.

Example

This example shows how the Declare statement is used at the module level of a standard module to declare a reference to an external procedure in a dynamic-link library (DLL) or Macintosh code resource. You can place the Declare statements in class modules if the Declare statements are Private.

' In Microsoft Windows (16-bit):
Declare Sub MessageBeep Lib "User" (ByVal N As Integer)
' Assume SomeBeep is an alias for the procedure name.
Declare Sub MessageBeep Lib "User" Alias "SomeBeep"(ByVal N As Integer)
' Use an ordinal in the Alias clause to call GetWinFlags.
Declare Function GetWinFlags Lib "Kernel" Alias "#132"() As Long

' In 32-bit Microsoft Windows systems, specify the library USER32.DLL,
' rather than USER.DLL. You can use conditional compilation to write
' code that can run on either Win32 or Win16.
#If Win32 Then
    Declare Sub MessageBeep Lib "User32" (ByVal N As Long)
#Else
    Declare Sub MessageBeep Lib "User" (ByVal N As Integer)
#End If

' On the Macintosh:
Declare Sub MessageAlert Lib "MyHd:MyAlert" Alias "MyAlert" (ByVal N _
    As Integer)
' Use a code resource in the Alias clause.
Declare Sub MessageAlert Lib "MyHd:MyAlert" Alias "XTST$MyAlert" _
    (ByVal N As Integer)

' If the code-resource type specifier has only 3 characters, be sure to
' leave a blank space where the final character would normally be.
Declare Sub MessageAlert Lib "MyHd:AnAlert" Alias "COD $AnAlert" _
    (ByVal N As Integer)

Example (Microsoft Access)

In Microsoft Access, you can use the Declare statement at the module level of a standard module to declare a reference to an external procedure in a dynamic-link library (DLL). A Declare statement is public by default. In order to include a Declare statement in a class module, precede it with the Private keyword.

The following example references a procedure in a DLL, then calls that procedure from Visual Basic.

' In standard module.
Declare Sub MessageBeep Lib "User32" (ByVal intN As Integer)

' In class module.
Private Declare Sub MessageBeep Lib "User32" (ByVal intN As Integer)

' Once you have referenced procedure in DLL with Declare
' statement, you can call that procedure normally from code.
Sub SystemBeep(intBeeps As Integer, sngPause As Single)
    Dim intI As Integer
    Dim sngStart As Single

    For intI = 1 To intBeeps
        ' Call system function.
        Call MessageBeep(intBeeps)
        ' Get start time.
        sngStart = Timer
        ' Pause between beeps.
        Do While Timer < sngStart + sngPause
            ' Return control to operating system.
            DoEvents
        Loop
    Next intI
End Sub