Declare

Syntax

Declare Sub SubName Lib LibName$ [(ArgumentList)] [Alias Routine$]

Declare Function FunctionName[$] Lib LibName$ [(ArgumentList)] [Alias Routine$] As Type

Remarks

In Windows, makes available a routine stored in a Windows dynamic-link library (DLL), a Word add-in library (WLL), or the Windows operating system for use as a function or subroutine in a WordBasic macro. On the Macintosh, makes available a routine stored in a Word add-in library (WLL) only. The declaration specifies the name of the routine, the library file in which it is stored, and any arguments the routine takes. Declare instructions are usually placed at the start of a macro, before the main subroutine; they cannot be placed inside a subroutine or function.

Caution

u When experimenting with external routines, save your work often. An invalid argument passed to a routine could result in unpredictable behavior in Word or other applications.

u You cannot declare an external routine in a 16-bit library from a 32-bit application, such as Word for Windows 95 or Word version 6.0 for
Windows NT. You must update macros that declare routines in 16-bit libraries to identify the 32-bit versions of those libraries.

u The names and locations of many Windows 3.x operating system routines (often referred to as API calls) changed in Windows 95 and Windows NT. You must update macros that declare Windows 3.x API calls to declare the correct routines in Windows 95 or Windows NT. Windows 3.x API function libraries are documented in the Microsoft Windows 3.1 Software Development Kit. Windows 95 and Windows NT function libraries are documented in the Microsoft Win32 Software Development Kit.

Argument	Explanation

Sub or Function	Use Function if the function you are declaring returns a value; use Sub if it does not.
SubName or FunctionName[$]	The name used in the macro to call the routine. This name does not have to be the actual name of the routine in the library. You can define the actual name using the Alias part of the statement. If FunctionName returns a string, it should include a dollar sign ($) like other string functions in WordBasic. Note that routine names are case sensitive in Windows 95 and Windows NT; if this name is the actual name of the routine in the library, it should match the documented case.
LibName$	The filename of the library containing the routine, in quotation marks. In Windows, use the entire filename, including the extension, to prevent ambiguity. In Windows, Word looks for the file in the current folder, the Windows folder, the Windows System folder, the Word program folder, and in the folders listed in the PATH environment variable. If the file is not stored in any of these folders, or is not a loaded add-in libarary (WLL), include the complete path with the filename. On the Macintosh, Word looks for the file in the current folder, the System folder, the Word program folder, the Word Dictionaries folder, and the Microsoft folder. If the file is not stored in any of these folders, or is not a loaded WLL, include the complete path with the filename.
ArgumentList	A list of variables representing arguments that are passed to the routine. See the following table for the syntax used within ArgumentList.

Argument	Explanation

Alias Routine$	The actual name of the routine in the library, in quotation marks. It is required only if the name specified after Sub or Function is not the actual name of the routine. Note that routine names are case sensitive in Windows 95 and Windows NT.
As Type	Declares the data type of the value returned by a function. The type is one of the following: As Integer for an integer or logical (BOOL) return type; As String for a string (LPSTR) return type; As Long for a long return type; As Double for a double return type.

The ArgumentList argument has the following syntax:

(Variable[$] [As Type] [, Variable[$] [As Type]] [, ¼])

The following table describes the parts of ArgumentList.

Part	Explanation

Variable[$]	A WordBasic variable name. For string variables, adding a dollar sign ($) to the variable name is the same as specifying As String — for example, fileName$ is the same as fileName As String. If there is no As Type, and the variable name does not end in a dollar sign, the variable defaults to a WordBasic numeric variable (double-precision floating-point number).
As Type	Declares the data type of the argument required by the routine: As Integer for integer or logical (BOOL) arguments; As String (or simply $ at the end of the variable name) for string (LPSTR) arguments; As Long for long arguments; As Double for double arguments.

Example

This Windows example uses the selection as a search keyword in Help. If there is one exact match, the macro displays the topic. If there is more than one match, the macro displays the Search dialog box (Windows 3.x Help) or the Help Topics dialog box (Windows 95 Help) with the keyword selected. If there is no match, the macro displays the Search or Help Topics dialog box, with the keyword list scrolled to the keyword closest in spelling to the selected word.

Declare Function WinHelp Lib "USER.EXE"(hWnd As Integer, lpHelpFile \
    As String, wCmd As Integer, dwData As String) As Integer
Declare Function GetActiveWindow Lib "USER.EXE"() As Integer
Sub MAIN
    hWnd = GetActiveWindow
    helpFile$ = "C:\WINWORD\WINWORD.HLP"
    wCmd = 261            'The decimal value for HELP_PARTIALKEY
    keyWord$ = Selection$()
    success = WinHelp(hWnd, helpFile$, wCmd, keyWord$)
    If success = 0 Then MsgBox "Could not start Windows Help"
End Sub

See Also

Dim