OCIの確保関数、確保解除関数および解放関数
OCIの確保関数、確保解除関数および解放関数をリストし、説明します。
表27-10は、この項で説明しているOCIの確保関数、確保解除関数および解放関数を示しています。
表27-10 確保関数、確保解除関数および解放関数
| 関数 | 用途 |
|---|---|
|
キャッシュ内のオブジェクトを解放します。 |
|
|
キャッシュまたは接続で永続オブジェクトの確保を解除します。 |
|
|
参照の配列を確保します。 |
|
|
割当て済のオブジェクトを解放します。 |
|
|
オブジェクトを確保します |
|
|
オブジェクトの確保を解除して確保カウントを0 (ゼロ)にします。 |
|
|
継続時間を指定して表オブジェクトを確保します。 |
|
|
オブジェクトの確保を解除します |
OCICacheFree()
指定された接続に対してキャッシュ内のオブジェクトと値をすべて解放します。
用途
指定された接続に対してキャッシュ内のオブジェクトと値をすべて解放します。
構文
sword OCICacheFree ( OCIEnv *env,
OCIError *err,
const OCISvcCtx *svc ); パラメータ
コメント
接続が指定された場合、この関数は、その接続に対して割り当てられている永続オブジェクト、一時オブジェクトおよび値を解放します。それ以外の場合は、オブジェクト・キャッシュ内の永続オブジェクト、一時オブジェクトおよび値をすべて解放します。オブジェクトは、確保カウントに関係なく解放されます。
関連項目:
インスタンスの解放の詳細は、「OCIObjectFree()」を参照してください
OCICacheUnpin()
永続オブジェクトの確保を解除します。
用途
永続オブジェクトの確保を解除します。
構文
sword OCICacheUnpin ( OCIEnv *env,
OCIError *err,
const OCISvcCtx *svc );パラメータ
コメント
この関数は、所定の接続に対するすべての永続オブジェクトの確保を完全に解除します。オブジェクトの確保カウントは0 (ゼロ)にリセットされます。
OCIObjectArrayPin()
参照配列を確保します。
用途
参照配列を確保します。
構文
sword OCIObjectArrayPin ( OCIEnv *env,
OCIError *err,
OCIRef **ref_array,
ub4 array_size,
OCIComplexObject **cor_array,
ub4 cor_array_size,
OCIPinOpt pin_option,
OCIDuration pin_duration,
OCILockOpt lock,
void **obj_array,
ub4 *pos );パラメータ
- env (IN/OUT)
-
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、
OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize()(非推奨)の説明を参照してください。 - err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。 - ref_array (IN)
-
確保される参照の配列です。
- array_size (IN)
-
参照の配列にある要素の数です。
- cor_array
-
確保されるオブジェクトに対応するCORハンドルの配列です。
- cor_array_size
-
cor_arrayにある要素の数です。 - pin_option (IN)
-
確保オプションです。
関連項目:
OCIObjectPin()
コメント
確保されたすべてのオブジェクトが1回のネットワーク・ラウンドトリップでデータベースから取り出されます。ユーザーが出力配列(obj_array)を指定した場合は、確保されたオブジェクトのアドレスが配列内の各要素に割り当てられます。
OCIObjectFree()
オブジェクト・インスタンスの解放と確保解除を行います。
用途
オブジェクト・インスタンスの解放と確保解除を行います。
構文
sword OCIObjectFree ( OCIEnv *env,
OCIError *err,
void *instance,
ub2 flags );パラメータ
- env (IN/OUT)
-
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、
OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize()(非推奨)の説明を参照してください。 - err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。 - instance (IN)
-
スタンドアロン・インスタンスへのポインタです。オブジェクトの場合は、確保されることが必要です。
- flags (IN)
-
OCI_OBJECTFREE_FORCEが渡された場合は、オブジェクトが確保済または使用済である場合も解放します。OCI_OBJECTFREE_NONULLが渡されると、NULLインジケータ構造体は解放されません。
コメント
この関数は、オブジェクト・インスタンスのために割り当てられたすべてのメモリーの割当てを解除します(NULLインジケータ構造体も含まれます)。インスタンスの型に応じて、次の規則が適用されます。
- 永続オブジェクト
-
この関数は、フラッシュされていない使用済永続オブジェクトをクライアントが解放しようとした場合、エラーを戻します。クライアントは、永続オブジェクトをフラッシュするか、マークを解除するか、または
flagsパラメータにOCI_OBJECTFREE_FORCEを設定する必要があります。この関数は、オブジェクトの確保を完全に解除できるかどうかを調べるために
OCIObjectUnpin()を1回コールします。成功した場合は、関数の残りを続行してオブジェクトを解放します。失敗した場合は、flagsパラメータにOCI_OBJECTFREE_FORCEが設定されていないかぎり、エラーが戻ります。メモリー内の永続オブジェクトを解放しても、そのオブジェクトのサーバー側での永続状態が変化することはありません。たとえば、オブジェクトが解放された後でも、そのオブジェクトはロックされたままになります。
- 一時オブジェクト
-
この関数は、オブジェクトの確保を完全に解除できるかどうかを調べるために
OCIObjectUnpin()を1回コールします。成功した場合は、関数の残りを続行してオブジェクトを解放します。失敗した場合は、flagsパラメータにOCI_OBJECTFREE_FORCEが設定されていないかぎり、エラーが戻ります。 - 値
-
オブジェクトのメモリーが即時に解放されます。
OCIObjectPin()
参照可能オブジェクトを確保します。
用途
参照可能オブジェクトを確保します。
構文
sword OCIObjectPin ( OCIEnv *env,
OCIError *err,
OCIRef *object_ref,
OCIComplexObject *corhdl,
OCIPinOpt pin_option,
OCIDuration pin_duration,
OCILockOpt lock_option,
void **object );パラメータ
- env (IN/OUT)
-
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、
OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize()(非推奨)の説明を参照してください。 - err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。 - object_ref (IN)
-
オブジェクトに対する参照です。
- corhdl (IN)
-
複合オブジェクト検索に対するハンドルです。
- pin_option (IN)
-
取り出されるオブジェクトのコピーの指定に使用します。
- pin_duration (IN)
-
オブジェクトがクライアントによってアクセスされる継続時間です。オブジェクトの確保は、確保継続時間の終了時点で暗黙的に解除されます。
OCI_DURATION_NULLが渡された場合、オブジェクトがすでにキャッシュ内にロードされているときは、確保の促進はありません。オブジェクトが未ロードの場合、OCI_DURATION_NULLに対して、確保継続時間にはOCI_DURATION_DEFAULTが設定されます。 - lock_option (IN)
-
ロック・オプション(たとえば、排他的ロック)です。ロック・オプションが指定された場合、オブジェクトはサーバー内でロックされます。オブジェクトのロック状況は、
OCIObjectIsLocked()関数をコールしても取り出せます。次の値が有効です。
-
OCI_LOCK_NONE(ロックなし) -
OCI_LOCK_X(排他ロック) -
OCI_LOCK_X_NOWAIT(NOWAITオプションを使用した排他ロック)関連項目:
コメント
この関数は、オブジェクト参照の指定時に参照可能オブジェクト・インスタンスを確保します。この確保のプロセスで、次の2つの目的を達成します。
-
参照を指定されたオブジェクトの場所を特定します。これは、オブジェクト・キャッシュ内のオブジェクトを追跡し記録するオブジェクト・キャッシュによって実行されます。
-
永続オブジェクトは使用中のため、エージ・アウトが不可であることをオブジェクト・キャッシュに通知します。永続オブジェクトは必要に応じていつでもサーバーからロードできるため、割当て時間の経過前であっても、確保が完全に解除された永続オブジェクトを解放する(エージ・アウトさせる)ことができる場合は、利用できるメモリーを増やすことができます。オブジェクトは複数回確保できます。確保されたオブジェクトは、確保が完全に解除されるまでメモリー内に残ります。
関連項目:
OCIObjectUnpin()
- 永続オブジェクト
-
永続オブジェクトを確保したときにそのオブジェクトがキャッシュ内に存在しない場合は、永続ストアからフェッチされます。オブジェクトの割当て時間はセッションです。オブジェクトがキャッシュ内に存在する場合は、そのオブジェクトがクライアントに戻されます。ロック・オプションが指定されている場合、オブジェクトは、サーバー内でロックされます。
この関数は存在しないオブジェクトに対してはエラーを戻します。
確保オプションを使用して、取り出されるオブジェクトのコピーを指定します。
-
pin_optionがOCI_PIN_ANY(任意のオブジェクトを確保)であり、オブジェクトがすでにオブジェクト・キャッシュ内にある場合は、そのオブジェクトが戻されます。それ以外の場合、オブジェクトはデータベースから取り出されます。これは、OCI_PIN_LATESTである場合と同じです。このオプションは、クライアントがセッションのデータに排他的アクセス権を持っていることを認識しているときに役立ちます。 -
pin_optionがOCI_PIN_LATEST(最新のオブジェクトを確保)の場合は、オブジェクトがロックされていなければデータベースから取り出されます。オブジェクトがキャッシュ処理されている場合は、最新バージョンによってリフレッシュされます。リフレッシュの詳細は、「OCIObjectRefresh()」を参照してください。オブジェクトがすでにキャッシュ内に確保され、使用済マークが設定されている場合は、そのオブジェクトへのポインタが戻ります。オブジェクトは、データベースからリフレッシュされません。 -
pin_optionがOCI_PIN_RECENT(最近のオブジェクトを確保)であり、オプションがカレント・トランザクションでキャッシュにロードされた場合は、そのオブジェクトが戻されます。オブジェクトがカレント・トランザクション中にロードされていない場合、オブジェクトはサーバーからリフレッシュされます。
OCIObjectPinCountReset()
オブジェクトの確保を完全に解除し、その確保カウントを0 (ゼロ)に設定します。
用途
オブジェクトの確保を完全に解除し、その確保カウントを0 (ゼロ)に設定します。
構文
sword OCIObjectPinCountReset ( OCIEnv *env,
OCIError *err,
void *object );パラメータ
コメント
この関数は、オブジェクトの確保を完全に解除し、その確保カウントに0 (ゼロ)を設定します。オブジェクトの確保が完全に解除されると、OCIは、そのオブジェクトをエラーなしにいつでも暗黙的に解放します。オブジェクトの型に応じて、次の規則が適用されます。
OCIObjectPinTable()
表オブジェクトを指定された継続時間の間、確保します。
用途
表オブジェクトを指定された継続時間の間、確保します。
構文
sword OCIObjectPinTable ( OCIEnv *env,
OCIError *err,
const OCISvcCtx *svc,
const OraText *schema_name,
ub4 s_n_length,
const OraText *object_name,
ub4 o_n_length,
const OCIRef *scope_obj_ref,
OCIDuration pin_duration,
void **object );パラメータ
- env (IN/OUT)
-
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、
OCIEnvCreate()、OCIEnvNlsCreate()およびOCIInitialize()(非推奨)の説明を参照してください。 - err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。 - svc (IN)
-
OCIサービス・コンテキスト・ハンドルです。
- schema_name (IN) [オプション]
-
表のスキーマ名です。
- s_n_length (IN) [オプション]
-
schema_nameに示されているスキーマ名の長さ(バイト単位)です。 - object_name (IN)
-
表の名前。
- o_n_length (IN)
-
object_nameに示されている表名の長さ(バイト単位)です。 - scope_obj_ref (IN) [オプション]
-
スコーピング・オブジェクトの参照です。
- pin_duration (IN)
-
確保継続時間です。
関連項目:
OCIObjectPin()
コメント
この関数は、表オブジェクトを指定の確保継続時間の間、確保します。クライアントは、OCIObjectUnpin()をコールしてこのオブジェクトの確保を解除できます。
このコールによって確保される表オブジェクトは、スタンドアロン型の永続オブジェクトを作成するために、パラメータとしてOCIObjectNew()に渡すことができます。
ノート:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。
OCIObjectUnpin()
オブジェクトの確保を解除します。
用途
オブジェクトの確保を解除します。
構文
sword OCIObjectUnpin ( OCIEnv *env,
OCIError *err,
void *object );パラメータ
コメント
各オブジェクトには、そのオブジェクトが確保されるたびに増分される確保カウントが対応付けられています。オブジェクトの確保カウントが0 (ゼロ)になったとき、そのオブジェクトの確保は完全に解除されたことになります。確保が解除されたオブジェクトは、OCIによって、エラーなしにいつでも暗黙的に解放されます。
この関数は、オブジェクトの確保を解除します。次のいずれかがTRUEであるとき、オブジェクトの確保は完全に解除されています。
-
オブジェクトの確保カウントが0 (ゼロ)に達しています(つまり、全部でn回確保された後に全部でn回確保解除されています)。
-
オブジェクトの確保継続時間が終了しています。
-
オブジェクトに対して
OCIObjectPinCountReset()関数がコールされました。
オブジェクトの確保が完全に解除されると、OCIは、そのオブジェクトをエラーなしにいつでも暗黙的に解放します。
確保解除しているオブジェクトの型に応じて、次の規則が適用されます。