---

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

この項では、コンテキストのメンテナンス関数について説明します。

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

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

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

---

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を戻します。

---

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を戻します。

---

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)

一意のキー値です。

keylen (IN)

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

コメント

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

戻り値

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

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