Lock and unlock collections  Release shared variable and collection references

Appendix C: Creating C Components

Read and update shared variables

Before reading or updating the shared variable, the component object must retrieve references to the collection and shared variable.

  1. Call the JagGetCollection routine to retrieve a reference for a collection. If the component object has just created the collection, the component object doesn’t need to call this routine.

  2. Call the JagGetSharedData or JagGetSharedDataByIndex routine to retrieve a reference to a shared variable. If the component object has just created the shared variable, the component object doesn’t need to call either of these routines.

  3. Call the JagGetSharedValue routine to retrieve a shared variable value.

  4. Call the JagSetSharedValue routine to assign a new value to the shared variable.


Retrieve references for collections

The JagGetCollection routine returns a reference to the specified collection. Once the component instance has retrieved a reference, the component object can lock and unlock the collection, create a new shared variable in the collection, or retrieve a reference to an existing shared variable.

If the collection exists, JAG_SUCCEED is returned and **ppCollection is set to the collection reference. If the collection does not exist, JAG_FAIL is returned and **ppCollection is set to NULL.


Retrieve references to shared variables

The JagGetSharedData and JagGetSharedDataByIndex routines return a reference to the specified shared variable. The component object must have already retrieved the collection reference before calling these routines. When calling the JagGetSharedData routine, you specify the shared variable by name. When calling the JagGetSharedDataByIndex routine, you specify the shared variable by index number.

For both routines, if the shared variable exists, JAG_SUCCEED is returned and **ppData is set to the shared variable reference. If the shared variable does not exist, JAG_FAIL is returned and **ppData is set to NULL for both routines.


Retrieve shared variable values

The JagGetSharedValue routine retrieves the value for a specified shared variable and places the value in a buffer. The component object must have retrieved the shared variable reference before executing this routine. The component object must create a buffer in which to copy a value. The buffer must be large enough to hold any value that can be stored in the shared variable. You must specify the buffer (and its size) in which the value is to be copied. The buffer must be large enough to contain the value. If the value is too large for the buffer, JAG_FAIL and the size of the value are returned.

If the value is successfully copied into the buffer, JAG_SUCCEED and the number of bytes copied to the buffer are returned. If *outlen is 0, then there was no value to copy.


Update shared variables with new values

The JagSetSharedValue routine copies a value to a specified shared variable. The component object must have retrieved the shared variable reference before calling this routine. The component object must pass a pointer to the value you want the component object to copy to the shared variable. This routine copies the value to the shared variable. You must specify the size 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.

EAServer maintains the values of shared data in its own memory space. When JagSetSharedValue() copies the data, it does not copy the pointer to the data. Similarly, JagGetSharedValue() copies the data into a buffer supplied by the caller, it does not place a pointer to the data in the user’s buffer.

If the new value is copied to the shared value, JAG_SUCCEED is returned. If an error occurs, JAG_FAIL is returned.




Copyright © 2005. Sybase Inc. All rights reserved. Release shared variable and collection references

View this book as PDF