Calvin Hsia's WebLog

DECLARE DLL performance questions

I was writing a sample about DECLARE DLL to show some of its features which I implemented about 12 years ago, when I rediscovered an interesting performance issue.

The purpose of DECLARE DLL is to allow the user to call functions in a DLL directly. For example, most of the Win32 API  lives in DLLs and thus being able to call the API directly is very powerful.

In order to use the function in a DLL, you needed to know its name and its parameter signature. For example, the GetWindowText function of the Windows API will return the text associated with a Window handle. If the Window handle is a normal user Window, it’s the title of the window. If it’s the Window handle of a button, then it’s the text on the button. GetWindowText takes 3 parameters: the Window Handle, a string buffer to place the answer, and the size of that buffer. It returns the length of the result put in the string buffer.

In order to use this API from VB or VFP, you would need to know that it lives in User32.dll in your Windows System directory (typically c:\windows\system32\user32.dll). Also, there are actually 2 versions of this API, as the windows SDK header file for this API (win32sdk\include\winuser.h) shows:

#ifdef UNICODE

#define GetWindowText  GetWindowTextW

#else

#define GetWindowText  GetWindowTextA

#endif // !UNICODE

In fact, there are 2 versions of most Win32 APIs that deal with strings: one for UNICODE (2 bytes per character) and one for non-UNICODE (double byte (1 or 2 bytes per character) and ANSI (1 byte per character). These header files are how the programmer (almost all were C/C++ developers in the old days) can use the Win32API.

To hide this Unicode complexity from the user, the header file has a conditional #define, so the user just has to write GetWindowText, and the #define macro expands it in the C compiler preprocessor

The UNICODE version appends a “W” and the non-UNICODE version appends a “A”.

That means the actual DLL does not export “GetWindowText”, but has 2 exports: “GetWindowTextA” and “GetWindowTextW”

You can see the two by typing this in a Visual Studio command prompt:

D:\>link /dump /exports c:\windows\system32\user32.dll | find /i "getwindowtext"

        376  177 0000F002 GetWindowTextA

        377  178 0001F1BE GetWindowTextLengthA

        378  179 0000DC5F GetWindowTextLengthW

        379  17A 0000BA08 GetWindowTextW

        402  191 0000C057 InternalGetWindowText

So the user would have to declare GetWindowTextA rather than GetWindowText.

To hide this complexity from the every day user, VFP will try to see if the specified function exists in the DLL. If it doesn’t, a “A” is appended to the function name and the DLL is queried again.

Because of this trial and error approach, one would think that appending the “A” before calling the API would make a difference in performance.

Another complexity arises for Win32 API calls (but not for other DLLs). The user is required to know in which particular DLL of Windows the function resides. Back in the old days, it wasn’t quite as clear. With MSDN online now, it’s pretty easy to see at the bottom of the MSDN topic for the API. The DECLARE DLL command allows the user to just type “Win32API” instead of the DLL name, which means User32.dll, Gdi32.dll, Kernel32.dll , Advapi32.dll and Mpr.dll are searched (in that order).

So the question is which would be faster: specifying the particular DLL name directly, or using “Win32API”?  How about specifying with or without the “A” ?

See also:

DECLARE DLL allows OBJECT type

What happens if external code throws an exception?

Is there a way in VFP to pass a DWORD to an API function from VFP?

Will GetLastError ever work properly in VFP8.0?

Undocumented APIs and 16 bit DLLs

What external code does your EXE depend on?

Here’s some sample code to get you started. The answer may surprise you!

          DECLARE integer GetWindowText IN win32api integer hWnd, string @ lpString, integer nMaxCout

          cStr=SPACE(100)

          ?GetWindowText(_vfp.hWnd,@cStr,LEN(cStr))

          ?cStr

nStart=SECONDS()

CLEAR DLLS

FOR i = 1 TO 10000

          cStr=SPACE(100)

          IF .f.

                   DECLARE integer GetWindowText IN win32api integer hWnd, string @ lpString, integer nMaxCout

                   GetWindowText(_vfp.hWnd,@cStr,LEN(cStr))

          ELSE

                   DECLARE integer GetWindowTextA IN c:\windows\system32\user32.dll integer hWnd, string @ lpString, integer nMaxCout

                   GetWindowTextA(_vfp.hWnd,@cStr,LEN(cStr))

          ENDIF

ENDFOR

?SECONDS()-nStart

RETURN