| Oracle® Call Interfaceプログラマーズ・ガイド 12c リリース1 (12.1) B72465-07 |
|
 前 |
 次 |
表16-3は、この項で説明しているOCIハンドル関数および記述子関数を示しています。
表16-3 ハンドル関数および記述子関数
| 関数 | 用途 |
|---|---|
記述子の配列を割り当てます。 |
|
記述子の配列を解放します。 |
|
ハンドルの属性値を取得します。 |
|
ハンドルまたは記述子の属性値を設定します。 |
|
記述子またはLOBロケータの割当てと初期化を行います。 |
|
割当て済の記述子を解放します。 |
|
ハンドルの割当てと初期化を行います。 |
|
割当て済のハンドルを解放します。 |
|
パラメータ記述子を取得します。 |
|
CORハンドルにパラメータ記述子を設定します。 |
記述子の配列を割り当てます。
用途
記述子の配列を割り当てます。
構文
sword OCIArrayDescriptorAlloc ( const void *parenth,
void **descpp,
const ub4 type,
ub4 array_size,
const size_t xtramem_sz,
void **usrmempp);
パラメータ
コメント
このコールは、成功した場合は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);
用途
前に割り当てた記述子の配列を解放します。
構文
sword OCIArrayDescriptorFree ( void **descp,
const ub4 type );
パラメータ
割当済記述子の配列へのポインタです。
解放する記憶域の型を指定します。「OCIDescriptorAlloc()」にリストされている型を参照してください。
コメント
記述子を割り当てるときにOCIDescriptorAlloc()を使用しても、解放するときにOCIArrayDescriptorFree()を使用すると、エラーが戻されます。
OCIArrayDescriptorAlloc()を使用して割り当てた記述子は、OCIArrayDescriptorFree()を使用して解放する必要があります。配列全体を一度に解放する場合は注意してください。OCIArrayDescriptorAlloc()で戻されたポインタdescppをOCIArrayDescriptorFree()に適切に渡します。そうしない場合、メモリーがリークすることがあります。
ハンドルの属性値を取得します。
用途
ハンドルの属性値を取得します。
構文
sword OCIAttrGet ( const void *trgthndlp,
ub4 trghndltyp,
void *attributep,
ub4 *sizep,
ub4 attrtype,
OCIError *errhp );
パラメータ
ハンドル・タイプのポインタです。実際のハンドルは、文ハンドルやセッション・ハンドルなどの場合があります。このコールによってエンコーディングを取得すると、ユーザーは環境ハンドルまたは文ハンドルと照合してチェックできます。
ハンドル・タイプです。次の型が有効です。
属性値の格納場所へのポインタです。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングです。
attributepがvoidポインタであるため、属性値のサイズは常にバイト単位です。文字列以外の属性のサイズはOCIライブラリですでに認識されているため、ほとんどの属性に対してNULLで渡すことができます。text*パラメータの場合は、ub4へのポインタを渡して文字列の長さを取得する必要があります。
取り出される属性のタイプです。ハンドル・タイプとその読取り可能な属性は、「ハンドルおよび記述子の属性」にリストされています。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コメント
このコールは、ハンドルの特定の属性を取得するときに使用します。OCI_DTYPE_PARAMは暗黙的におよび明示的に記述する場合に使用します。このパラメータ記述子は、ダイレクト・パス・ロードでも使用します。暗黙的な記述の場合、パラメータ記述子には選択リストごとに列記述があります。明示的な記述の場合、パラメータ記述子には記述する各スキーマ・オブジェクトについての記述情報が含まれています。トップレベル・パラメータ記述子にそれ自体が記述子となる属性がある場合、OCIAttrGet()への後続コールで属性の型としてOCI_ATTR_PARAMを使用し、環境ハンドルまたは文ハンドルのUnicode情報を取得します。
OCIAttrGet()に密接に関連している関数はOCIDescribeAny()で、この関数は、表、ビュー、シノニム、プロシージャ、ファンクション、パッケージ、順序および型などの既存のスキーマ・オブジェクトを記述する汎用的な記述コールです。このコールは、OCIAttrGet()コールを使用して取得できるオブジェクト固有の属性を記述ハンドルに移入します。
次に、この記述ハンドルに対するOCIParamGet()コールによって、指定位置のパラメータ記述子が戻されます。パラメータ位置は1から開始します。パラメータ記述子に対してOCIAttrGet()をコールすると、ストアド・プロシージャまたはファンクション・パラメータの特定の属性、あるいは表の列記述子が戻されます。OCIDescribeAny()によってスキーマ・オブジェクト記述全体がクライアント側にキャッシュされているため、これらの後続コールは、サーバーへのラウンドトリップを別に行う必要がありません。記述ハンドルに対するOCIAttrGet()コールによって、位置の総数も戻すことができます。
特にUTF-16モードでループを実行する場合は、属性に対応している同じポインタ変数を再利用し、OCIAttrGet()のコール後にその内容をローカル変数にコピーしてください。複数のポインタを同じ属性に使用すると、メモリー・リークが発生する可能性があります。
ハンドルまたは記述子の属性値を設定します。
用途
ハンドルまたは記述子の属性値を設定します。
構文
sword OCIAttrSet ( void *trgthndlp,
ub4 trghndltyp,
void *attributep,
ub4 size,
ub4 attrtype,
OCIError *errhp );
パラメータ
その属性が変更されるハンドルのポインタです。
ハンドル・タイプです。
属性値のポインタです。この属性値がターゲット・ハンドルにコピーされます。属性値がポインタの場合は、そのポインタのみがコピーされ、ポインタの内容はコピーされません。文字列属性は、OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
属性値のサイズです。サイズはOCIライブラリですでにわかっているため、ほとんどの属性に対して0 (ゼロ)で渡すことができます。text*属性では、エンコーディングに関係なく、バイト単位で文字列の長さを設定するためにub4で渡す必要があります。
設定される属性のタイプです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コメント
ハンドル・タイプとその書込み可能な属性については、「ハンドルおよび記述子の属性」のリストを参照してください。
用途
記述子またはLOBロケータを格納する記憶域を割り当てます。
構文
sword OCIDescriptorAlloc ( const void *parenth,
void **descpp,
ub4 type,
size_t xtramem_sz,
void **usrmempp);
パラメータ
環境ハンドルです。
目的の型の記述子またはLOBロケータを戻します。
割り当てられる記述子またはLOBロケータの型を指定します。
OCI_DTYPE_SNAP - C型のスナップショット記述子OCISnapshotの生成を指定します。
OCI_DTYPE_LOB - C型のLOB値型ロケータ(BLOBまたはCLOBの場合) OCILobLocatorの生成を指定します。
OCI_DTYPE_FILE - C型のFILE値型ロケータOCILobLocatorの生成を指定します。
OCI_DTYPE_ROWID - C型OCIRowidの記述子ROWIDの生成を指定します。
OCI_DTYPE_DATE - C型のANSI DATE記述子OCIDateTimeの生成を指定します。
OCI_DTYPE_PARAM - C型の読取り専用パラメータ記述子OCIParamの生成を指定します。
OCI_DTYPE_TIMESTAMP - C型OCIDateTimeの記述子TIMESTAMPの生成を指定します。
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の生成を指定します。
コメント
typeで指定された型に対応する、割当ておよび初期化済の記述子のポインタを戻します。成功した場合は、非NULL記述子またはLOBロケータが戻ります。エラー発生時に診断は利用できません。
このコールは、成功した場合はOCI_SUCCESSを、メモリー不足エラーが発生した場合はOCI_INVALID_HANDLEを戻します。
関連項目:
xtramem_szパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください
用途
割当て済記述子の割当てを解除します。
構文
sword OCIDescriptorFree ( void *descp,
ub4 type );
パラメータ
割り当てられた記述子です。
解放する記憶域の型を指定します。「OCIDescriptorAlloc()」にリストされている型を参照してください。
コメント
このコールにより、記述子に対応付けられた記憶域が解放されます。OCI_SUCCESSまたはOCI_INVALID_HANDLEを戻します。記述子はすべて明示的に割当てを解除できますが、環境ハンドルの割当てを解除すると、OCIで記述子の割当てが解除されます。
割当ておよび初期化済ハンドルのポインタを戻します。
用途
割当ておよび初期化済ハンドルのポインタを戻します。
構文
sword OCIHandleAlloc ( const void *parenth,
void **hndlpp,
ub4 type,
size_t xtramem_sz,
void **usrmempp );
パラメータ
環境ハンドルです。
ハンドルを戻します。
割り当てられるハンドルの型を指定します。使用可能なハンドルについては、表2-1で説明しています。
コメント
typeで指定された型に対応する、割当ておよび初期化済のハンドルのポインタを戻します。成功時には非NULLハンドルが戻ります。すべてのハンドルが、親ハンドルとして渡される環境ハンドルと対応付けて割り当てられます。
エラー発生時に診断は利用できません。このコールは、成功した場合はOCI_SUCCESSを、エラーが発生した場合はOCI_INVALID_HANDLEを戻します。
ハンドルは、OCIコールに渡す前にOCIHandleAlloc()を使用して割り当てる必要があります。
関連項目:
ユーザー・メモリー割当て用のxtramem_szパラメータの使用方法の詳細は、「ユーザー・メモリーの割当て」を参照してください
用途
このコールは、ハンドルの割当てを明示的に解除します。
構文
sword OCIHandleFree ( void *hndlp,
ub4 type );
パラメータ
OCIHandleAlloc()により割り当てられるハンドルです。
解放する記憶域の型を指定します。ハンドルについては、表2-1で説明しています。
コメント
このコールは、ハンドルに対応付けられている記憶域で、typeパラメータに指定された型に該当するものを解放します。
このコールは、OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERRORを戻します。
ハンドルはすべて明示的に割当て解除できます。OCIでは、親ハンドルの割当てを解除すると、子ハンドルの割当てが自動的に解除されます。
文ハンドルが解放されると、文ハンドルに関連付けられたカーソルがクローズされますが、実際のカーソルのクローズはサーバーへの次回のラウンドトリップまで延期されます。アプリケーションによりカーソルを即時にクローズする必要がある場合、OCIHandleFree()コールの後にOCIServerVersion()またはOCIPing()などのサーバー・ラウンドトリップ・コールを実行できます。
関連関数
記述ハンドルまたは文ハンドル内の指定位置にあるパラメータの記述子を戻します。
用途
記述ハンドルまたは文ハンドル内の指定位置にあるパラメータの記述子を戻します。
構文
sword OCIParamGet ( const void *hndlp,
ub4 htype,
OCIError *errhp,
void **parmdpp,
ub4 pos );
パラメータ
文ハンドルまたは記述ハンドルです。OCIParamGet()関数は、このハンドル用のパラメータ記述子を戻します。
hndlpパラメータに渡されるハンドルの型です。次の型が有効です。
OCI_DTYPE_PARAM、パラメータ記述子用
OCI_HTYPE_COMPLEXOBJECT、複合オブジェクト検索ハンドル用
OCI_HTYPE_STMT、文ハンドル用
コメント
このコールは、記述ハンドルまたは文ハンドル内の指定位置にあるパラメータの記述子を戻します。パラメータ記述子は、常にOCIライブラリによって内部的に割り当てられます。また、OCIDescriptorFree()を使用して解放できます。たとえば、文を実行するたびに同じ列のメタデータをフェッチする場合は、OCIParamGet()の各コール間でパラメータ記述子を明示的に解放しないかぎり、プログラムではメモリーがリークします。
関連項目:
パラメータ記述子の属性の詳細は、「ハンドルおよび記述子の属性」を参照してください
CORハンドルへの複合オブジェクト検索(COR)記述子を設定します。
用途
CORハンドルへの複合オブジェクト検索(COR)記述子を設定します。
構文
sword OCIParamSet ( void *hndlp,
ub4 htype,
OCIError *errhp,
const void *dscp,
ub4 dtyp,
ub4 pos );
パラメータ
コメント
CORハンドルにはOCIHandleAlloc()を、記述子にはOCIDescriptorAlloc()を使用して、それぞれ前もって割り当てておく必要があります。記述子の属性は、OCIAttrSet()を使用して設定します。
関連項目:
複合オブジェクト検索の詳細は、「複合オブジェクト検索」を参照してください
