Chapter 5: C Routines Reference
Set a shared variable value.
JagStatus JagSetSharedData ( JagSharedData * pData, SQLPOINTER pValue, SQLINTEGER len)
The shared variable handle.
A buffer containing the new value.
The size (in bytes) of the value. If the value is a null-terminated string, you must include the length of the null terminator in the length of the string.
Check the server’s log file for more information when JagSetSharedData fails.
The JagSetSharedValue method copies a value to a specified shared variable. You must have retrieved the shared variable reference before executing this method. You must pass a pointer to the value you want to copy to the shared variable. You must specify the size of the value.
There are two possible strategies for using shared data values:
Pass a pointer to the value so that JagSetSharedValue copies the new value.
This approach is easier to implement, however it should not be used for sharing large data values. Repeated copying of large values can adversely affect performance.
Pass the address of a pointer to the value, so that JagSetSharedValue copies only the address of memory that contains the value.
Use this approach for data structures that contain pointers or for large values. When you use this approach, you must allocate and free the memory used to store shared values yourself. Memory must be allocated with malloc or its equivalent; do not use local variables.
When using this approach, your component must always lock the property during the time that the property data is in use to ensure that the data is not overwritten or freed while it is in use. Locking can be achieved one of two ways:
Lock the collection – Create the collection with the pLockLevel option set to JAG_LOCKCOLLECTION when calling JagNewCollection. Call JagLockCollection or JagLockNoWaitCollection to lock the collection.
Use system calls for locking – Use system calls to create a semaphore or mutex that is stored with the data. You can use the semaphore or mutex to prevent concurrent access.
The first approach is preferable because it is simpler to implement and portable to different platforms.
The code below calls JagSetSharedValue to save “tombstone” as a shared data value. The len parameter is passed as 1 byte more than the string length to ensure that the null-terminator is copied:
SQLCHAR buf; JagSharedData *pData strcpy(buf, "tombstone"); retcode = JagSetSharedValue(pData, buf, strlen(buf) + 1);
The code below allocates a SQLCHAR pointer, then calls JagSetSharedValue to save the pointer as shared data.
SQLCHAR *ptrToData; JagSharedData *pData ptrToData = (SQLCHAR *)malloc(20); strcpy(ptrToData, "tombstone"); /* ** Pass the address of the pointer to save the pointer; ** the length of the shared data is the size of the ** pointer */ retcode = JagSetSharedValue(pData, &ptrToData, sizeof(ptrToData));
Here is code to retrieve the value that was set in the example above:
SQLCHAR *ptrToData; JagSharedData *pData SQLINTEGER outlen; retcode = JagGetSharedValue(pData, &ptrToData, sizeof(ptrToData), &outlen);
JagGetSharedData, JagGetSharedDataByIndex, JagGetSharedValue, JagNewSharedData, JagNewSharedDataByIndex
Appendix C, “Creating C Components,” in the EAServer Programmer’s Guide
|Copyright © 2005. Sybase Inc. All rights reserved.|