Cartridge Services -- Maintaining Context

Table 13-11 OCI Parameter Manager Interface Functions Quick Reference  

Function/Page	Purpose
OCIContextSetValue()	Save a value (or address) for a particular duration.
OCIContextGetValue()	Return the value stored in the context.
OCIContextClearValue()	Remove the value stored in the context.
OCIContextGenerateKey()	Returns a unique 4-byte value each time it is called.

OCIContextSetValue()

Purpose

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

hndl (IN)

The OCI environment or user session handle.

err (IN)

The error handle.

duration (IN)

One of the following (a previously created user duration):

OCI_DURATION_STATEMENT

OCI_DURATION_SESSION

key (IN)

Unique key value.

keylen (IN)

Length of the key. Maximum is 64 bits.

ctx_value (IN)

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.

  Table 13-12 OCIContextSetValue Keywords/Parameters

  Keyword/Parameter	Meaning
  hndl (IN)	the OCI environment or user session handle
  err (IN)	the error handle
  duration (IN)	any user created duration OCI_DURATION_STATEMENT OCI_DURATION_SESSION
  key (IN))	unique key value
  keylen (IN)	length of the above key (maximum length is 64 bits)
  ctx_value (IN)	pointer that will be saved in the context

OCIContextGetValue()

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

hndl (IN)

The OCI environment or user session handle.

err (IN)

The error handle.

key (IN)

Unique key value.

keylen (IN)

Length of the key. Maximum is 64 bits.

ctx_value (IN)

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.

  Table 13-13 OCIContextSetValue Keywords/Parameters

  Keyword/Parameter	Meaning
  hndl (IN)	the OCI environment or user session handle
  err (IN)	the error handle
  key (IN))	key value previously registered via OCIContextSetValue()
  keylen (IN)	length of the above key (maximum length is 64 bits)
  ctx_value (IN)	pointer to the value stored in the context or NULL if no value was stored

OCIContextClearValue()

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

hndl (IN)

The OCI environment or user session handle.

err (IN)

The error handle.

key (IN)

Unique key value.

keylen (IN)

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.

  Table 13-14 OCIContextClearValue Keywords/Parameters  

  Keyword/Parameter	Meaning
  hndl (IN)	the OCI environment or user session handle
  err (IN)	the error handle
  key (IN))	unique key value
  keylen (IN)	length of the above key (maximum length is 64 bits)

OCIContextGenerateKey()

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

hndl (IN)

The OCI environment or user session handle.

err (IN)

The error handle.

key (IN)

Unique key value.

keylen (IN)

Length of the key. Maximum is 64 bits.

Comments

This value is going to be unique on a per session basis.

Returns

• If operation succeeds, return OCI_SUCCESS.

• If operation fails, return OCI_ERROR.

  Table 13-15 OCIContextGenerateKey Keywords/Parameters

  Keyword/Parameter	Meaning
  hndl (IN)	the OCI environment or user session handle
  err (IN)	the error handle
  key (OUT))	pointer to a unique, 4 byte value

  .