表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);
パラメータ
環境ハンドルです。
必要な型を持つ記述子の連続配列へのポインタを戻します。
割り当てられる記述子またはLOBロケータの型を指定します。型のリストは、「OCIDescriptorAlloc()」を参照してください。
割り当てる記述子の数を指定します。指定した数の記述子をコールで割り当てることができなければ、エラーがスローされます。
記述子の存続期間中アプリケーションで使用するために割り当てられるユーザー・メモリーの量を指定します。
記述子の存続期間中コールによってユーザー用に割り当てられた、サイズxtramem_sz
のユーザー・メモリーのポインタを戻します。
例
例16-7を変更して、多数の記述子を割り当てることができます。
コメント
記述子を割り当てるときに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
へのポインタを渡して文字列の長さを取得する必要があります。
取り出される属性のタイプです。ハンドル・タイプとその読取り可能な属性は、付録Aにリストされています。
エラー発生時の診断情報のために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()に渡すエラー・ハンドルです。
構文
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型の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
のユーザー・メモリーのポインタを戻します。
構文
sword OCIHandleAlloc ( const void *parenth, void **hndlpp, ub4 type, size_t xtramem_sz, void **usrmempp );
パラメータ
環境ハンドルです。
ハンドルを戻します。
割り当てられるハンドルの型を指定します。使用可能なハンドルについては、表2-1で説明しています。
割り当てられるユーザー・メモリーの量を指定します。
コールによりユーザーに割り当てられた、サイズxtramem_sz
のユーザー・メモリーのポインタを戻します。
パラメータ
OCIHandleAlloc()により割り当てられるハンドルです。
解放する記憶域の型を指定します。ハンドルについては、表2-1で説明しています。
コメント
このコールは、ハンドルに対応付けられている記憶域で、type
パラメータに指定された型に該当するものを解放します。
このコールは、OCI_SUCCESS
、OCI_INVALID_HANDLE
またはOCI_ERROR
を戻します。
ハンドルはすべて明示的に割当て解除できます。OCIでは、親ハンドルの割当てを解除すると、子ハンドルの割当てが自動的に解除されます。
文ハンドルが解放されると、文ハンドルに関連付けられたカーソルがクローズされますが、実際のカーソルのクローズはサーバーへの次回のラウンドトリップまで延期されます。アプリケーションによりカーソルを即時にクローズする必要がある場合、OCIHandleFree()
コールの後にOCIServerVersion()またはOCIPing()などのサーバー・ラウンドトリップ・コールを実行できます。
パラメータ
文ハンドルまたは記述ハンドルです。OCIParamGet()
関数は、このハンドル用のパラメータ記述子を戻します。
hndlp
パラメータに渡されるハンドルの型です。次の型が有効です。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
ハンドル・タイプOCI_DTYPE_PARAM
の、pos
パラメータで指定された位置におけるパラメータの記述子です。
文ハンドルまたは記述ハンドルにおける位置番号です。この位置にあるパラメータ記述子が戻ります。
注意: 指定位置にパラメータ記述子がない場合は、OCI_ERROR が戻されます。 |
コメント
このコールは、記述ハンドルまたは文ハンドル内の指定位置にあるパラメータの記述子を戻します。パラメータ記述子は、常にOCIライブラリによって内部的に割り当てられます。また、OCIDescriptorFree()を使用して解放できます。たとえば、文を実行するたびに同じ列のメタデータをフェッチする場合は、OCIParamGet()
の各コール間でパラメータ記述子を明示的に解放しないかぎり、プログラムではメモリーがリークします。
構文
sword OCIParamSet ( void *hndlp, ub4 htype, OCIError *errhp, const void *dscp, ub4 dtyp, ub4 pos );
パラメータ
ハンドル・ポインタです。
ハンドル・タイプです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
複合オブジェクト検索記述子ポインタです。
記述子型です。COR記述子の型は、OCI_DTYPE_COMPLEXOBJECTCOMP
です。
位置番号です。
コメント
CORハンドルにはOCIHandleAlloc()を、記述子にはOCIDescriptorAlloc()を使用して、それぞれ前もって割り当てておく必要があります。記述子の属性は、OCIAttrSet()を使用して設定します。