---

OCIの確保関数、確保解除関数および解放関数

この項では、OCIの確保関数、確保解除関数および解放関数について説明します。

表18-11 確保関数、確保解除関数および解放関数

関数	用途
OCICacheFree()	キャッシュ内のオブジェクトを解放します。
OCICacheUnpin()	キャッシュまたは接続で永続オブジェクトの確保を解除します。
OCIObjectArrayPin()	参照の配列を確保します。
OCIObjectFree()	割当て済のオブジェクトを解放します。
OCIObjectPin()	オブジェクトを確保します。
OCIObjectPinCountReset()	オブジェクトの確保を解除して確保カウントを0（ゼロ）にします。
OCIObjectPinTable()	継続時間を指定して表オブジェクトを確保します。
OCIObjectUnpin()	オブジェクトの確保を解除します。

---

OCICacheFree()

用途

指定された接続に対してキャッシュ内のオブジェクトと値をすべて解放します。

構文

sword OCICacheFree ( OCIEnv              *env,
                     OCIError            *err,
                     const OCISvcCtx     *svc );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・コンテキストです。

コメント

接続が指定された場合、この関数は、その接続に対して割り当てられている永続オブジェクト、一時オブジェクトおよび値を解放します。それ以外の場合は、オブジェクト・キャッシュ内の永続オブジェクト、一時オブジェクトおよび値をすべて解放します。オブジェクトは、確保カウントに関係なく解放されます。

関連項目: インスタンスの解放の詳細は、「OCIObjectFree()」を参照してください。

関連関数

OCIObjectFree()

---

OCICacheUnpin()

用途

永続オブジェクトの確保を解除します。

構文

sword OCICacheUnpin ( OCIEnv              *env,
                      OCIError            *err,
                      const OCISvcCtx     *svc );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

svc (IN)

OCIサービス・コンテキスト・ハンドルです。指定された接続のオブジェクトの確保が解除されます。

コメント

この関数は、所定の接続に対するすべての永続オブジェクトの確保を完全に解除します。オブジェクトの確保カウントは0（ゼロ）にリセットされます。

関連項目: 確保および確保解除の詳細は、「オブジェクトの確保」および「確保カウントおよび確保解除」を参照してください。

関連関数

OCIObjectUnpin()

---

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()および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)

PINオプションです。

関連項目: 「OCIObjectPin()」

pin_duration (IN)

確保継続時間です。「OCIObjectPin()」を参照してください。

lock (IN)

ロック・オプションです。「OCIObjectPin()」を参照してください。

obj_array (OUT)

この引数がNULLでない場合は、確保されたオブジェクトをこの配列に戻します。void *型の要素をこの配列に割り当てる必要があります。この配列のサイズはarray_sizeと同じです。

pos (OUT)

エラーが発生すると、この引数によってエラーの原因となった要素が示されます。この引数には、ref_arrayの第1要素に対して、1が設定されます。

コメント

確保されたすべてのオブジェクトが1回のネットワーク・ラウンドトリップでデータベースから取り出されます。ユーザーが出力配列（obj_array）を指定した場合は、確保されたオブジェクトのアドレスが配列内の各要素に割り当てられます。

関連関数

OCIObjectPin()

---

OCIObjectFree()

用途

オブジェクト・インスタンスの解放と確保解除を行います。

構文

sword OCIObjectFree ( OCIEnv          *env,
                      OCIError        *err,
                      void            *instance,
                      ub2             flags );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()および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が設定されていないかぎり、エラーが戻ります。

値

オブジェクトのメモリーが即時に解放されます。

関連関数

OCICacheFree()

---

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()および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オプションを使用した排他ロック

  
  

  関連項目: NOWAITオプションの詳細は、「NOWAITオプションを使用したロック」を参照してください。

  
  

object (OUT)

確保されたオブジェクトへのポインタです。

コメント

この関数は、オブジェクト参照によって指示された参照可能オブジェクト・インスタンスを確保します。この確保のプロセスで、次の2つの目的を達成します。

• 参照によって指示されたオブジェクトの場所を特定します。これは、オブジェクト・キャッシュ内のオブジェクトを追跡し記録するオブジェクト・キャッシュによって実行されます。

• 永続オブジェクトは使用中のため、エージ・アウトが不可であることをオブジェクト・キャッシュに通知します。永続オブジェクトは必要に応じていつでもサーバーからロードできるため、割当て時間の経過前であっても、確保が完全に解除された永続オブジェクトを解放する（エージ・アウトさせる）ことができる場合は、利用できるメモリーを増やすことができます。オブジェクトは複数回確保できます。確保されたオブジェクトは、確保が完全に解除されるまでメモリー内に残ります。

  
  

  関連項目: 「OCIObjectUnpin()」を参照してください。

  
  

永続オブジェクト

永続オブジェクトを確保したときにそのオブジェクトがキャッシュ内に存在しない場合は、永続ストアからフェッチされます。オブジェクトの割当て時間はセッションです。オブジェクトがキャッシュ内に存在する場合は、そのオブジェクトがクライアントに戻されます。ロック・オプションが指定されている場合、オブジェクトは、サーバー内でロックされます。

この関数は、存在しないオブジェクトに対してはエラーを戻します。

確保オプションを使用して、取り出されるオブジェクトのコピーを指定します。

• pin_optionがOCI_PIN_ANY（任意のオブジェクトを確保）であり、オブジェクトがすでにオブジェクト・キャッシュ内にある場合は、そのオブジェクトが戻されます。それ以外の場合、オブジェクトはデータベースから取り出されます。これは、OCI_PIN_LATESTである場合と同じです。このオプションは、クライアントがセッションのデータに排他的アクセス権を持っていることを認識しているときに役立ちます。

• pin_optionがOCI_PIN_LATEST（最新のオブジェクトを確保）の場合は、オブジェクトがロックされていなければデータベースから取り出されます。オブジェクトがキャッシュ処理されている場合は、最新バージョンによってリフレッシュされます。リフレッシュの詳細は、「OCIObjectRefresh()」を参照してください。オブジェクトがすでにキャッシュ内に確保され、使用済マークが設定されている場合は、そのオブジェクトへのポインタが戻ります。オブジェクトは、データベースからリフレッシュされません。

• pin_optionがOCI_PIN_RECENT（最近のオブジェクトを確保）であり、オプションがカレント・トランザクションでキャッシュにロードされた場合は、そのオブジェクトが戻されます。オブジェクトがカレント・トランザクション中にロードされていない場合、オブジェクトはサーバーからリフレッシュされます。

一時オブジェクト

一時オブジェクトがすでに解放されている場合、この関数はエラーを戻します。ロック・オプションに排他ロックが指定されている場合は、エラーを戻しません。

関連関数

OCIObjectUnpin()、OCIObjectPinCountReset()

---

OCIObjectPinCountReset()

用途

オブジェクトの確保を完全に解除し、その確保カウントを0（ゼロ）に設定します。

構文

sword OCIObjectPinCountReset ( OCIEnv        *env,
                               OCIError      *err,
                               void          *object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

オブジェクトへのポインタで、すでに確保されていることが必要です。

コメント

この関数は、オブジェクトの確保を完全に解除し、その確保カウントに0（ゼロ）を設定します。オブジェクトの確保が完全に解除されると、OCIは、そのオブジェクトをエラーなしにいつでも暗黙的に解放します。オブジェクトの型に応じて、次の規則が適用されます。

永続オブジェクト

永続オブジェクトの確保が完全に解除された場合、そのオブジェクトはエージ・アウトの対象になります。オブジェクトのメモリーは、オブジェクトのエージ・アウトが終了したときに解放されます。エージ・アウトは、メモリーを最大限に利用するために行われます。使用済オブジェクトは、フラッシュされるまでエージ・アウトされません。

一時オブジェクト

オブジェクトの確保カウントが減分されます。一時オブジェクトは、その割当て時間の終了時、またはOCIObjectFree()をコールすることで明示的に解放された場合にかぎり解放できます。

値

この関数は、値に対してはエラーを戻します。

関連項目: 「確保カウントおよび確保解除」

関連関数

OCIObjectPin()、OCIObjectUnpin()

---

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,
                          void               *not_used,
                          OCIDuration        pin_duration,
                          void               **object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()および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に示されている表名の長さ（バイト単位）です。

not_used (IN/OUT)

このパラメータは使用されていません。NULLを渡します。

pin_duration (IN)

確保継続時間です。

関連項目: 「OCIObjectPin()」

object (OUT)

確保された表オブジェクトです。

コメント

この関数は、表オブジェクトを指定の確保継続時間の間、確保します。クライアントは、OCIObjectUnpin()をコールしてこのオブジェクトの確保を解除できます。

このコールによって確保される表オブジェクトは、スタンドアロン型の永続オブジェクトを作成するために、パラメータとしてOCIObjectNew()に渡すことができます。

注意: この関数で取得されたTDO（TDOまたは表定義の配列）は、渡されたサービス・ハンドル（接続）に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。

関連関数

OCIObjectPin()、OCIObjectUnpin()

---

OCIObjectUnpin()

用途

オブジェクトの確保を解除します。

構文

sword OCIObjectUnpin ( OCIEnv        *env,
                       OCIError      *err,
                       void          *object );

パラメータ

env (IN/OUT)

オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、OCIEnvCreate()およびOCIInitialize()の説明を参照してください。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()をコールして診断情報を取得します。

object (IN)

オブジェクトへのポインタで、すでに確保されていることが必要です。

コメント

各オブジェクトには、そのオブジェクトが確保されるたびに増分される確保カウントが対応付けられています。オブジェクトの確保カウントが0（ゼロ）になったとき、そのオブジェクトの確保は完全に解除されたことになります。確保が解除されたオブジェクトは、OCIによって、エラーなしにいつでも暗黙的に解放されます。

この関数は、オブジェクトの確保を解除します。次のいずれかがTRUEであるとき、オブジェクトの確保は完全に解除されています。

1. オブジェクトの確保カウントが0（ゼロ）に達しています（つまり、全部でN回確保された後に全部でN回確保解除されています）。

2. オブジェクトの確保継続時間が終了しています。

3. オブジェクトに対してOCIObjectPinCountReset()関数がコールされました。

オブジェクトの確保が完全に解除されると、OCIは、そのオブジェクトをエラーなしにいつでも暗黙的に解放します。

オブジェクトの型に応じて、次の規則が適用されます。

永続オブジェクト

永続オブジェクトの確保が完全に解除された場合、そのオブジェクトはエージ・アウトの対象になります。オブジェクトのメモリーは、オブジェクトのエージ・アウトが終了したときに解放されます。エージ・アウトは、メモリーを最大限に利用するために行われます。使用済オブジェクトは、フラッシュされるまでエージ・アウトされません。

一時オブジェクト

オブジェクトの確保カウントが減分されます。一時オブジェクトは、その割当て時間の終了時、またはOCIObjectFree()をコールすることで明示的に削除したときにかぎり解放できます。

値

この関数は値に対してはエラーを戻します。

関連関数

OCIObjectPin()、OCIObjectPinCountReset()