25.3 ハンドル関数および記述子関数
OCIハンドル関数および記述子関数をリストし、説明します。
表25-3は、この項で説明しているOCIハンドル関数および記述子関数を示しています。
表25-3 ハンドル関数および記述子関数
関数 | 用途 |
---|---|
記述子の配列を割り当てます。 |
|
記述子の配列を解放します。 |
|
ハンドルの属性値を取得します。 |
|
ハンドルまたは記述子の属性値を設定します。 |
|
記述子またはLOBロケータの割当てと初期化を行います。 |
|
割当て済の記述子を解放します。 |
|
ハンドルの割当てと初期化を行います。 |
|
割当て済のハンドルを解放します。 |
|
パラメータ記述子を取得します。 |
|
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ロケータの型を指定します。
関連項目:
OCI記述子 - array_size (IN)
-
割り当てる記述子の数を指定します。指定した数の記述子をコールで割り当てることができなければ、エラーがスローされます。
コメント
このコールは、成功した場合は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)
-
解放する記憶域の型を指定します。
関連項目:
OCI記述子
コメント
記述子を割り当てるときに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)
-
ハンドル・タイプです。次の型が有効です。
- 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情報を取得します。
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記述子
コメント
type
で指定された型に対応する、割当ておよび初期化済の記述子のポインタを戻します。成功した場合は、非NULL
記述子またはLOBロケータが戻ります。エラー発生時に診断は利用できません。
このコールは、成功した場合はOCI_SUCCESS
を、メモリー不足エラーが発生した場合はOCI_INVALID_HANDLE
を戻します。
関連項目:
xtramem_sz
パラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください
25.3.6 OCIDescriptorFree()
割当て済記述子の割当てを解除します。
用途
割当て済記述子の割当てを解除します。
構文
sword OCIDescriptorFree ( void *descp, ub4 type );
パラメータ
- descp (IN)
-
割り当てられた記述子です。
- type (IN)
-
解放する記憶域の型を指定します。
関連項目:
OCI記述子
コメント
このコールにより、記述子に対応付けられた記憶域が解放されます。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)
-
割り当てられるハンドルの型を指定します。使用可能なハンドルについては、表3-1で説明しています。
コメント
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)
-
解放する記憶域の型を指定します。ハンドルについては、表3-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
、文ハンドル用
コメント
このコールは、記述ハンドルまたは文ハンドル内の指定位置にあるパラメータの記述子を戻します。パラメータ記述子は、常に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 );
パラメータ
コメント
CORハンドルにはOCIHandleAlloc()
を、記述子にはOCIDescriptorAlloc()
を使用して、それぞれ前もって割り当てておく必要があります。記述子の属性は、OCIAttrSet()
を使用して設定します。
関連項目:
複合オブジェクト検索の詳細は、「複合オブジェクト検索」を参照してください