カートリッジ・サービス — コンテキストのメンテナンス

カートリッジ・サービスのコンテキストのメンテナンス関数をリストし、説明します。

表20-3は、この項で説明しているコンテキストのメンテナンス関数を示しています。

表20-3 コンテキストのメンテナンス関数

関数	用途
OCIContextClearValue()	コンテキストに格納されている値を削除します。
OCIContextGenerateKey()	コールが実行されるたびに一意の4バイト値を戻します。
OCIContextGetValue()	コンテキストに格納されている値を戻します。
OCIContextSetValue()	特定の継続時間に対する値(アドレス)を保存します。

関連項目:

これらの関数の使用方法の詳細は、『Oracle Databaseデータ・カートリッジ開発者ガイド』を参照してください

OCIContextClearValue()

用途

OCIContextSetValue()をコールして指定キーに対応付けられたコンテキストに格納されている値を削除します。

構文

sword OCIContextClearValue( void     *hndl, 
                            OCIError *err, 
                            ub1      *key, 
                            ub1      keylen );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN)

エラー・ハンドルです。

key (IN)

一意のキー値です。

keylen (IN)

キーの長さです。最大の長さは64ビットです。

コメント

存在しないキーが渡されるとエラーが戻されます。

戻り値

• 操作が成功した場合は、OCI_SUCCESSが戻されます。

• 操作が失敗した場合は、OCI_ERRORが戻されます。

OCIContextGenerateKey()

用途

コールが実行されるたびに一意の4バイト値を戻します。

構文

sword OCIContextGenerateKey( void     *hndl, 
                             OCIError *err, 
                             ub4      *key );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN)

エラー・ハンドルです。

key (IN)

一意のキー値です。

コメント

この値はセッションごとに一意です。

戻り値

• 操作が成功した場合は、OCI_SUCCESSが戻されます。

• 操作が失敗した場合は、OCI_ERRORが戻されます。

OCIContextGetValue()

用途

OCIContextSetValue()をコールして指定キーに対応付けられたコンテキストに格納されている値を戻します。

構文

sword OCIContextGetValue( void       *hndl, 
                          OCIError   *err, 
                          ub1        *key, 
                          ub1        keylen, 
                          void       **ctx_value );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN)

エラー・ハンドルです。

key (IN)

一意のキー値です。

keylen (IN)

キーの長さです。最大の長さは64ビットです。

ctx_value (IN)

コンテキストに格納されている値へのポインタです(値が格納されていない場合はNULL)。

コメント

ctx_valueの場合は、戻される格納済コンテキストに対する事前割当てポインタへのポインタが必要です。

戻り値

• 操作が成功した場合は、OCI_SUCCESSが戻されます。

• 操作が失敗した場合は、OCI_ERRORが戻されます。

OCIContextSetValue()

用途

特定の継続時間に対する値(アドレス)を保存します。

構文

sword OCIContextSetValue( void        *hndl, 
                          OCIError    *err, 
                          OCIDuration duration, 
                          ub1         *key, 
                          ub1         keylen, 
                          void        *ctx_value );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN)

エラー・ハンドルです。

duration (IN)

次の値のいずれかになります(以前作成されたユーザー期間)。

OCI_DURATION_STATEMENT

OCI_DURATION_SESSION

key (IN)

一意のキー値です。

keylen (IN)

キーの長さです。最大の長さは64ビットです。

ctx_value (IN)

コンテキストに保存されるポインタです。

コメント

格納されているコンテキスト値は、渡される期間以上の期間でメモリーから割り当てる必要があります。渡されるキーは、このセッションで一意的である必要があります。同じキーと期間で再度コンテキスト値を保存しようとすると、以前のコンテキスト値が新しいコンテキスト値で上書きされます。通常、クライアントは、このコールを使用して構造体を割り当て、そのアドレスをコンテキストに格納し、OCIContextGetValue()を使用して別のコールでこのアドレスを取得します。(キー、値の)対応付けは、OCIContextClearValue()をコールして明示的に削除できます。削除しない場合は、期間の最後で消滅します。

戻り値

• 操作が成功した場合は、OCI_SUCCESSが戻されます。

• 操作が失敗した場合は、OCI_ERRORが戻されます。