Vlad and Arnon,

For me your conversation has been interesting BUT it clearly comes from the perspective of persons who "know" C and who are also more than happy to put up with VFP's deficiencies in the documentation department because you have the tempraments to press on.

I have been looking at VFP's documentation regarding APIs and DLLs, and I have also looked at the Tips & Tricks in the VFUG site.

The following will show how VFP's reliance on singular examples causes ME great confusion, generating more questions that it supplies answers:

1) An extract from VFp 5.0 Help for DECLARE-DLL states:

>>DECLARE [cFunctionType] FunctionName IN LibraryName [AS AliasName]
[cParamType1 [@] ParamName1,
cParamType2 [@] ParamName2, ...]
Arguments

cFunctionType Indicates the data type of the return value from the shared library, if any. If the function does not return a value, omit cFunctionType.

cFunctionType can assume the following values:

cFunctionType Description
SHORT 16-bit integer
INTEGER 32-bit integer
SINGLE 32-bit floating point
DOUBLE 64-bit floating point
LONG 32-bit long integer
STRING Character string <<

2) An extract from page 642 of the VFP 5.0 Developer's Guide states:

>> For example, the Windows system function GetSystemTime( ) expects a pointer to a structure consisting of eight words or unsigned 16-bit integers indicating the year, month, day, and so on. The structure is defined this way:
typedef struct _SYSTEMTIME {
WORD wYear ;
WORD wMonth ;
WORD wDayOfWeek ;
WORD wDay ;
WORD wHour ;
WORD wMinute ;
WORD wSecond ;
WORD wMilliseconds ;
} SYSTEMTIME

To pass data between Visual FoxPro and the GetSystemTime( ) function, you must create a 40-byte string buffer (consisting initially of spaces) and then pass the address of this string to the function for it to fill in. When the string is returned, you must parse it in 2-byte increments to extract the individual fields of the structure. The following fragment illustrates how you could extract three of the fields from the structure:
DECLARE INTEGER GetSystemTime IN win32api STRING @
cBuff=SPACE(40)
=GetSystemTime(@cBuff)

tYear = ALLTRIM(STR(ASC(SUBSTR(cBuff,2)) * ;
256 + ASC(SUBSTR(cBuff,1))))
tMonth = ALLTRIM(STR(ASC(SUBSTR(cBuff,4)) * ;
256 + ASC(SUBSTR(cBuff,3))))
tDOW = ALLTRIM(STR(ASC(SUBSTR(cBuff,6)) * ;
256 + ASC(SUBSTR(cBuff,5)))) <<

The questions this generates in my feeble mind include:

a) Why is cFunctionType defines as INTEGER in the example when the API apparently returns a string???
b) If GetSystemTime "expects a pointer to a structure consisting of 8 words or unsigned 16-bit integers", then WHY does it state that "you must create a 40-byte string buffer. . ."? I always thought that a byte was 8 bits and so a "16-bit integer" would be 2 bytes (for a total of 16 bytes required). And even if a "word" is 4 bytes, are not 8*4 = 32 (and not 40)?? SO WHY 40?
c) Since this is a discussion regarding "structures", would it not be useful for the documentation to have some words RIGHT HERE on which type of VFP type is equivalent to which type of C type?


SO there you have it - I am no further ahead after reading than I was before!

Regards,
Jim N. (and I'll say no more myself on this)