Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
|
|
View PDF |
This section describes the maintaining context functions.
Table 19-4 Maintaining Context Functions
Function/Page | Purpose |
---|---|
|
Save a value (or address) for a particular duration. |
|
Return the value stored in the context. |
|
Remove the value stored in the context. |
|
Returns a unique 4-byte value each time it is called. |
See Also:
For more information about using these functions, see Oracle Database Data Cartridge Developer's GuidePurpose
This call is used to save a value (or address) for a particular duration.
Syntax
sword OCIContextSetValue( dvoid *hndl, OCIError *err, OCIDuration duration, ub1 *key, ub1 keylen, dvoid *ctx_value );
Parameters
The OCI environment or user session handle.
The error handle.
One of the following (a previously created user duration):
OCI_DURATION_STATEMENT
OCI_DURATION_SESSION
Unique key value.
Length of the key. Maximum is 64 bits.
Pointer that will be saved in the context.
Comments
The context value being stored must be allocated out of memory of duration greater than or equal to the duration being passed in. The key being passed in should be unique in this session. Trying to save a context value under the same key and duration again will result in overwriting the old context value with the new one. Typically, a client will allocate a structure, store its address in the context using this call, and get this address in a separate call using OCIContextGetValue()
. The (key, value) association can be explicitly removed by calling OCIContextClearValue()
or else it will go away at the end of the duration.
Returns
If operation succeeds, return OCI_SUCCESS
.
If operation fails, return OCI_ERROR
.
Purpose
This call is used to return the value that is stored in the context associated with the given key (by calling OCIContextSetValue()
).
Syntax
sword OCIContextGetValue( dvoid *hndl, OCIError *err, ub1 *key, ub1 keylen, dvoid **ctx_value );
Parameters
The OCI environment or user session handle.
The error handle.
Unique key value.
Length of the key. Maximum is 64 bits.
Pointer to the value stored in the context (NULL
if no value was stored).
Comments
For ctx_value
: a pointer to a preallocated pointer for the stored context to be returned is required.
Returns
If operation succeeds, return OCI_SUCCESS
.
If operation fails, return OCI_ERROR
.
Purpose
This call is used to remove the value that is stored in the context associated with the given key (by calling OCIContextSetValue()
).
Syntax
sword OCIContextClearValue( dvoid *hndl, OCIError *err, ub1 *key, ub1 keylen );
Parameters
The OCI environment or user session handle.
The error handle.
Unique key value.
Length of the key. Maximum is 64 bits.
Comments
An error is returned when a non-existent key is passed.
Returns
If operation succeeds, returns OCI_SUCCESS
.
If operation fails, returns OCI_ERROR
.
Purpose
This call will return a unique, 4-byte value each time it is called.
Syntax
sword OCIContextGenerateKey( dvoid *hndl, OCIError *err, ub4 *key );
Parameters
The OCI environment or user session handle.
The error handle.
Unique key value.
Length of the key. Maximum is 64 bits.
Comments
This value is going to be unique for each session.
Returns
If operation succeeds, return OCI_SUCCESS
.
If operation fails, return OCI_ERROR
.