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