Chapter 5 C Routines Reference

JagSetSharedValue

Description

Set a shared variable value.

Syntax

JagStatus JagSetSharedData (
            JagSharedData * pData,
            SQLPOINTER pValue,
            SQLINTEGER len)

Parameters

pData

The shared variable handle.

pValue

A buffer containing the new value.

len

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.

Return Values

Return value	To indicate
JAG_SUCCEED	Success
JAG_FAIL	Failure

Check the server's log file for more information when JagSetSharedData fails.

Usage

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 among Jaguar host platforms.
Note JagSetSharedValue does not follow pointers in structures when copying data. If the shared variable is a structure that contains pointers, then only the addresses are copied, not the memory contents at those addresses.

Example storing data values directly

The code below calls JagSetSharedValue to save "Jaguar CTS" as a shared data value. Note that the len parameter is passed as 1 byte more than the string length to ensure that the null-terminator is copied:

SQLCHAR buf[20];
JagSharedData  *pData
 
strcpy(buf, "Jaguar CTS");
retcode = JagSetSharedValue(pData, buf, strlen(buf) + 1);

Example storing pointers to shared data

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, "Jaguar CTS");

/* 
** 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);