Skip to content
This repository has been archived by the owner on Nov 16, 2023. It is now read-only.

Latest commit

 

History

History
140 lines (98 loc) · 9.34 KB

declare-statement.md

File metadata and controls

140 lines (98 loc) · 9.34 KB
Raw
title keywords f1_keywords ms.prod ms.assetid ms.date
Declare Statement
vblr6.chm1008781
vblr6.chm1008781
office
82f68f6b-76c6-2efd-72d2-652000b3a083
06/08/2017

Declare Statement

Used at module level to declare references to externalprocedures in adynamic-link library (DLL).

Note Declare statements with the PtrSafe keyword is the recommended syntax. Declare statements that include PtrSafe work correctly in the VBA7 development environment on both 32-bit and 64-bit platforms only after all data types in the Declare statement (parameters and return values) that need to store 64-bit quantities are updated to useLongLong for 64-bit integrals orLongPtr for pointers and handles. To ensure backwards compatibility with VBA version 6 and earlier use the following construct:

#If VBA7 Then 
Declare PtrSafe Sub... 
#Else 
Declare Sub... 
#EndIf

Syntax 1 [ Public |Private ] Declare SubnameLib "libname" [ Alias "aliasname" ] [ ( [ arglist ] ) ] Syntax 2 [ Public |Private ] Declare FunctionnameLib "libname" [ Alias "aliasname" ] [ ( [ arglist ] ) ] [ Astype ] VBA7 Declare Statement Syntax

Note For code to run in 64-bit versions of Microsoft Office all Declare statements must include the PtrSafe keyword, and all data types in the Declare statement (parameters and return values) that need to store 64-bit quantities must be updated to useLongLong for 64-bit integrals orLongPtr for pointers and handles.

Syntax 1 (Sub) [ Public |Private ] Declare PtrSafe ** Sub**nameLib "libname" [ Alias "aliasname" ] [ ( [ arglist ] ) ] Syntax 2 (Function) [ Public |Private ] Declare PtrSafe FunctionnameLib "libname" [ Alias "aliasname" ] [ ( [ arglist ] ) ] [ Astype ]

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.
PtrSafe Required on 64-bit. The PtrSafe keyword asserts that a Declare statement is safe to run in 64-bit versions of Microsoft Office
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 anexpression.
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 publicvariable, 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.
type Optional. Data type of the value returned by a Function procedure; may beByte, Boolean, Integer, Long, LongLong, LongPtr, Currency, Single, Double, Decimal (not currently supported),Date, String (variable length only), orVariant, a user-defined type, or an object type. ( LongLong is a valid declared type only on 64-bit platforms.)
The arglist argument has the following syntax and parts:
[ Optional ] [ ByVal ByRef ] [ ParamArray ] varname [ ( ) ] [ Astype ]
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 Optionalarray 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, LongLong, LongPtr, Currency, Single, Double, Decimal (not currently supported), Date, String (variable length only), Object, Variant, a user-defined type, or an object type. ( LongLong is a valid declared type only on 64-bit platforms.)
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 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, 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 ("").

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). You can place the Declare statements in class modules if the Declare statements are Private.

Note

' 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 
 
 
' 64-bit Declare statement example: 
Declare PtrSafe Function GetActiveWindow Lib "User32" () As LongPtr 
 
' Conditional Compilation Example 
#If Vba7 Then 
     ' Code is running in  32-bit or 64-bit VBA7. 
     #If Win64 Then 
          ' Code is running in 64-bit VBA7. 
     #Else 
          ' Code is not running in 64-bit VBA7. 
     #End If 
#Else 
     ' Code is NOT running in 32-bit or 64-bit VBA7. 
#End If