表17-7は、この項で説明しているその他のOCI関数を示しています。
表17-7 その他の関数
関数 | 用途 |
---|---|
即時非同期ブレークを実行します。 |
|
クライアント・ライブラリのバージョンを戻します。 |
|
エラー・メッセージとOracleエラーを戻します。 |
|
|
|
パスワードを変更します。 |
|
接続とサーバーがアクティブであることを確認します。 |
|
|
|
ユニバーサル |
|
Oracleリリース文字列を取得します。 |
|
Oracleバージョン文字列を取得します。 |
|
サービス・コンテキスト・ハンドルを |
|
ハンドルに対して登録されたコールバックを識別します。 |
|
ユーザー作成コールバック関数を登録します。 |
即時非同期ブレークを実行します。
用途
サーバーに対応付けられて現在実行中であるOCI関数は即時(非同期)終了します。
構文
sword OCIBreak ( void *hndlp, OCIError *errhp );
パラメータ
コメント
このコールにより、サーバーに対応付けられて現在実行中であるOCI関数は即時(非同期)終了します。これは通常、サーバーで長時間実行されている処理中のOCIコールを停止するために使用します。これは、マルチスレッド・アプリケーションのユーザー・スレッドや、LinuxまたはUNIXシステムのユーザー・シグナル・ハンドラによって呼び出すことができます。ユーザー・シグナル・ハンドラで使用できるOCIコールはOCIBreak()
のみです。
注意:
OCIBreak()
は、Windows 2000やWindows XPなどのWindowsシステムで作動します。
このコールは、終了する関数を識別するためのパラメータとして、サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルを取得できます。
用途
実行時にクライアント・ライブラリの5桁のOracle Databaseバージョン番号を戻します。
構文
void OCIClientVersion ( sword *major_version, sword *minor_version, sword *update_num, sword *patch_num, sword *port_update_num );
パラメータ
コメント
OCIClientVersion()
は、アプリケーションの実行に使用しているOCIクライアントのバージョンを戻します。これは、アプリケーションが実行時に認識する際に役に立ちます。アプリケーションまたはテスト・プログラムは、この関数を呼び出すことにより、特定のOCIクライアント・システムのバージョンおよびパッチ・セットを確認できます。また、アプリケーションがクライアントのパッチ・セットのレベルに応じて異なるコードパスを使用する必要がある場合も、この関数が役に立ちます。
OCIClientVersion()
以外にも、OCI_MAJOR_VERSION
とOCI_MINOR_VERSION
という2つのマクロが定義されています。これらのマクロは、様々なOCIクライアントのバージョンで作成および実行できる汎用アプリケーションを作成するときに役に立ちます。たとえば、次のようにします。
.... #if (OCI_MAJOR_VERSION > 9) ... #endif ....
エラー・メッセージとOracle Databaseエラー・コードを戻します。
用途
指定されたバッファ内のエラー・メッセージとOracle Databaseエラー・コードを戻します。
構文
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
になります。
次のいずれかの定数を使用して、OCIErrorGet()
からの戻りメッセージの取得先となるエラー・メッセージ・バッファを定義します。
# define OCI_ERROR_MAXMSG_SIZE 1024 /* max size of an error message */ # define OCI_ERROR_MAXMSG_SIZE2 3072 /* new length max size of an error message */
戻りエラー・テキストに詳細な情報が含められるようにするにはOCI_ERROR_MAXMSG_SIZE2
を使用する必要があります。
たとえば、次のように実行できます。
char errorMesg[OCI_ERROR_MAXMSG_SIZE2];
その後にOCIErrorGet()
を渡します。また、同じOCI_ERROR_MAXMSG_SIZE2
値をOCIErrorGet()
コールに渡して、割り当てたバッファのサイズを指定する必要があります。
ハンドルのタイプ(OCI_HTYPE_ERROR
またはOCI_HTYPE_ENV
)です。
コメント
この関数は、SQL文はサポートしていません。hndlp
は、通常、エラー・ハンドルですが、環境ハンドルの場合もあります。メッセージは、常に環境ハンドルに設定されたエンコーディングで取得する必要があります。エラーに関して複数の診断レコードが存在する場合は、この関数を複数回コールできます。
OCI_ERROR
またはOCI_SUCCESS_WITH_INFO
を戻さないOCIコールの後にOCIErrorGet()
がコールされると、エラーが発生した先行OCIコールのエラー・メッセージがOCIErrorGet()
によって検出される可能性があります。この問題を回避するには、OCI_ERROR
またはOCI_SUCCESS_WITH_INFO
を戻すOCIコールの後にのみOCIErrorGet()
がコールされるようにする必要があります。
エラー・ハンドルは、最初はOCIHandleAlloc()
のコールで割り当てられます。
注意:
レコードがなくなる(OCI_NO_DATA
が戻される)まで、繰り返しOCIErrorGet()
をコールすると、複数の診断レコードを取り出すことができます。OCIErrorGet()
は、最大1個の診断レコードを戻します。
関連項目:
例
次のコード例は、OCIErrorGet()
を使用したエラー・チェック関数の単純な例です。
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以上のサービス・コンテキスト・ハンドルに変換します。
用途
バージョン7のLda_Def
をバージョン8以上のサービス・コンテキスト・ハンドルに変換します。
構文
sword OCILdaToSvcCtx ( OCISvcCtx **svchpp, OCIError *errhp, Lda_Def *ldap );
パラメータ
コメント
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が使用されているかどうかが判断されます。
リリース11.2サーバーでリリース12.1のクライアント・パスワードを変更する場合、OCIPasswordChange()
をコールする前にOCISessionBegin()をコールする必要があります。それ以外の場合はパスワード変更操作はORA-1017
エラーにより失敗します。
用途
サーバーへのラウンドトリップ・コールを行い、接続とサーバーがアクティブであることを確認します。
構文
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()コールが発行された場合に、OCIReset()をコールする必要があります。
関連関数
ユニバーサルROWID
を拡張文字(BASE64)表現に変換します。
用途
ユニバーサルROWID
を拡張文字(BASE64)表現に変換します。
構文
sword OCIRowidToChar ( OCIRowid *rowidDesc, OraText *outbfp, ub2 *outbflp OCIError *errhp );
パラメータ
OCIDescriptorAlloc()
で割り当てられ、前に実行されたSQL文で挿入されたROWID
記述子です。
このコールが正常に実行された後、文字表現が格納されるバッファへのポインタです。
出力バッファ長へのポインタです。実行前は、バッファ長にはoutbfp
のサイズが格納されています。実行後は、変換されたバイト数が格納されます。
変換時に切捨てがある場合、outbfp
には、変換を正常終了するために必要な長さが格納されます。エラーも戻されます。
エラー発生時の診断情報のためにOCIErrorGet()
に渡すエラー・ハンドルです。
コメント
この変換を行った後は、文字形式のROWID
をOCIBindByPos()
コールまたはOCIBindByName()
コールにバインドし、指定されたROWID
の行の問合せに使用できます。
OCI_UTF16ID
に設定されたパラメータcharset
およびncharset
を使用して、OCIEnvNlsCreate()
で環境を作成してある場合、関数OCIRowidToChar()
は想定されているUTF-16ではなくASCII表現の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 Databaseバージョン文字列を戻します。
構文
sword OCIServerVersion ( void *hndlp, OCIError *errhp, OraText *bufp, ub4 bufsz ub1 hndltype );
パラメータ
サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
バージョン情報が戻されるバッファです。
バイト数で示したバッファの長さです。
関数に渡されたハンドル型です。
コメント
このコールは、Oracle Databaseのバージョン文字列を戻します。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
バージョン8以上のサービス・コンテキスト・ハンドルとバージョン7のLda_Def
との間の切替えを行います。
用途
バージョン8以上のサービス・コンテキスト・ハンドルとバージョン7のLda_Def
との間の切替えを行います。
構文
sword OCISvcCtxToLda ( OCISvcCtx *srvhp, OCIError *errhp, Lda_Def *ldap );
パラメータ
コメント
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-8にリスト表示されています。
コールバックがいつ呼び出されるかを定義します。次のモードが有効です。
OCI_UCBTYPE_ENTRY
- このコールバックは、OCI関数の開始時に呼び出されます。
OCI_UCBTYPE_EXIT
- このコールバックは、OCI関数の終了前に呼び出されます。
OCI_UCBTYPE_REPLACE
- このコールバックでOCI_CONTINUE
以外が戻された場合は、次の置換コールバックおよびOCI関数に対するOCIコードはコールされません。かわりに、最後のコールバックの処理が開始されます。このパラメータの詳細は、「OCIUserCallbackRegister()
」を参照してください。
コールバック関数ポインタへのポインタです。fcode
、when
およびhndlp
の値に対して現在登録されている関数を戻します。この場合、コールバックが登録されていないときは、戻り値はNULL
です。
関連項目:
callbackp
のパラメータの詳細は、「OCIUserCallbackRegister()
」を参照してください
現在登録されているコールバックに対して戻されるコンテキストへのポインタです。
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コードまたは置換コールバックからの戻り値(置換コールバックがOCI_CONTINUE
を戻さず、結果的にOCIコードをバイパスした場合)が、このコールによって戻されます。
コールバックに対してNULL
値が渡された場合は、when
値および指定されたハンドルのコールバックが削除されます。これは、NULL
のucbDesc
を含む指定のucbDesc
値に対するコールバックの登録を解除する方法です。
コールバックのコンテキスト・ポインタです。
OCI関数の一意の関数コードです。これらは表17-8にリスト表示されています。
コールバックがいつ呼び出されるかを定義します。次のモードが有効です。
OCI_UCBTYPE_ENTRY
- このコールバックは、OCI関数の開始時に呼び出されます。
OCI_UCBTYPE_EXIT
- このコールバックは、OCI関数の終了前に呼び出されます。
OCI_UCBTYPE_REPLACE
- このコールバックでOCI_CONTINUE
以外が戻された場合は、次の置換コールバックおよびOCI関数に対するOCIコードはコールされません。かわりに、最後のコールバックの処理が開始されます。
コメント
この関数は、OCI環境にユーザー作成のコールバックを登録する場合に使用します。
このコールバックにより、アプリケーションで次の処理を行うことができます。
デバッグおよびパフォーマンス測定のためにOCIコールをトレースします。
選択したOCIコールの後に、前処理または後処理を追加実行します。
指定された関数のコードを、外部キー・データ・ソースで実行する専用コードに置き換えます。
OCIでは、最初のコールバック、置換コールバックおよび最後のコールバックがサポートされています。
この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-8にリスト表示されています。コールバックは、表17-3に示されている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-8 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 |
74 |
OCILobFileSetName |
11 |
OCISessionEnd |
43 |
OCILobAppend |
75 |
OCILobFileGetName |
12 |
OCIPasswordChange |
44 |
OCILobErase |
76 |
OCILogon |
13 |
OCIStmtPrepare |
45 |
OCILobGetLength |
77 |
OCILogoff |
14 |
(使用されていません) |
46 |
OCILobTrim |
78 |
OCILobDisableBuffering |
15 |
(使用されていません) |
47 |
OCILobRead |
79 |
OCILobFlushBuffer |
16 |
(使用されていません) |
48 |
OCILobWrite |
80 |
OCILobLoadFromFile |
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 |
表17-9 OCI関数コードの続き(97以降)
# | OCIルーチン | # | OCIルーチン | # | OCIルーチン |
---|---|---|---|---|---|
97 |
予約済 |
113 |
OCILobErase2 |
129 |
OCILobGetOptions |
98 |
予約済 |
114 |
OCILobGetLength2 |
130 |
OCILobSetOptions |
99 |
OCITransMultiPrepare |
115 |
OCILobLoadFromFile2 |
131 |
OCILobFragementInsert |
100 |
OCIConnectionPoolCreate |
116 |
OCILobRead2 |
132 |
OCILobFragementDelete |
101 |
OCIConnectionPoolDestroy |
117 |
OCILobTrim2 |
133 |
OCILobFragementMove |
102 |
OCILogon2 |
118 |
OCILobWrite2 |
134 |
OCILobFragementReplace |
103 |
OCIRowidToChar |
119 |
OCILobGetStorageLimit |
135 |
OCILobGetDeduplicateRegions |
104 |
OCISessionPoolCreate |
120 |
OCIDBStartup |
136 |
OCIAppCtxSet |
105 |
OCISessionPoolDestroy |
121 |
OCIDBShutdown |
137 |
OCIAppCtxClearAll |
106 |
OCISessionGet |
122 |
OCILobArrayRead |
138 |
OCILobGetContentType |
107 |
OCISessionRelease |
123 |
OCILobArrayWrite |
139 |
OCILobSetContentType |
108 |
OCIStmtPrepare2 |
124 |
OCIAQEnqStreaming |
||
109 |
OCIStmtRelease |
125 |
OCIAQGetReplayInfo |
||
110 |
OCIAQEnqArray |
126 |
OCIAQResetReplayInfo |
||
111 |
OCIAQDeqArray |
127 |
OCIArrayDescriptorAlloc |
||
112 |
OCILobCopy2 |
128 |
OCIArrayDescriptorFree |