Using SWCSTRUC.DLL

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.

Example Files

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.

Extracting Elements from a C Structure

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.

Get Functions

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

Inserting Elements into a C Structure

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.

Put Functions

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

Using Global Memory

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:

  1. Allocate memory to hold the string:
  2. nPointer = CStructAllocFarMem( 80 )

  3. Store the string in the allocated memory:
  4. Call CStructCopyToFarMem( nPointer, strToPass, 80 )

  5. Store the pointer to the string in a structure starting at the tenth byte:
  6. Call CStructPutFarPointer( strBuffer, 10, nPointer )
    ... do something with allocated memory

  7. When done using the allocated memory, free it:
  8. Call CStructFreeFarMem( nPointer )

Global Memory Functions

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

Copying Buffers

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

Google
 

Return to http://gupta.narod.ru/


Сайт создан в системе uCoz