| Oracle Call Interfaceプログラマーズ・ガイド 11g リリース1（11.1） E05677-02 |
|
 戻る |
 次へ |
この項では、その他のOCI関数について説明します。
表17-11 その他の関数
| 関数 | 用途 |
|---|---|
|
|
即時非同期ブレークを実行します。 |
|
|
クライアント・ライブラリのバージョンを戻します。 |
|
|
エラーを戻します。 |
|
|
|
|
|
パスワードを変更します。 |
|
|
接続とサーバーがアクティブであることを確認します。 |
|
|
|
|
|
ユニバーサルROWIDを拡張文字（BASE64）表現に変換します。 |
|
|
Oracleリリース文字列を取得します。 |
|
|
Oracleバージョン文字列を取得します。 |
|
|
サービス・コンテキスト・ハンドルを |
|
|
ハンドルに対して登録されたコールバックを識別します。 |
|
|
ユーザー作成コールバック関数を登録します。 |
用途
このコールにより、サーバーに対応付けられて現在実行中であるOCI関数は即時（非同期）終了します。
構文
sword OCIBreak ( void *hndlp,
OCIError *errhp );
パラメータ
サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コメント
このコールにより、サーバーに対応付けられて現在実行中であるOCI関数は即時（非同期）終了します。これは通常、サーバーで長時間実行されている処理中のOCIコールを停止するために使用します。これは、マルチスレッド・アプリケーションのユーザー・スレッドや、LinuxまたはUNIXシステムのユーザー・シグナル・ハンドラによって呼び出すことができます。ユーザー・シグナル・ハンドラで使用できるOCIコールはOCIBreak()のみです。
|
注意: OCIBreak()は、Windows 2000やWindows XPなどのWindowsシステムで作動します。 |
このコールは、終了する関数を識別するためのパラメータとして、サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルを取得できます。
関連関数
用途
実行時にクライアント・ライブラリの5桁のOracleバージョン番号を戻します。
構文
sword OCIClientVersion ( sword *major_version,
sword *minor_version,
sword *update_num,
sword *patch_num,
sword *port_update_num );
パラメータ
バージョンです。
リリースです。
更新番号です。
ライブラリに適用されたパッチ番号です。
ポート更新番号は、ライブラリに適用されたポート固有のパッチです。
コメント
OCIClientVersion()は、アプリケーションの実行に使用しているOCIクライアントのバージョンを戻します。これは、アプリケーションが実行時に使用されているOCIのバージョンを認識するのに役に立ちます。アプリケーションまたはテスト・プログラムは、この関数を呼び出すことにより、特定のOCIクライアント・システムのバージョンおよびパッチ・セットを確認できます。また、アプリケーションがクライアントのパッチ・セットのレベルに応じて異なるコードパスを使用する必要がある場合も、この関数が役に立ちます。
実行時にクライアントのバージョンを確認するときに役に立つOCIClientVersion()以外にも、OCI_MAJOR_VERSIONとOCI_MINOR_VERSIONという2つのマクロが用意されています。これらのマクロは、様々なOCIクライアントのバージョンで作成および実行できる汎用アプリケーションを作成するときに役に立ちます。たとえば、次のようにします。
.... #if (OCI_MAJOR_VERSION > 9) ... #endif ....
関連関数
用途
指定されたバッファ内のエラー・メッセージとOracleエラー・コードを戻します。
構文
sword OCIErrorGet ( void *hndlp,
ub4 recordno,
OraText *sqlstate,
sb4 *errcodep,
OraText *bufp,
ub4 bufsiz,
ub4 type );
パラメータ
エラー・ハンドルまたは環境ハンドル（OCIEnvCreate()およびOCIHandleAlloc()に関するエラー用）です。エラー・ハンドルの場合がほとんどです。
アプリケーションが情報を検索する検索先の状態レコードを示します。1から始まります。
リリース8.x以上ではサポートされていません。
戻されたエラー・コードです。
戻されたエラー・メッセージ・テキストです。
エラー・メッセージについて指定されたバッファのサイズ（バイト数）です。エラー・メッセージの長さがbufsizより長い場合、切り捨てられたエラー・メッセージ・テキストがbufpに戻されます。
typeがOCI_HTYPE_ERRORに設定されている場合、切捨て時のOCIErrorGet()からのリターン・コードはOCI_ERRORになります。クライアントは、より大きいバッファを指定し、OCIErrorGet()を再度コールできます。
メッセージ・テキスト全体を収容するのにbufsizが十分で、メッセージを正常にbufpにコピーできた場合、OCIErrorGet()のリターン・コードはOCI_SUCCESSになります。
ハンドルのタイプ（OCI_HTYPE_ERRORまたはOCI_HTYPE_ENV）です。
コメント
この関数は、SQL文はサポートしていません。hndlpは、ほとんどの場合、エラー・ハンドルですが、環境ハンドルの場合もあります。メッセージは、常に環境ハンドルに設定されたエンコーディングで取得する必要があります。エラーに関して複数の診断レコードが存在する場合は、この関数を複数回コールできます。
リターン・コードがOCI_SUCCESSである場合、OCIErrorGet()をコールしないでください。これをコールした場合、前に実行された文からのエラー・メッセージがOCIErrorGet()により見つかります。
エラー・ハンドルは、最初はOCIHandleAlloc()のコールで割り当てられます。
|
注意: レコードがなくなる（ OCI_NO_DATAが戻される）まで、繰り返しOCIErrorGet()をコールすると、複数の診断レコードを取り出すことができます。OCIErrorGet()は、最大1個の診断レコードを戻します。 |
例
OCIErrorGet()を使用したエラー・チェック関数の単純な例を次に示します。
static void checkerr(OCIError *errhp, sword status)
{
text errbuf[512];
ub4 buflen;
sb4 errcode;
if (status == OCI_SUCCESS) return;
switch (status)
{
case OCI_SUCCESS_WITH_INFO:
printf("Error - OCI_SUCCESS_WITH_INFO\n");
OCIErrorGet ((void *) errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
printf("Error - %s\n", errbuf);
break;
case OCI_NEED_DATA:
printf("Error - OCI_NEED_DATA\n");
break;
case OCI_NO_DATA:
printf("Error - OCI_NO_DATA\n");
break;
case OCI_ERROR:
OCIErrorGet ((void *) errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
printf("Error - %s\n", errbuf);
break;
case OCI_INVALID_HANDLE:
printf("Error - OCI_INVALID_HANDLE\n");
break;
case OCI_STILL_EXECUTING:
printf("Error - OCI_STILL_EXECUTING\n");
break;
case OCI_CONTINUE:
printf("Error - OCI_CONTINUE\n");
break;
default:
printf("Error - %d\n", status);
break;
}
}
関連関数
用途
バージョン7のLda_Defをバージョン8以上のサービス・コンテキスト・ハンドルに変換します。
構文
sword OCILdaToSvcCtx ( OCISvcCtx **svchpp,
OCIError *errhp,
Lda_Def *ldap );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
OCISvcCtxToLda()によりこのサービス・コンテキストから戻されたOracle7ログイン・データ領域（LDA）です。
コメント
Oracle7のLda_Defをバージョン8以上のサービス・コンテキスト・ハンドルに変換します。変換されたサービス・コンテキスト・ハンドルをOCISvcCtxToLda()関数に渡すと、このコールの逆の変換ができます。
OCILdaToSvcCtx()コールは、OCISvcCtxToLda()から取得したLda_Defをサービス・コンテキスト・ハンドルに戻してリセットする場合にかぎり使用します。このコールは、Lda_defをサービス・コンテキスト・ハンドルに戻して再開されたLda_defを変換する場合には使用できません。
サービス・コンテキストがLda_Defに変換されている場合は、Oracle7のコールしか使用できません。Lda_Defをサービス・コンテキストにリセットせずにバージョン8以上のOCIコールを行っても実行されません。
サーバー・ハンドルまたはサービス・コンテキスト・ハンドルのOCI_ATTR_IN_V8_MODE属性によって、アプリケーションでは、そのアプリケーションの現在の実行モードが、Oracleバージョン7か、Oracleバージョン8以上かを判断できます。
関連関数
用途
このコールは、アカウントのパスワードの変更を許可します。
構文
sword OCIPasswordChange ( OCISvcCtx *svchp,
OCIError *errhp,
const OraText *user_name,
ub4 usernm_len,
const OraText *opasswd,
ub4 opasswd_len,
const OraText *npasswd,
sb4 npasswd_len,
ub4 mode );
パラメータ
サービス・コンテキストへのハンドルです。サービス・コンテキスト・ハンドルは初期化され、サーバー・コンテキスト・ハンドルがそれに対応付けられている必要があります。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
ユーザー名を指定します。UTF-16エンコーディングが可能です。 サービス・コンテキストが認証ハンドルで初期化されている場合、ユーザー名はNULL文字で終了する必要があります。
user_nameで指定されたユーザー名文字列の長さで、エンコーディングに関係なくバイト数で表されます。usernm_lenは0（ゼロ）以外にしてください。
ユーザーの旧パスワードを指定します。UTF-16エンコーディングが可能です。
opasswdで指定された旧パスワード文字列の長さ（バイト単位）です。opasswd_lenは0（ゼロ）以外にしてください。
ユーザーの新規パスワードを指定します。UTF-16エンコーディングが可能です。パスワード複雑度検証ルーチンがユーザーのプロファイルに指定され、新規パスワードの複雑度が検証される場合、新規パスワードは検証関数の複雑度要件に一致する必要があります。
npasswdで指定された新規パスワード文字列の長さ（バイト単位）です。パスワード文字列を有効にするには、npasswd_lenは0（ゼロ）以外にしてください。
OCI_DEFAULT− 環境ハンドルの設定を使用します。
OCI_UTF16− 環境ハンドルの設定に関係なく、UTF-16エンコーディングを使用します。
user_name、opasswdおよびnpasswdで使用できるエンコーディングはUTF-16のみで、あとは使用するかしないかの選択のみです。
OCI_AUTH− ユーザー・セッション・コンテキストが作成されていない場合は、このコールによって作成され、パスワードが変更されます。コールが終了しても、ユーザー・セッション・コンテキストは消去されません。ユーザーはログインされたままです。
ユーザー・セッション・コンテキストがすでに作成されている場合は、パスワードの変更のみが実行され、このフラグによるセッションへの影響はありません。ユーザーはログインされたままです。
コメント
このコールは、アカウントのパスワードの変更を許可します。このコールはOCISessionBegin()に類似していますが、次の点が異なります。
ユーザー・セッションがすでに確立されている場合は、旧パスワードを使用しているアカウントを認証した後、パスワードを新規パスワードに変更します。
ユーザー・セッションが確立されていない場合は、ユーザー・セッションを確立して旧パスワードを使用しているアカウントを認証した後、パスワードを新規パスワードに変更します。
このコールは、アカウントのパスワードが期限切れになり、OCISessionBegin()が、エラー（ORA-28001）またはパスワードが期限切れであることを示す警告を戻したときに役に立ちます。
modeまたは環境ハンドルによって、UTF-16が使用されているかどうかが判断されます。
関連関数
用途
サーバーへのラウンドトリップ・コールを行い、接続とサーバーがアクティブであることを確認します。
構文
sword OCIPing ( OCISvcCtx *svchp,
OCIError *errhp,
ub4 mode );
パラメータ
サービス・コンテキストへのハンドルです。サービス・コンテキスト・ハンドルは初期化され、サーバー・コンテキスト・ハンドルがそれに対応付けられている必要があります。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コールのモードです。OCI_DEFAULTを使用します。
コメント
OCIPing()は、単にサーバーへのダミー・ラウンドトリップ・コールを行います。つまり、応答を求めてダミー・パケットがサーバーに送信されます。ラウンドトリップが完了すると、OCIPing()が戻されます。このコール自体に対してはサーバー操作は実行されません。
OCIPing()を使用して、サーバーに対する軽量コールを行うことができます。コールが正常に終了した場合は、接続とサーバーがアクティブであることを示します。コールがブロックされた場合、接続が別のスレッドによって使用されている可能性があります。このコールが失敗した場合、接続やサーバーに問題が発生している可能性があり、エラーをエラー・ハンドルから取り出すことができます。OCIPing()はラウンドトリップ・コールであるため、これを使用して、サーバーに対する保留状態のOCIクライアント側のコール（存在する場合）をすべてフラッシュすることもできます。たとえば、OCIHandleFree()の後にOCIPing()をコールすることにより、保留状態のコールの実行を強制し、バックエンド・カーソルをクローズすることができます。アプリケーションがバックエンド・カーソルを即時にクローズする必要がある場合、このコールが役に立ちます。
関連関数
用途
割り込まれた非同期操作およびプロトコルをリセットします。非ブロック操作の処理中にOCIBreak()コールが発行された場合に、コールする必要があります。
構文
sword OCIReset ( void *hndlp,
OCIError *errhp );
パラメータ
サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コメント
このコールは、非ブロック・モードでのみコールされます。割り込まれた非同期操作およびプロトコルをリセットします。非ブロック操作の処理中にOCIBreak()コールが発行された場合に、コールする必要があります。
関連関数
用途
ユニバーサルROWIDを拡張文字（BASE64）表現に変換します。
構文
sword OCIRowidToChar ( OCIRowid *rowidDesc,
OraText *outbfp,
ub2 *outbflp
OCIError *errhp );
パラメータ
OCIDescriptorAlloc()で割り当てられ、前に実行されたSQL文で挿入されたROWID記述子です。
このコールが正常に実行された後、文字表現が格納されるバッファへのポインタです。
出力バッファ長へのポインタです。実行前は、バッファ長にはoutbfpのサイズが格納されています。実行後は、変換されたバイト数が格納されます。
変換時の切捨てに備えて、outbfpには、変換を正常終了するために必要な長さが格納されています。エラーも戻されます。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コメント
この変換を行った後は、文字形式のROWIDをOCIBindByPos()コールまたはOCIBindByName()コールにバインドし、指定されたROWIDの行の問合せに使用できます。
用途
Oracle Databaseサーバーのリリース文字列を戻します。
構文
sword OCIServerRelease ( void *hndlp,
OCIError *errhp,
OraText *bufp,
ub4 bufsz
ub1 hndltype
ub4 *version );
パラメータ
サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
バージョン情報が戻されるバッファです。
バイト数で示したバッファの長さです。
関数に渡されたハンドル型です。
整数書式でのバージョンです。
コメント
バッファ・ポインタbufpは、NULL終端文字を含めた最大bufszの文字列表現のリリース情報を指し示しています。 バッファ・サイズが小さすぎると、この結果はbufszサイズに切り捨てられます。 version引数には、整数書式の5桁のOracle Databaseバージョンが含まれます。これは、次のマクロを使用して取り出せます。
#define MAJOR_NUMVSN(v) ((sword)(((v) >> 24) & 0x000000FF)) /* version number */ #define MINOR_NUMRLS(v) ((sword)(((v) >> 20) & 0x0000000F)) /* release number */ #define UPDATE_NUMUPD(v) ((sword)(((v) >> 12) & 0x000000FF)) /* update number */ #define PORT_REL_NUMPRL(v) ((sword)(((v) >> 8) & 0x0000000F)) /* port release number */ #define PORT_UPDATE_NUMPUP(v) ((sword)(((v) >> 0) & 0x000000FF)) /* port update number */
関連関数
用途
Oracleサーバーのバージョン文字列を戻します。
構文
sword OCIServerVersion ( void *hndlp,
OCIError *errhp,
OraText *bufp,
ub4 bufsz
ub1 hndltype );
パラメータ
サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
バージョン情報が戻されるバッファです。
バイト数で示したバッファの長さです。
関数に渡されたハンドル型です。
コメント
このコールは、Oracleサーバーのバージョン文字列を戻します。Unicodeの文字列が可能です（環境ハンドルでUnicodeと判断された場合）。
たとえば、アプリケーションが8.1.5 SunOSサーバー上で実行されている場合は、次のようなバージョン文字列がbufpに戻されます。
Oracle8i Enterprise Edition Release 8.1.5.0.0 - Production With the Partitioning and Java options PL/SQL Release 8.1.5.0.0 - Production
関連関数
OCIErrorGet()、OCIClientVersion()
用途
バージョン8以上のサービス・コンテキスト・ハンドルとバージョン7のLda_Defとの間の切替えを行います。
構文
sword OCISvcCtxToLda ( OCISvcCtx *srvhp,
OCIError *errhp,
Lda_Def *ldap );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
このコールによって初期化される、Oracle7スタイルのOCIコールのためのログイン・データ領域（LDA）です。
コメント
OCIバージョン8以上のサービス・コンテキスト・ハンドルとOracle7のLda_Defとの間の切替えを行います。
この関数は、サービス・コンテキストが正常に初期化された後でのみコールできます。
Lda_Defに変換した後のサービス・コンテキストは、リリース7.xのOCIコール（たとえば、obindps()、ofen()）で使用できます。
同じサーバー・ハンドルを共有する複数のサービス・コンテキストがある場合、Oracle7モードでは常に1つのサービス・コンテキストのみ可能です。
変換されたLda_DefをOCILdaToSvcCtx()関数に渡すと、このコールの逆の変換ができます。
サーバー・ハンドルまたはサービス・コンテキスト・ハンドルのOCI_ATTR_IN_V8_MODE属性によって、アプリケーションでは、そのアプリケーションの現在の実行モードが、Oracleバージョン7か、Oracleバージョン8以上かを判断できます。
関連関数
用途
ハンドルに対して登録されたコールバックを判断します。
構文
sword OCIUserCallbackGet ( void *hndlp,
ub4 type,
void *ehndlp,
ub4 fcode,
ub4 when,
OCIUserCallback (*callbackp)
(
void *ctxp,
void *hndlp,
ub4 type,
ub4 fcode,
ub1 when,
sword returnCode,
ub4 *errnop,
va_list arglist
),
void **ctxpp,
OCIUcb *ucbDesc );
パラメータ
typeパラメータによって指定された型のハンドルです。
ハンドル・タイプです。次のハンドル・タイプが有効です。
OCI_HTYPE_ENV− このコールバックは、環境ハンドル上で生成されたfcodeによって指定される関数の、すべてのコールに対して登録されます。
OCIエラー・ハンドルまたは環境ハンドルです。エラーがある場合は、ehndlpに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。
OCI関数の一意の関数コードです。これらの関数については、表17-12「OCI関数コード」のリストを参照してください。
コールバックがいつ呼び出されるかを定義します。次のモードが有効です。
OCI_UCBTYPE_ENTRY− このコールバックは、OCI関数の開始時に呼び出されます。
OCI_UCBTYPE_EXIT− このコールバックは、OCI関数の終了前に呼び出されます。
OCI_UCBTYPE_REPLACE− このコールバックでOCI_CONTINUE以外が戻された場合は、次の置換コールバックおよびOCI関数に対するOCIコードはコールされません。かわりに、最後のコールバックの処理が開始されます。このパラメータの詳細は、「OCIUserCallbackRegister()」を参照してください。
コールバック関数ポインタへのポインタです。fcode、whenおよびhndlpの値に対して現在登録されている関数を戻します。 この場合、コールバックが登録されていないときは、戻り値はNULLです。
現在登録されているコールバックに対して戻されるコンテキストへのポインタです。
OCI指定の記述子です。この記述子は、環境コールバックでOCIによって渡されます。この記述子には、コールバックを登録する場合の優先度が格納されます。ucbDescパラメータにNULLを指定すると、このコールバックの優先度が最も高くなります。
パッケージで動的に登録されたユーザー・コールバックとは対照的に、静的に登録されたユーザー・コールバックは、使用するucb記述子がないため、NULL記述子を使用します。
コメント
この関数は、特定のハンドルに対して登録されているコールバックを検索します。
関連関数
用途
ユーザー作成コールバック関数を登録します。
構文
sword OCIUserCallbackRegister ( void *hndlp,
ub4 type,
void *ehndlp,
OCIUserCallback (callback)
(
void *ctxp,
void *hndlp,
ub4 type,
ub4 fcode,
ub1 when,
sword returnCode,
ub4 *errnop,
va_list arglist
),
void *ctxp,
ub4 fcode,
ub4 when,
OCIUcb *ucbDesc );
パラメータ
typeパラメータによって指定された型のハンドルです。
ハンドル・タイプです。次のハンドル・タイプが有効です。
OCI_HTYPE_ENV− このコールバックは、環境ハンドル上で生成されたfcodeによって指定される関数の、すべてのコールに対して登録されます。
OCIエラー・ハンドルまたは環境ハンドルです。エラーがある場合は、ehndlpに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。OCIEnvCallbackでは、エラー・ハンドルを使用することができないため、環境ハンドルはehndlpとして渡されます。
コールバック関数ポインタです。OCIUserCallback関数プロトタイプの変数引数のリストは、OCI関数に渡されるパラメータです。OCIUserCallbackのtypedefについては、後で説明します。
最初のコールバックでOCI_CONTINUE以外が戻された場合、リターン・コードは後続の最初のコールバックまたは置換コールバック（存在する場合）に渡されます。このコールバックが最新の最初のコールバックで、置換コールバックがない場合、OCIコードは実行されてリターン・コードは無視されます。
置換コールバックがOCI_CONTINUE以外を戻した場合、後続の置換コールバックおよびOCIコードは迂回されて最後のコールバックの処理が開始されます。
最後のコールバックからOCI_CONTINUE以外が戻された場合は、OCI関数から戻り値が戻されます。OCI_CONTINUEが戻された場合は、OCIコードまたは置換コールバック（置換コールバックがOCI_CONTINUEを戻さずにOCIコードを迂回した場合）の戻り値がコールから戻されます。
コールバックに対してNULL値が渡された場合は、when値および指定されたハンドルのコールバックが削除されます。これは、NULLのucbDescを含む指定のucbDesc値に対するコールバックを登録解除する方法です。
コールバックのコンテキスト・ポインタです。
OCI関数の一意の関数コードです。これらの関数については、表17-12「OCI関数コード」のリストを参照してください。
コールバックがいつ呼び出されるかを定義します。次のモードが有効です。
OCI_UCBTYPE_ENTRY− このコールバックは、OCI関数の開始時に呼び出されます。
OCI_UCBTYPE_EXIT− このコールバックは、OCI関数の終了前に呼び出されます。
OCI_UCBTYPE_REPLACE− このコールバックでOCI_CONTINUE以外が戻された場合は、次の置換コールバックおよびOCI関数に対するOCIコードはコールされません。かわりに、最後のコールバックの処理が開始されます。
OCI指定の記述子です。この記述子は、環境コールバックでOCIによって渡されます。この記述子には、コールバックを登録する場合の優先度が格納されます。ucbDescパラメータにNULLを指定すると、このコールバックの優先度が最も高くなります。
パッケージで動的に登録されたユーザー・コールバックとは対照的に、静的に登録されたユーザー・コールバックは、使用するucb記述子がないため、NULL記述子を使用します。
コメント
この関数は、OCI環境にユーザー作成のコールバックを登録する場合に使用します。
このコールバックにより、アプリケーションで次の処理を行うことができます。
デバッグおよびパフォーマンス測定のためにOCIコールをトレースします。
選択したOCIコールの後に、前処理または後処理を追加実行します。
指定された関数のコードを、外部キー・データ・ソースで実行するコードに置き換えます。
OCIでは、最初のコールバック、置換コールバックおよび最後のコールバックの3種類のコールバックがサポートされています。
この3種類のコールバックは、モードOCI_UCBTYPE_ENTRY、OCI_UCBTYPE_REPLACEおよびOCI_UCBTYPE_EXITで識別されます。
次の制御フローがあります。
最初のコールバックの実行
置換コールバックの実行
OCIコードの実行
最後のコールバックの実行
最初のコールバックは、プログラムがOCI関数に入るときに実行されます。
置換コールバックは、最初のコールバック実行の後に実行されます。置換コールバックからOCI_CONTINUEの値が戻された場合は、後続の置換コールバックまたは通常のOCI固有のコードが実行されます。置換コールバックからOCI_CONTINUE以外の値が戻される場合は、後続の置換コールバックおよびOCIコードは実行されません。
OCI関数が正常に実行された後または置換コールバックからOCI_CONTINUE以外が戻された後は、プログラムの制御は最後のコールバック（登録されている場合）に移ります。
置換コールバックまたは最後のコールバックからOCI_CONTINUE以外が戻された場合は、コールバックからのリターン・コードは、対応付けられたOCIコールから戻されます。
ハンドルに対して登録されているコールバックを検索するには、OCIUserCallbackGet()を使用します。
OCIUserCallback typedefのプロトタイプは次のとおりです。
typedef sword (*OCIUserCallback)
(void *ctxp,
void *hndlp,
ub4 type,
ub4 fcode,
ub4 when,
sword returnCode,
sb4 *errnop,
va_list arglist );
OCIUserCallback関数プロトタイプへのパラメータは次のとおりです。
登録コールバック関数内でctxpとして渡されるコンテキストです。
typeパラメータで指定された型のハンドルです。コールバックを呼び出すためのハンドルです。OCI_HTYPE_ENV型以外は使用しないため、環境ハンドルenvはここに渡されます。
hndlpに対して登録された型です。次のハンドル・タイプが有効です。
OCI_HTYPE_ENV− このコールバックは、環境ハンドル上で生成されたfcodeによって指定される関数の、すべてのコールに対して登録されます。
OCIコールの関数コードです。これらの関数については、表17-12「OCI関数コード」のリストを参照してください。コールバックは、表17-7「アドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数」に示されているOCIコールに対してのみ登録できます。
コールバックのwhen値です。
直前のコールバックまたはOCIコードからのリターン・コードです。1回目の最初のコールバックでは、OCI_SUCCESSが常に渡されます。後続のコールバックでは、OCIコードまたは前のコールバックからのリターン・コードが渡されます。
1回目の最初のコールバックをコールすると、*errnopの入力値は0（ゼロ）になります。コールバックによりOCI_CONTINUE以外の値が戻される場合は、*errnopにエラー番号を設定する必要があります。この値は、OCIコール内に渡されるエラー・ハンドルで設定されます。
後続のすべてのコールバックの場合、*errnopの入力値はエラー・ハンドル内のエラー番号の値です。このため、前のコールバックからOCI_CONTINUEが戻されなかった場合、前のコールバックからの*errnopの出力値はエラー・ハンドル内の値となり、この値が、ここで後続のコールバックに渡されます。反対に、前のコールバックによってOCI_CONTINUEが戻された場合、エラー・ハンドル内の値はすべてここで渡されます。
*errnopにOracle以外のエラー番号が戻された場合は、そのエラー番号に対して適切なテキストを戻すために、コールバックをOCIErrorGet()関数に登録する必要があります。
これらは引数の変数値として渡される、OCIコールへのパラメータです。これらのパラメータは、va_argを使用して間接参照する必要があります。ユーザー・コールバックのデモ・プログラムを参照してください。
表17-12 OCI関数コード
| # |
OCIルーチン | # |
OCIルーチン | # |
OCIルーチン |
|---|---|---|---|---|---|
|
1 |
OCIInitialize |
33 |
OCITransStart |
65 |
OCIDefineByPos |
|
2 |
OCIHandleAlloc |
34 |
OCITransDetach |
66 |
OCIBindByPos |
|
3 |
OCIHandleFree |
35 |
OCITransCommit |
67 |
OCIBindByName |
|
4 |
OCIDescriptorAlloc |
36 |
（使用されていません） |
68 |
OCILobAssign |
|
5 |
OCIDescriptorFree |
37 |
OCIErrorGet |
69 |
OCILobIsEqual |
|
6 |
OCIEnvInit |
38 |
OCILobFileOpen |
70 |
OCILobLocatorIsInit |
|
7 |
OCIServerAttach |
39 |
OCILobFileClose |
71 |
OCILobEnableBuffering |
|
8 |
OCIServerDetach |
40 |
（使用されていません） |
72 |
OCILobCharSetID |
|
9 |
（使用されていません） |
41 |
（使用されていません） |
73 |
OCILobCharSetForm |
|
10 |
OCISessionBegin |
42 |
OCILobCopy、OCILobCopy2 |
74 |
OCILobFileSetName |
|
11 |
OCISessionEnd |
43 |
OCILobAppend |
75 |
OCILobFileGetName |
|
12 |
OCIPasswordChange |
44 |
OCILobErase、OCILobErase2 |
76 |
OCILogon |
|
13 |
OCIStmtPrepare |
45 |
OCILobGetLength、OCILobGetLength2 |
77 |
OCILogoff |
|
14 |
（使用されていません） |
46 |
OCILobTrim、OCILobTrim2 |
78 |
OCILobDisableBuffering |
|
15 |
（使用されていません） |
47 |
OCILobRead、OCILobRead2 |
79 |
OCILobFlushBuffer |
|
16 |
（使用されていません） |
48 |
OCILobWrite、OCILobWrite2 |
80 |
OCILobLoadFromFile、OCILobLoadFromFile2 |
|
17 |
OCIBindDynamic |
49 |
（使用されていません） |
81 |
OCILobOpen |
|
18 |
OCIBindObject |
50 |
OCIBreak |
82 |
OCILobClose |
|
19 |
（使用されていません） |
51 |
OCIServerVersion |
83 |
OCILobIsOpen |
|
20 |
OCIBindArrayOfStruct |
52 |
（使用されていません） |
84 |
OCILobFileIsOpen |
|
21 |
OCIStmtExecute |
53 |
（使用されていません） |
85 |
OCILobFileExists |
|
22 |
（使用されていません） |
54 |
OCIAttrGet |
86 |
OCILobFileCloseAll |
|
23 |
（使用されていません） |
55 |
OCIAttrSet |
87 |
OCILobCreateTemporary |
|
24 |
（使用されていません） |
56 |
OCIParamSet |
88 |
OCILobFreeTemporary |
|
25 |
OCIDefineObject |
57 |
OCIParamGet |
89 |
OCILobIsTemporary |
|
26 |
OCIDefineDynamic |
58 |
OCIStmtGetPieceInfo |
90 |
OCIAQEnq |
|
27 |
OCIDefineArrayOfStruct |
59 |
OCILdaToSvcCtx |
91 |
OCIAQDeq |
|
28 |
OCIStmtFetch |
60 |
（使用されていません） |
92 |
OCIReset |
|
29 |
OCIStmtGetBindInfo |
61 |
OCIStmtSetPieceInfo |
93 |
OCISvcCtxToLda |
|
30 |
（使用されていません） |
62 |
OCITransForget |
94 |
OCILobLocatorAssign |
|
31 |
（使用されていません） |
63 |
OCITransPrepare |
95 |
（使用されていません） |
|
32 |
OCIDescribeAny |
64 |
OCITransRollback |
96 |
OCIAQListen |
関連関数
