1. プログラマーズ・ガイド
  2. Oracle Database Access C API
  3. ハンドル関数および記述子関数

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

OCIハンドル関数および記述子関数をリストし、説明します。

表25-3は、この項で説明しているOCIハンドル関数および記述子関数を示しています。

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

関数 用途

OCIArrayDescriptorAlloc()

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

OCIArrayDescriptorFree()

記述子の配列を解放します。

OCIAttrGet()

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

OCIAttrSet()

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

OCIDescriptorAlloc()

記述子またはLOBロケータの割当てと初期化を行います。

OCIDescriptorFree()

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

OCIHandleAlloc()

ハンドルの割当てと初期化を行います。

OCIHandleFree()

割当て済のハンドルを解放します。

OCIParamGet()

パラメータ記述子を取得します。

OCIParamSet()

CORハンドルにパラメータ記述子を設定します。

25.3.1 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)

array_sizeで番号付けされたポインタの配列へのポインタを戻します(割り当てられた記述子ごとに1つのチャンクが割り当てられるため)。

コメント

このコールは、成功した場合は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);

関連トピック

25.3.2 OCIArrayDescriptorFree()

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

用途

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

構文

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

パラメータ

descp (IN)

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

type (IN)

解放する記憶域の型を指定します。「OCIDescriptorAlloc()」に示す型を参照してください。

コメント

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

LOB操作を実行する場合、OCIArrayDescriptorFree()をコールする前に必ずOCILobFreeTemporary()をコールして、一時LOBの内容を解放する必要があります。詳細は、「一時LOBの解放について」を参照してください。

OCIArrayDescriptorAlloc()を使用して割り当てた記述子は、OCIArrayDescriptorFree()を使用して解放する必要があります。配列全体を一度に解放する場合は注意してください。OCIArrayDescriptorAlloc()で戻されたポインタdescppをOCIArrayDescriptorFree()に適切に渡します。そうしない場合、メモリーがリークすることがあります。

関連トピック

25.3.3 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、文ハンドル用

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

attributep (OUT)

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

sizep (OUT)

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

attrtype (IN)

取り出される属性のタイプです。ハンドル・タイプとその読取り可能な属性は、「ハンドルおよび記述子の属性」にリストされています。

errhp (IN/OUT)

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

コメント

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

関連項目:

「OCIDescribeAny()の使用例」および「選択リスト項目の記述について」

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

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

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

関連トピック

25.3.4 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()に渡すエラー・ハンドルです。

コメント

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

関連トピック

25.3.5 OCIDescriptorAlloc()

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

用途

記述子または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_SHARDING_KEY - C型のシャード・キーまたはシャード・グループ・キーOCIShardingKeyの生成を指定します。

  • 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パラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください

25.3.6 OCIDescriptorFree()

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

用途

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

構文

sword OCIDescriptorFree ( void     *descp,
                          ub4       type );

パラメータ

descp (IN)

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

type (IN)

解放する記憶域の型を指定します。「OCIDescriptorAlloc()」にリストされている型を参照してください。

コメント

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

LOB操作を実行する場合、OCIDescriptorFree()をコールする前に必ずOCILobFreeTemporary()をコールして、一時LOBの内容を解放する必要があります。詳細は、「一時LOBの解放について」を参照してください。

関連トピック

25.3.7 OCIHandleAlloc()

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

用途

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

構文

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

パラメータ

parenth (IN)

環境ハンドルです。

hndlpp (OUT)

ハンドルを戻します。

type (IN)

割り当てられるハンドルの型を指定します。使用可能なハンドルについては、表4-1で説明しています。

xtramem_sz (IN)

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

usrmempp (OUT)

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

コメント

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

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

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

関連トピック

関連項目:

ユーザー・メモリー割当て用のxtramem_szパラメータの使用方法の詳細は、「ユーザー・メモリーの割当て」を参照してください

25.3.8 OCIHandleFree()

ハンドルの割当てを明示的に解除します

用途

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

構文

sword OCIHandleFree ( void      *hndlp,
                      ub4        type );

パラメータ

hndlp (IN)

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

type (IN)

解放する記憶域の型を指定します。ハンドルについては、表4-1で説明しています。

コメント

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

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

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

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

関連トピック

25.3.9 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()の各コール間でパラメータ記述子を明示的に解放しないかぎり、プログラムではメモリーがリークします。

関連トピック

関連項目:

パラメータ記述子の属性の詳細は、「ハンドルおよび記述子の属性」を参照してください

25.3.10 OCIParamSet()

CORハンドルへの複合オブジェクト検索(COR)記述子を設定します。

用途

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()を使用して設定します。

関連トピック

関連項目:

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