Microsoft Access 2010 Bible

Part IV: Professional Database Development

948

Note
The arguments in the argument list are only placeholders. It doesn’t matter what you name them, although
most developers assign them the same name specified in the SDK documentation. The argument list simply tells
Access what to expect when the function is called so that it can check the arguments and their data types.
Access does not, however, check the type declarations against the actual library, so it’s up to you to assign the
correct data types to your arguments.

ByVal or ByRef?

When you assign arguments to a declaration statement, you must decide how the API expects to

receive the arguments. By default, when Access passes an argument, it does so by reference, or

ByRef. This means that Access passes the memory address of the variable to the function it’s call-

ing. When a function receives the address of an argument, it can change the value stored at that

address, which may or may not be desirable. When you pass an argument by value, or ByVal,

you’re telling Access to pass only the variable’s value to the function. When a function receives only

the value of an argument, it can use only that value to do its job. Passing an argument by value is

usually desirable because it ensures that the variables used in your application keep a stable value.

Here’s an example of using the ByVal keyword:

Declare Function apiGetTempPath Lib “Kernel32” _

Alias “GetTempPathA” (ByVal BufferSize As Long, _

ByVal lpszReturnBuffer As String) As Long

There is always an exception to the rule, and the exception in this case is string variables. Access

VBA and C++ handle strings differently. C++ expects to receive pointers to strings that are termi-

nated with a null value; Access VBA does not. This means that you must pass the string by value

(ByVal). As I said earlier, passing an argument by value passes the data stored in the variable

instead of the memory address — except when you pass strings. When you pass a string using the

ByVal option, you pass the address of the variable, which means the function can change the

value passed to it by manipulating what’s stored at the memory address.

In the case of API calls, it’s a good thing that strings are always passed with the ByVal qualifier.

An API function can’t return a string value, so you must give the function permission to alter a

memory location in order to retrieve a string value from an API. You do this by specifying that the

argument is to be passed by value. Notice that lpszReturnBuffer is a pointer to a string that

GetTempPathA uses to place the path that Windows uses for temp files; it’s being passed as an

address. BufferSize, on the other hand, is a variable that contains the length of the string being

passed as lpszReturnBuffer.

A final note on passing strings: Many API functions expect to receive addresses to string values.

Most of the time, these functions expect a minimum number of bytes to be allocated for the string

value. In order to fulfill these requirements, you must know in advance how many bytes the func-

tion expects in the string, and you must expand your string variables to that length before passing

the string. You can do this using the VBA String$() function. The String function fills a string

variable with a fixed number of characters. In the following example, strMyString is filled with

20 spaces: