SQLWindows applications can pass data to and receive data from DLL functions that use C structures by calling functions in SWCSTRUC.DLL. You use SWCSTRUC.DLL when you need more flexibility to manipulate structures than the structPointer external data type provides.
The functions that use C structures are grouped into these categories:
These functions use a string buffer to provide access to C structures. The string buffer is accessed directly by these functions and cannot be used as a normal string within SQLWindows.
Warning: To ensure that the SQLWindows string is large enough to hold the entire structure, call SalStrSetBufferLength to initialize the length of the string. The CStructPut* functions do not detect attempts to write beyond the length of the destination string. Writing beyond the length of the string can cause unpredictable results.
These are the example files for SWCSTRUC.DLL:
| CSTRUC.APL | Include library that declares external functions in SWCSTRUC.DLL. |
| CSTRUC.APP | Sample application that uses SWCSTRUC.DLL. |
The table below ("Get Functions") lists the functions that extract C structure elements from a string.
Except for CStructGetString, all functions have these parameters:
String: LPVOID
Number: LONG
The first parameter is the SQLWindows buffer for a C structure. The second parameter is the offset, in bytes, of the value to extract. The extracted value is returned.
The example below gets a WORD that begins at the eighth byte:
nResult = CStructGetWord( strBuffer, 7 )
CStructGetString has these parameters:
String: LPVOID
Number: LONG
Number: LONG
Receive String: LPSTR
The first and second parameters are as described above. The third and fourth parameters contain the number of bytes to extract and the string where the value is stored. The length of the string that has been extracted is returned, including the null terminator.
The example below extracts a string that begins at the eighth byte into a string that can hold up to 20 bytes:
nLength = CStructGetString( strBuffer, 7, 20, strExtract )
Important: To extract int data types, call CStructGetWord.
| Syntax | nResult = CStructGetByte( strBuffer, nOffset ) | |
| Description | Extracts a byte from a buffer | |
| Parameters | String: LPVOID | C structure buffer |
| Number: LONG | offset in bytes to extract | |
| Returns | Number: BYTE | extracted value |
| Syntax | nResult = CStructGetWord( strBuffer, nOffset ) | |
| Description | Extracts an unsigned integer from a buffer | |
| Parameters | String: LPVOID | C structure buffer |
| Number: LONG | offset in bytes to extract | |
| Returns | Number: WORD | extracted value |
| Syntax | nResult = CStructGetLong( strBuffer, nOffset ) | |
| Description | Extracts a long from a buffer | |
| Parameters | String: LPVOID | C structure buffer |
| Number: LONG | offset in bytes to extract | |
| Returns | Number: LONG | extracted value |
| Syntax | nResult = CStructGetFloat( strBuffer, nOffset ) | |
| Description | Extracts a float from a buffer | |
| Parameters | String: LPVOID | C structure buffer |
| Number: LONG | offset in bytes to extract | |
| Returns | Number: FLOAT | extracted value |
| Syntax | nResult = CStructGetDouble( strBuffer, nOffset ) | |
| Description | Extracts a double from a buffer | |
| Parameters | String: LPVOID | C structure buffer |
| Number: LONG | offset in bytes to extract | |
| Returns | Number: DOUBLE | extracted value |
| Syntax | nLength = CStructGetString( strBuffer, nOffset, nMaxWidth, strExtract ) | |
| Description | Extracts a string from a buffer | |
| Parameters | String: LPVOID | C structure buffer |
| Number: LONG | offset in bytes to extract | |
| Number: LONG | number of bytes to extract | |
| Receive String: LPSTR | where to put extracted string | |
| Returns | Number: LONG | length extracted (including null) |
| Syntax | nFarPointer = CStructGetFarPointer( strBuffer, nOffset ) | |
| Description | Extracts a far pointer from a buffer | |
| Parameters | String: LPVOID | C structure buffer |
| Number: LONG | offset in bytes to extract | |
| Returns | Number: LONG | extracted value |
The table below ("Put Functions") lists the functions that insert C structure elements into a string.
Except for CStructPutString, all functions have these parameters:
Receive String: LPVOID
Number: LONG
Number: BYTE, INT, WORD, LONG, FLOAT, or DOUBLE
The first parameter is a buffer for a C structure. The second parameter is the offset in bytes that indicates where to insert the value. The third parameter is the value to insert. This external data type depends on the function.
The example below inserts a WORD beginning at the eighth byte:
CStructPutWord( strBuffer, 7, nValue )
CStructPutString has these parameters:
Receive String: LPVOID
Number: LONG
Number: LONG
String: LPSTR
The first and second parameters are as described above. The third parameter is the maximum number of bytes to insert. The fourth parameter is the null-terminated string to insert. If the maximum number of bytes is less than the length of the string to insert, then the inserted string does not include a null terminator.
The example below inserts a string starting at the eighth byte, where up to 20 bytes are allowed:
CStructPutString( strBuffer, 7, 20, strInsert )
Important: To insert int data types, call CStructPutWord.
| Syntax | bOk = CStructPutByte( strBuffer, nOffset, nInsert ) | |
| Description | Inserts a byte into a buffer | |
| Parameters | Receive String: LPVOID | C structure buffer |
| Number: LONG | where to insert (offset in bytes) | |
| Number: BYTE | value to insert | |
| Returns | Boolean: BOOL | |
| Syntax | bOk = CStructPutWord( strBuffer, nOffset, nInsert ) | |
| Description | Inserts a word into a buffer | |
| Parameters | Receive String: LPVOID | C structure buffer |
| Number: LONG | where to insert (offset in bytes) | |
| Number: WORD | value to insert | |
| Returns | Boolean: BOOL | |
| Syntax | bOk = CStructPutLong( strBuffer, nOffset, nInsert ) | |
| Description | Inserts a long into a buffer | |
| Parameters | Receive String: LPVOID | C structure buffer |
| Number: LONG | where to insert (offset in bytes) | |
| Number: LONG | value to insert | |
| Returns | Boolean: BOOL | |
| Syntax | bOk = CStructPutFloat( strBuffer, nOffset, nInsert ) | |
| Description | Inserts a float into a buffer | |
| Parameters | Receive String: LPVOID | C structure buffer |
| Number: LONG | where to insert (offset in bytes) | |
| Number: FLOAT | value to insert | |
| Returns | Boolean: BOOL | |
| Syntax | bOk = CStructPutDouble( strBuffer, nOffset, nInsert ) | |
| Description | Inserts a double into a buffer | |
| Parameters | Receive String: LPVOID | C structure buffer |
| Number: LONG | where to insert (offset in bytes) | |
| Number: DOUBLE | value to insert | |
| Returns | Boolean: BOOL | |
| Syntax | bOk = CStructPutString( strBuffer, nOffset, nMaxWidth, strInsert ) | |
| Description | Inserts a string into a buffer | |
| Parameters | Receive String: LPVOID | C structure buffer |
| Number: LONG | where to insert (offset in bytes) | |
| Number: LONG | null-terminated string to insert | |
| String: LPSTR | maximum number of bytes to insert | |
| Returns | Boolean: BOOL | |
| Syntax | bOk = CStructPutFarPointer( strBuffer, nOffset, nFarPointer ) | |
| Description | Inserts a far pointer into a buffer | |
| Parameters | Receive String: LPVOID | C structure buffer |
| Number: LONG | where to insert (offset in bytes) | |
| Number: LONG | value to insert | |
| Returns | Boolean: BOOL | |
SWCSTRUC.DLL has functions that allocate, free, and access global memory so that structures with pointers to global memory are accessible by SQLWindows. The table below ("Global Memory Functions") shows these functions.
The example below shows how to use the memory functions to insert a pointer to a string into a structure:
nPointer = CStructAllocFarMem( 80 )
Call CStructCopyToFarMem( nPointer, strToPass, 80 )
Call CStructPutFarPointer( strBuffer, 10, nPointer )
... do something with allocated memory
Call CStructFreeFarMem( nPointer )
| Syntax | nFarPointer = CStructAllocFarMem( nBytes ) | |
| Description | Allocates global memory | |
| Parameters | Number: LONG | number of bytes to allocate |
| Returns | Number: LONG | address of the global memory |
| Syntax | bOk = CStructFreeFarMem( nFarPointer ) | |
| Description | Frees memory allocated by CStructAllocFarMem | |
| Parameters | Number: LONG | address of the global memory to free |
| Returns | Boolean: BOOL | |
| Syntax | bOk = CStructCopyToFarMem( nFarPointer, strData, nDataLen ) | |
| Description | Copies a string to far memory | |
| Parameters | Number: LONG | address of global memory |
| String: LPVOID | data to copy | |
| Number: LONG | maximum number of bytes to copy | |
| Returns | Boolean: BOOL | |
| Syntax | bOk = CStructCopyFromFarMem( nFarPointer, strData, nDataLen ) | |
| Description | Copies data from far memory to a string | |
| Parameters | Number: LONG | address of global memory |
| Receive String: LPVOID | string to copy | |
| Number: LONG | number of bytes to copy | |
| Returns | Boolean: BOOL | |
Use the CStructCopyBuffer function to copy data from one buffer to another. The data in the buffers can contain null characters.
| Syntax | bOk = CStructCopyBuffer( strDest, nDestOffset, strSrc, nSrcOffset, nCopyLen ) | |
| Description | Copies data from far memory to a string | |
| Parameters | String: LPVOID | copy to this string (destination) |
| Number: LONG | where to copy to in destination string | |
| String: LPVOID | copy from this string (source) | |
| Number: LONG | where to copy from in source string | |
| Number: LONG | number of bytes to copy | |
| Returns | Boolean: BOOL | |
Return to http://gupta.narod.ru/