Hi Albert,

I have similar function in my daily library. It's called buf2dword and looks almost the same. You're right the name is rather ambiguous. It should be something like "four-byte-string-buffer-TO-foxpro-numeric-value" -- of course it has to be squeezed to a reasonable form :)

Many API types are 4-byte values; not just DWORDs but LONG, INT, UINT, HWND; then various pointers like LPRECT, LPBYTE, LPDWORD etc. It is important to know that less significant bytes go first. For example, DWORD value 1 is presented with four bytes: 1, 0, 0, 0.

The meaning of this function is a conversion of 4-byte memory buffer to corresponding FoxPro numeric value. And such memory buffer is nothing else but FoxPro string. Usually this function is required for processing an output from external functions, like Windows API, returned in a form of a structure.

As an example, here is a snippet of code that obtains the version of Shell32.dll installed on local computer.

DECLARE INTEGER DllGetVersion IN shell32 STRING @pdvi

LOCAL lcBuffer
lcBuffer = Chr(20) + Repli(Chr(0), 19)

IF DllGetVersion(@lcBuffer) = 0
	? "Major version:", buf2dword(SUBSTR(lcBuffer, 5,4))
	? "Minor version:", buf2dword(SUBSTR(lcBuffer, 9,4))
	? "Build number: ", buf2dword(SUBSTR(lcBuffer, 13,4))
	? "Platform:     ", Iif(buf2dword(SUBSTR(lcBuffer, 17,4))=1,;
		"Windows", "WinNT")
ENDIF

FUNCTION buf2dword(lcBuffer)
RETURN Asc(SUBSTR(lcBuffer, 1,1)) + ;
	BitLShift(Asc(SUBSTR(lcBuffer, 2,1)),  8) +;
	BitLShift(Asc(SUBSTR(lcBuffer, 3,1)), 16) +;
	BitLShift(Asc(SUBSTR(lcBuffer, 4,1)), 24)

The DllGetVersion populates DLLVERSIONINFO structure that consists of five DWORDs:

*|typedef struct _DllVersionInfo {
*|    DWORD  cbSize;            0:4
*|    DWORD  dwMajorVersion;    4:4
*|    DWORD  dwMinorVersion;    8:4
*|    DWORD  dwBuildNumber;    12:4
*|    DWORD  dwPlatformID;     16:4
*|} DLLVERSIONINFO; total bytes = 20

The easiest way to pass such structure to the function is using a FoxPro string. As you can see, lcBuffer contains exactly 20 bytes (5x4). Its first DWORD is set to the length of the structure. This is a requirement for this particular API call. Note that the buffer is passed to the function by reference.

After the function returns, the lcBuffer is populated with actual values. This is still a string of 20 bytes. We have to split it to five 4-byte substrings and apply buf2dword to each substring to convert it to FoxPro numeric value.