Naming the Procedure

The name that follows Declare Function or Declare Sub is the name you use to call the procedure from VBA. There is a degree of flexibility here because the name need not be the actual name of the procedure in the DLL.

As in the following example, you can rename the procedure to almost anything, provided you use the Alias keyword to specify the actual name of the API procedure.

Private Declare Function MySillyProcedureName Lib "advapi32.dll" _ Alias "GetUserNameA" (ByVal lpBuffer As String, _ nSize As Long) As Long

The Alias keyword specifies the actual name of the procedure as it appears in the API. You cannot change this, but as you've seen, you can change the Name argument in the procedure declaration.

There are several reasons for renaming an API procedure:

□ Some API procedures begin with an underscore character (_), which is illegal in VBA. To get around this, rename the procedure and use the Alias keyword.

□ API procedure names are case sensitive, and terribly intolerant of programmers who forget that. VBA, on the other hand, doesn't care one way or the other, so by renaming the procedure, you build in a level of forgiveness.

□ Several API procedures have arguments that can accept different data types. Supplying a wrong data type to such a procedure is a good way to get the API angry because VBA does not check the data types of the arguments you supply. The kind of response you are likely to get by using a wrong data type can range from erroneous data, unexpected application behavior, application hang, or system crash. To avoid type problems, declare several versions of the same procedure, each with a different name and each using arguments of different data types.

□ Some Windows APIs have names that are the same as the reserved keywords in Access, such as SetFocus and GetObject. Using those keywords results in a compile error. Because you can't rename the Access keywords, you can give the API a unique name in the Declare statement and use the Alias keyword to refer to the API as defined by Windows.

□ Most API procedures that can take string arguments come in two flavors: one for ANSI and one for Unicode. The ANSI version is suffixed by an A, as in the GetUserNameA example. The Unicode flavor has a W suffix (for wide). VBA uses Unicode internally and converts all strings to ANSI before calling a DLL procedure, so you generally use the ANSI version. But if you need to use both versions in the same project, renaming one or both of them makes sense.

□ Finally, you can create procedure names that conform to your object naming standards.

What Is Unicode?

Unicode is one of the three distinct character sets supported by the Win32 API:

Single-byte: 8 bits wide, and provides for 256 characters. The ANSI character set is a single-byte character set.

Double-byte (DBCS): Also 8 bits wide, but some of its byte values are called DBCS lead bytes, which are combined with the byte that follows them to form a single character. DBCSs provide a sufficient number of characters for languages such as Japanese, which have hundreds of characters.

Unicode: 16 bits, which provides for up to 65,535 characters; enough to support all the characters in all the languages around the world.

If you make a mistake when declaring the Alias, VBA won't find the procedure in the DLL and will present runtime error 453 (Can't find DLL entry point GetUserNameB in advapi32), which your error-handling code can trap.

0 0

Post a comment