Passing Arguments to DLL Functions from CitectVBA

Many arguments to DLL functions are passed by value. By default, arguments in CitectVBA are passed by reference, so it's important that you include the Byval keyword in the function definition when the DLL function requires that an argument be passed by value. See Passing variables Byref and Byval.

Note: Although the Byval keyword appears in front of some arguments of type String, strings are always passed to Windows API functions by reference, therefore any DLL function can always modify a string source directly.

DLL functions don't return strings in the same way that CitectVBA functions do. Because strings are always passed to DLL functions by reference, the DLL function can modify the value of the string argument. Rather than returning a string as the return value for the function, as you would probably do in CitectVBA, a DLL function returns a string into an argument of type String that was passed to the function. The actual return value for the function is often a long integer specifying the number of bytes that were written into the string argument.

To call a DLL function that writes to a String variable, you need to take additional steps to format the string properly. First of all, the String variable must be a null-terminated string. A null-terminated string ends in a special null character. Secondly, a DLL function can't change the size of a string once it has been created.

Therefore, you need to make sure that the string that you pass to a function is large enough to hold the entire return value, and that it terminates with a Null character. When you pass a string to a DLL function, you'll usually need to specify the size of the string that you've passed in another argument. Windows keeps track of the length of the string so that it doesn't overwrite any memory that the string is using.

Note: It's only necessary to pass in a null-terminated string and its size if you're returning a string from a function. If the function does not return a string into a string argument, but instead takes a string that provides information to the function, you can simply pass in a normal CitectVBA String variable.

A Nullstring is a string of value 0 [no Character code]; note that this is not the same as an empty string ("").