---

ハンドル関数および記述子関数

この項では、OCIハンドル関数および記述子関数について説明します。

表16-3 ハンドル関数および記述子関数 

関数	用途
OCIArrayDescriptorAlloc()	記述子の配列を割り当てます。
OCIArrayDescriptorFree()	記述子の配列を解放します。
OCIAttrGet()	ハンドルの属性値を取得します。
OCIAttrSet()	ハンドルまたは記述子の属性値を設定します。
OCIDescriptorAlloc()	記述子またはLOBロケータの割当てと初期化を行います。
OCIDescriptorFree()	割当て済みの記述子を解放します。
OCIHandleAlloc()	ハンドルの割当てと初期化を行います。
OCIHandleFree()	割当て済みのハンドルを解放します。
OCIParamGet()	パラメータ記述子を取得します。
OCIParamSet()	CORハンドルにパラメータ記述子を設定します。

---

OCIArrayDescriptorAlloc()

用途

記述子の配列を割り当てます。

構文

sword OCIArrayDescriptorAlloc ( const  void   *parenth,
                                void          **descpp,
                                const ub4     type,
                                ub4           array_size,
                                const size_t  xtramem_sz,
                                void          **usrmempp);

パラメータ

parenth (IN)

環境ハンドルです。

descpp (OUT)

必要な型を持つ記述子の連続配列へのポインタを戻します。

type (IN)

割り当てられる記述子またはLOBロケータの型を指定します。型のリストは、次の項目を参照してください。

関連項目: 「OCIDescriptorAlloc()」

array_size (IN)

割り当てる記述子の数を指定します。指定した数の記述子をコールで割り当てることができなければ、エラーがスローされます。

xtramem_sz (IN)

記述子の存続期間中アプリケーションで使用するために割り当てられるユーザー・メモリーの量を指定します。

usrmempp (OUT)

記述子の存続期間中コールによってユーザー用に割り当てられた、サイズxtramem_szのユーザー・メモリーのポインタを戻します。

コメント

このコールは、成功した場合はOCI_SUCCESSを、メモリー不足条件が発生した場合は該当するエラーを戻します。

関連項目: xtramem_szパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください。

例

多数の記述子を割り当てるプログラムは、次のコードから変更できます。

OCIDateTime *descpp1[500];
...
for (i = 0; i!=500; i++)
{
     /* Allocate descriptors */
OCIDescriptorAlloc((void  *)envhp,(void  **)&descpp1[i], OCI_DTYPE_TIMESTAMP_TZ,
                   0,(void  **)0);
}
...

次のように、forループを単一コールで置き換えることができます。

OCIArrayDescriptorAlloc((void *)envhp,(void **)&descpp1,
                        OCI_DTYPE_TIMESTAMP_TZ, 500, 0, (void **)0);

関連関数

OCIDescriptorAlloc()、OCIArrayDescriptorFree()

---

OCIArrayDescriptorFree()

用途

前に割り当てた記述子の配列を解放します。

構文

sword OCIArrayDescriptorFree ( void       **descp,
                               const ub4  type );

パラメータ

descp (IN)

割当済記述子の配列へのポインタです。

type (IN)

解放する記憶域の型を指定します。次の関連項目に示す型を参照してください。

関連項目: 「OCIDescriptorAlloc()」

コメント

記述子を割り当てるときにOCIDescriptorAlloc()を使用しても、解放するときにOCIArrayDescriptorFree()を使用すると、エラーが戻されます。

OCIArrayDescriptorAlloc()を使用して割り当てた記述子を解放するには、OCIArrayDescriptorFree()を使用する必要があります。配列全体を1度に解放するように注意してください。OCIArrayDescriptorAlloc()により戻されたポインタのdescppをOCIArrayDescriptorFree()に適切に渡します。それ以外の場合、メモリー・リークが発生する可能性があります。

関連関数

OCIArrayDescriptorAlloc()

---

OCIAttrGet()

用途

ハンドルの属性値を取得します。

構文

sword OCIAttrGet ( const void     *trgthndlp,
                   ub4            trghndltyp,
                   void           *attributep,
                   ub4            *sizep,
                   ub4            attrtype,
                   OCIError       *errhp );

パラメータ

trgthndlp (IN)

ハンドル・タイプのポインタです。実際のハンドルは、文ハンドルやセッション・ハンドルなどの場合があります。このコールによってエンコーディングを取得すると、ユーザーは環境ハンドルまたは文ハンドルと照合してチェックできます。

trghndltyp (IN)

ハンドル・タイプです。次の型が有効です。

• OCI_DTYPE_PARAM、パラメータ記述子用

• OCI_HTYPE_STMT、文ハンドル用

• 表2-1「OCIハンドル・タイプ」の任意のハンドル・タイプ、または表2-2「記述子タイプ」の任意の記述子タイプ

attributep (OUT)

属性値の格納場所へのポインタです。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングになります。

sizep (OUT)

属性値のサイズは常にバイト単位です。これは、attributepがvoidポインタであるためです。非文字列属性のサイズは、OCIライブラリですでに認識されているため、ほとんどの属性の値は、NULLとして渡すことができます。text*パラメータでは、文字列の長さを取得するためにub4のポインタを渡す必要があります。

attrtype (IN)

取り出される属性のタイプです。属性タイプは、このマニュアルの次の章にリストされています。

関連項目: ハンドル・タイプとその読取り可能な属性については、付録A「ハンドルおよび記述子の属性」のリストを参照してください。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

このコールは、ハンドルの特定の属性を取得するときに使用します。OCI_DTYPE_PARAMは暗黙的におよび明示的に記述する場合に使用します。このパラメータ記述子は、ダイレクト・パス・ロードでも使用します。暗黙的な記述の場合、パラメータ記述子には選択リストごとに列記述があります。明示的な記述の場合、パラメータ記述子には記述する各スキーマ・オブジェクトについての記述情報が含まれています。トップレベル・パラメータ記述子にそれ自体が記述子となる属性がある場合、OCIAttrGet()への後続コールで属性の型としてOCI_ATTR_PARAMを使用し、環境ハンドルまたは文ハンドルのUnicode情報を取得します。

関連項目: 「OCIDescribeAny()の使用例」および「選択リスト項目の記述」

OCIAttrGet()と密接に関連している関数は、OCIDescribeAny()です。これは、表、ビュー、シノニム、プロシージャ、ファンクション、パッケージ、順序、型などの既存のスキーマ・オブジェクトを記述する汎用的な記述コールです。このコールの結果、記述ハンドルには、OCIAttrGet()コールを介して取得できるオブジェクト固有の属性が移入されます。

次に、この記述ハンドルに対するOCIParamGet()によって、指定位置のパラメータ記述子が戻されます。パラメータ位置は1から開始します。パラメータ記述子に対してOCIAttrGet()をコールすると、ストアド・プロシージャやストアド・ファンクションのパラメータの特定の属性、場合によっては、表の列記述子が戻されます。OCIDescribeAny()によってスキーマ・オブジェクト記述全体がクライアント側にキャッシュされているため、これらの後続コールは、サーバーへのラウンドトリップを別に行う必要がありません。記述ハンドルに対するOCIAttrGet()コールによって、位置の総数も戻すことができます。

特にUTF-16モードでループを実行する場合は、属性に対応している同じポインタ変数を再利用し、OCIAttrGet()のコール後にその内容をローカル変数にコピーしてください。複数のポインタを同じ属性に使用すると、メモリー・リークが発生する可能性があります。

関連関数

OCIAttrSet()

---

OCIAttrSet()

用途

ハンドルまたは記述子の属性値を設定します。

構文

sword OCIAttrSet ( void        *trgthndlp,
                   ub4         trghndltyp,
                   void        *attributep,
                   ub4         size,
                   ub4         attrtype,
                   OCIError    *errhp );

パラメータ

trgthndlp (IN/OUT)

その属性が変更されるハンドル・タイプのポインタです。

trghndltyp (IN/OUT)

ハンドル・タイプです。

attributep (IN)

属性値のポインタです。この属性値がターゲット・ハンドルにコピーされます。属性値がポインタの場合は、そのポインタのみがコピーされ、ポインタの内容はコピーされません。文字列属性は、OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

size (IN)

属性値のサイズです。サイズはOCIライブラリですでにわかっているため、ほとんどの属性に対して0（ゼロ）で渡すことができます。text*属性では、エンコーディングに関係なく、バイト単位で文字列の長さを設定するためにub4で渡す必要があります。

attrtype (IN)

設定される属性のタイプです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

ハンドル・タイプとその書込み可能な属性については、付録A「ハンドルおよび記述子の属性」のリストを参照してください。

関連関数

OCIArrayDescriptorAlloc()

---

OCIDescriptorAlloc()

用途

記述子またはLOBロケータを格納する記憶域を割り当てます。

構文

sword OCIDescriptorAlloc ( const void    *parenth,
                           void          **descpp,
                           ub4           type,
                           size_t        xtramem_sz,
                           void          **usrmempp);

パラメータ

parenth (IN)

環境ハンドルです。

descpp (OUT)

目的の型の記述子またはLOBロケータを戻します。

type (IN)

割り当てられる記述子またはLOBロケータの型を指定します。

• OCI_DTYPE_SNAP: C型のスナップショット記述子OCISnapshotの生成を指定します。

• OCI_DTYPE_LOB: C型のLOB値型ロケータ（BLOBまたはCLOBの場合）OCILobLocatorの生成を指定します。

• OCI_DTYPE_FILE−C型のFILE値型ロケータOCILobLocatorの生成を指定します。

• OCI_DTYPE_ROWID−C型のROWID記述子OCIRowidの生成を指定します。

• OCI_DTYPE_DATE: C型のANSI DATE記述子OCIDateTimeの生成を指定します。

• OCI_DTYPE_PARAM: C型の読取り専用パラメータ記述子OCIParamの生成を指定します。

• OCI_DTYPE_TIMESTAMP: C型のTIMESTAMP記述子OCIDateTimeの生成を指定します。

• OCI_DTYPE_TIMESTAMP_TZ: C型のTIMESTAMP WITH TIME ZONE記述子OCIDateTimeの生成を指定します。

• OCI_DTYPE_TIMESTAMP_LTZ: C型のTIMESTAMP WITH LOCAL TIME ZONE記述子OCIDateTimeの生成を指定します。

• OCI_DTYPE_INTERVAL_YM: C型のINTERVAL YEAR TO MONTH記述子OCIIntervalの生成を指定します。

• OCI_DTYPE_INTERVAL_DS: C型のINTERVAL DAY TO SECOND記述子OCIIntervalの生成を指定します。

• OCI_DTYPE_COMPLEXOBJECTCOMP−C型の複合オブジェクト検索記述子OCIComplexObjectCompの生成を指定します。

• OCI_DTYPE_AQENQ_OPTIONS−C型のアドバンスト・キューイング・エンキュー・オプション記述子OCIAQEnqOptionsの生成を指定します。

• OCI_DTYPE_AQDEQ_OPTIONS−C型のアドバンスト・キューイング・デキュー・オプション記述子OCIAQDeqOptionsの生成を指定します。

• OCI_DTYPE_AQMSG_PROPERTIES−C型のアドバンスト・キューイング・メッセージ・プロパティ記述子OCIAQMsgPropertiesの生成を指定します。

• OCI_DTYPE_AQAGENT−C型のアドバンスト・キューイング・エージェント記述子OCIAQAgentの生成を指定します。

• OCI_DTYPE_AQNFY: C型のアドバンスト・キューイング通知記述子OCIAQNotifyの生成を指定します。

• OCI_DTYPE_AQLIS_OPTIONS: C型のアドバンスト・キューイング・リスニング記述子OCIAQListenOptsの生成を指定します。

• OCI_DTYPE_AQLIS_MSG_PROPERTIES: C型のアドバンスト・キューイング・メッセージ・プロパティ記述子OCIAQLisMsgPropsの生成を指定します。

• OCI_DTYPE_SRVDN: C型の識別名記述子OCIServerDNsの生成を指定します。

• OCI_DTYPE_UCB: C型のユーザー・コールバック記述子OCIUcbの生成を指定します。

xtramem_sz (IN)

記述子の存続期間中アプリケーションで使用するために割り当てられるユーザー・メモリーの量を指定します。

usrmempp (OUT)

記述子の存続期間中コールによってユーザー用に割り当てられた、サイズxtramem_szのユーザー・メモリーのポインタを戻します。

コメント

typeで指定された型に対応する、割当ておよび初期化済みの記述子のポインタを戻します。成功した場合は、非NULL記述子またはLOBロケータが戻ります。エラー発生時に診断は利用できません。

このコールは、成功した場合はOCI_SUCCESSを、メモリー不足エラーが発生した場合はOCI_INVALID_HANDLEを戻します。

関連項目: xtramem_szパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください。

関連関数

OCIDescriptorFree()、OCIArrayDescriptorAlloc()、OCIArrayDescriptorFree()

---

OCIDescriptorFree()

用途

割当て済み記述子の割当てを解除します。

構文

sword OCIDescriptorFree ( void     *descp,
                          ub4      type );

パラメータ

descp (IN)

割り当てられた記述子です。

type (IN)

解放する記憶域の型を指定します。次の関連項目に示す型を参照してください。

関連項目: 「OCIDescriptorAlloc()」

コメント

このコールにより、記述子に対応付けられた記憶域が解放されます。OCI_SUCCESSまたはOCI_INVALID_HANDLEを戻します。記述子はすべて明示的に割当てを解除できますが、環境ハンドルの割当てを解除すると、OCIで記述子の割当てが解除されます。

関連関数

OCIDescriptorAlloc()

---

OCIHandleAlloc()

用途

このコールは、割当ておよび初期化済みハンドルのポインタを戻します。

構文

sword OCIHandleAlloc ( const void    *parenth,
                       void          **hndlpp,
                       ub4           type,
                       size_t        xtramem_sz,
                       void          **usrmempp );

パラメータ

parenth (IN)

環境ハンドルです。

hndlpp (OUT)

ハンドルを戻します。

type (IN)

割り当てられるハンドルの型を指定します。使用可能なハンドルについては、次の表を参照してください。

関連項目: 表2-1「OCIハンドル・タイプ」

xtramem_sz (IN)

割り当てられるユーザー・メモリーの量を指定します。

usrmempp (OUT)

コールによりユーザーに割り当てられた、サイズxtramem_szのユーザー・メモリーのポインタを戻します。

コメント

typeで指定された型に対応する、割当ておよび初期化済みのハンドルのポインタを戻します。成功時には非NULLハンドルが戻ります。すべてのハンドルが、親ハンドルとして渡される環境ハンドルと対応付けて割り当てられます。

エラー発生時に診断は利用できません。このコールは、成功した場合はOCI_SUCCESSを、エラーが発生した場合はOCI_INVALID_HANDLEを戻します。

ハンドルは、OCIコールに渡す前にOCIHandleAlloc()を使用して割り当てる必要があります。

環境ハンドルの割当ておよび初期化を行うには、OCIEnvInit()をコールします。

関連項目: xtramem_szパラメータを使用したユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください。

関連関数

OCIHandleFree()、OCIEnvInit()

---

OCIHandleFree()

用途

このコールは、ハンドルの割当てを明示的に解除します。

構文

sword OCIHandleFree ( void      *hndlp,
                      ub4       type );

パラメータ

hndlp (IN)

OCIHandleAlloc()により割り当てられるハンドルです。

type (IN)

解放する記憶域の型を指定します。ハンドルについては、次の表を参照してください。

関連項目: 表2-1「OCIハンドル・タイプ」

コメント

このコールは、ハンドルに対応付けられている記憶域で、typeパラメータに指定された型に該当するものを解放します。

このコールは、OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERRORを戻します。

ハンドルはすべて明示的に割当て解除できます。OCIでは、親ハンドルの割当てを解除すると、子ハンドルの割当てが自動的に解除されます。

文ハンドルが解放されると、文ハンドルに関連付けられたカーソルがクローズされますが、実際のカーソルのクローズはサーバーへの次回のラウンドトリップまで延期されます。このため、アプリケーションによりカーソルを即時にクローズする必要がある場合、OCIHandleFree()コールの後にOCIServerVersion()またはOCIPing()などのサーバー・ラウンドトリップ・コールを実行できます。

関連関数

OCIHandleAlloc()、OCIEnvInit()

---

OCIParamGet()

用途

記述ハンドルまたは文ハンドル内の指定位置にあるパラメータの記述子を戻します。

構文

sword OCIParamGet ( const void        *hndlp,
                    ub4               htype,
                    OCIError          *errhp,
                    void              **parmdpp,
                    ub4               pos );

パラメータ

hndlp(IN)

文ハンドルまたは記述ハンドルです。OCIParamGet()関数は、このハンドル用のパラメータ記述子を戻します。

htype (IN)

hndlpパラメータに渡されるハンドルの型です。次の型が有効です。

• OCI_DTYPE_PARAM、パラメータ記述子用

• OCI_HTYPE_COMPLEXOBJECT、複合オブジェクト検索ハンドル用

• OCI_HTYPE_STMT、文ハンドル用

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

parmdpp (OUT)

ハンドル・タイプOCI_DTYPE_PARAMの、posパラメータで指定された位置におけるパラメータの記述子です。

pos (IN)

文ハンドルまたは記述ハンドルにおける位置番号です。この位置にあるパラメータ記述子が戻ります。

注意: 指定位置にパラメータ記述子がない場合は、OCI_ERRORが戻されます。

コメント

このコールは、記述ハンドルまたは文ハンドル内の指定位置にあるパラメータの記述子を戻します。パラメータ記述子は、常にOCIライブラリによって内部的に割り当てられます。また、OCIDescriptorFree()を使用して解放できます。たとえば、文を実行するたびに同じ列のメタデータをフェッチする場合は、OCIParamGet()の各コール間でパラメータ記述子を明示的に解放しないかぎり、プログラムではメモリーがリークします。

関連項目: パラメータ記述子の属性の詳細は、付録A「ハンドルおよび記述子の属性」を参照してください。

関連関数

OCIArrayDescriptorAlloc()、OCIAttrSet()、OCIParamSet()、OCIDescriptorFree()

---

OCIParamSet()

用途

CORハンドルへの複合オブジェクト検索（COR）記述子の設定に使用します。

構文

sword OCIParamSet ( void           *hndlp,
                    ub4            htype,
                    OCIError       *errhp,
                    const void     *dscp,
                    ub4            dtyp,
                    ub4            pos );

パラメータ

hndlp (IN/OUT)

ハンドル・ポインタです。

htype (IN)

ハンドル・タイプです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

dscp (IN)

複合オブジェクト検索記述子ポインタです。

dtyp (IN)

記述子型です。COR記述子の型は、OCI_DTYPE_COMPLEXOBJECTCOMPです。

pos (IN)

位置番号です。

コメント

CORハンドルにはOCIHandleAlloc()を、記述子にはOCIDescriptorAlloc()を使用して、それぞれ前もって割り当てておく必要があります。記述子の属性は、OCIAttrSet()を使用して設定します。

関連項目: 複合オブジェクト検索の詳細は、「複合オブジェクト検索」を参照してください。

関連関数

OCIParamGet()