26.9 その他の関数
その他のOCI関数をリストし、説明します。
表26-8は、この項で説明しているその他のOCI関数を示しています。
表26-8 その他の関数
関数 | 用途 |
---|---|
即時非同期ブレークを実行します。 |
|
クライアント・ライブラリのバージョンを戻します。 |
|
エラー・メッセージとOracleエラーを戻します。 |
|
|
|
パスワードを変更します。 |
|
接続とサーバーがアクティブであることを確認します。 |
|
|
|
ユニバーサル |
|
Oracleリリース文字列を取得します。 |
|
Oracleバージョン文字列を取得します。 |
|
サービス・コンテキスト・ハンドルを |
|
ハンドルに対して登録されたコールバックを識別します。 |
|
ユーザー作成コールバック関数を登録します。 |
26.9.1 OCIBreak()
即時非同期ブレークを実行します。
用途
サーバーに対応付けられて現在実行中であるOCI関数は即時(非同期)終了します。
構文
sword OCIBreak ( void *hndlp, OCIError *errhp );
パラメータ
コメント
このコールにより、サーバーに対応付けられて現在実行中であるOCI関数は即時(非同期)終了します。これは通常、サーバーで長時間実行されている処理中のOCIコールを停止するために使用します。これは、マルチスレッド・アプリケーションのユーザー・スレッドや、LinuxまたはUNIXシステムのユーザー・シグナル・ハンドラによって呼び出すことができます。ユーザー・シグナル・ハンドラで使用できるOCIコールはOCIBreak()
のみです。
注意:
OCIBreak()
は、Windows 2000やWindows XPなどのWindowsシステムで作動します。
このコールは、終了する関数を識別するためのパラメータとして、サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルを取得できます。
26.9.2 OCIClientVersion()
クライアント・ライブラリのバージョンを戻します。
用途
実行時にクライアント・ライブラリの5桁のOracle Databaseバージョン番号を戻します。
構文
void OCIClientVersion ( sword *featureRelease, sword *releaseUpdate, sword *releaseUpdateRevision, sword *increment, sword *ext );
パラメータ
コメント
リリース18c、バージョン18.1以上では、データベース・バージョンの各コンポーネントを抽出するための新しいクライアント・マクロが5つあります。これらのマクロは、OCIServerRelease2()
により戻されたエンコード済データベース・バージョン番号と一緒に使用して、データベース・バージョンの5つのコンポーネントをそれぞれ抽出することを目的にしています。これらのマクロは、バージョン18.1以上では、新しいリリース・ネーミング計画に従って名前が付けられています。バージョン番号から抽出される5桁は、<feature release>.<release update>.<release update revision>.<release update increment>.<extension>
です。たとえば、18.1.1.1.1は、機能リリース18、リリース更新1、リリース更新バージョン1、リリース更新増分1、エクステンション1を表します。featureRelease()
は、アプリケーションが実行されているOCIクライアントの機能リリースの年を返します。これは、アプリケーションが実行時に認識する際に役に立ちます。アプリケーションまたはテスト・プログラムは、この関数を呼び出すことにより、特定のOCIクライアント・システムのバージョンおよびパッチ・セットを確認できます。また、アプリケーションがクライアントのパッチ・セットのレベルに応じて異なるコードパスを使用する必要がある場合も、この関数が役に立ちます。
これらのマクロは、様々なOCIクライアントのバージョンで作成および実行できる汎用アプリケーションを作成するときに役に立ちます。たとえば、次のようにします。
.... #if (featureRelease > 12) ... #endif ....
OCIServerRelease()
によって戻されるエンコード済バージョン番号からデータベース・バージョンの対応する5つのコンポーネントを抽出するために使用できます。ただし、その場合も、コンポーネントは次の番号に一致します。
-
バージョン番号
-
リリース番号
-
更新番号
-
ポーティング・リリース番号
-
ポーティング更新番号
関連トピック
26.9.3 OCIErrorGet()
エラー・メッセージとOracle Databaseエラー・コードを戻します。
用途
指定されたバッファ内のエラー・メッセージとOracle Databaseエラー・コードを戻します。
構文
sword OCIErrorGet ( void *hndlp, ub4 recordno, OraText *sqlstate, sb4 *errcodep, OraText *bufp, ub4 bufsiz, ub4 type );
パラメータ
- hndlp (IN)
-
エラー・ハンドル(通常)、または環境ハンドル(
OCIEnvCreate()
およびOCIHandleAlloc()
に関するエラー用)です。 - recordno (IN)
-
アプリケーションが情報を検索する検索先の状態レコードを示します。1から始まります。
- sqlstate (OUT)
-
リリース8.x以上ではサポートされていません。
- errcodep (OUT)
-
戻されたエラー・コードです。
- bufp (OUT)
-
戻されたエラー・メッセージ・テキストです。
- bufsiz (IN)
-
エラー・メッセージについて指定されたバッファのサイズ(バイト数)です。エラー・メッセージの長さが
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()
コールに渡して、割り当てたバッファのサイズを指定する必要があります。 - type (IN)
-
ハンドルのタイプ(
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()
のコールで割り当てられます。
注意:
OCIErrorGet()
関数は、少なくとも1つの診断レコードを返します。レコードがなくなり、メソッドがOCI_NO_DATA
を返すまで、OCIErrorGet()
メソッドを繰り返しコールすることで複数の診断レコードを取得できます。
関連項目:
例
次のコード例は、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; } }
関連トピック
26.9.4 OCILdaToSvcCtx()
バージョン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以上かを判断できます。
26.9.5 OCIPasswordChange()
アカウントのパスワードを変更します。
用途
アカウントのパスワードの変更を許可します。
構文
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 );
パラメータ
- svchp (IN/OUT)
-
サービス・コンテキストへのハンドルです。サービス・コンテキスト・ハンドルは初期化され、サーバー・コンテキスト・ハンドルがそれに対応付けられている必要があります。
- errhp (IN)
-
エラー発生時の診断情報のために
OCIErrorGet()
に渡すエラー・ハンドルです。 - user_name (IN)
-
ユーザー名を指定します。UTF-16エンコーディングが可能です。サービス・コンテキストが認証ハンドルで初期化されている場合は、最後の文字を
NULL
文字にする必要があります。 - usernm_len (IN)
-
エンコーディングに関係なく、
user_name
にバイト数で指定されたユーザー名文字列の長さです。usernm_len
の値は0 (ゼロ)以外にしてください。 - opasswd (IN)
-
ユーザーの旧パスワードを指定します。UTF-16エンコーディングが可能です。
- opasswd_len (IN)
-
opasswd
で指定された旧パスワード文字列の長さ(バイト単位)です。opasswd_len
の値は0 (ゼロ)以外にしてください。 - npasswd (IN)
-
ユーザーの新規パスワードを指定します。UTF-16エンコーディングが可能です。パスワード複雑度検証ルーチンがユーザーのプロファイルに指定され、新規パスワードの複雑度が検証される場合、新規パスワードは検証関数の複雑度要件に一致する必要があります。
- npasswd_len (IN)
-
npasswd
で指定された新規パスワード文字列の長さ(バイト単位)です。パスワード文字列を有効にするには、npasswd_len
は0 (ゼロ)以外にしてください。 - mode (IN)
-
OCI_DEFAULT
- 環境ハンドルの設定を使用します。-
OCI_UTF16
- 環境ハンドルの設定に関係なく、UTF-16エンコーディングを使用します。user_name
、opasswd
およびnpasswd
で使用できるエンコーディングはUTF-16のみで、あとは使用するかしないかの選択のみです。 -
OCI_AUTH
- ユーザー・セッション・コンテキストが作成されていない場合は、このフラグを使用したコールによって作成され、パスワードが変更されます。コールが終了しても、ユーザー・セッション・コンテキストは消去されません。ユーザーはログインされたままです。ユーザー・セッション・コンテキストが作成されている場合は、このフラグを使用したコールによってパスワードの変更のみが実行され、セッションへの影響はありません。ユーザーはログインされたままです。
OCI_AUTH
モードは、この項でリストされている任意のOCI_CPW_*
モードと組み合せて使用し、パスワード変更前のログインで、期限切れのユーザー・アカウントに対してそれぞれの管理セッションを確立できます。 -
OCI_CPW_SYSDBA
- このモードでは、SYSDBA
アクセス用に認証されます。 -
OCI_CPW_SYSOPER
- このモードでは、SYSOPER
アクセス用に認証されます。 -
OCI_CPW_SYSASM
- このモードでは、SYSASM
アクセス用に認証されます。 -
OCI_CPW_SYSBKP
- このモードでは、SYSBKP
アクセス用に認証されます。 -
OCI_CPW_SYSDGD
- このモードでは、SYSDGD
アクセス用に認証されます。 -
OCI_CPW_SYSKMT
- このモードでは、SYSKMT
アクセス用に認証されます。
-
コメント
このコールは、アカウントのパスワードの変更を許可します。このコールはOCISessionBegin()
に類似していますが、次の点が異なります。
-
ユーザー・セッションが確立されている場合、このコールでは、旧パスワードを使用しているアカウントを認証した後、パスワードを新規パスワードに変更します。
-
ユーザー・セッションが確立されていない場合、このコールでは、ユーザー・セッションを確立して旧パスワードを使用しているアカウントを認証した後、パスワードを新規パスワードに変更します。
このコールは、アカウントのパスワードが期限切れになり、OCISessionBegin()
が、エラー(ORA-28001)またはパスワードが期限切れであることを示す警告を戻したときに役に立ちます。
mode
または環境ハンドルによって、UTF-16が使用されているかどうかが判断されます。
リリース11.2サーバーでリリース12.1以上のクライアント・パスワードを変更する場合、OCIPasswordChange()
をコールする前にOCISessionBegin()
をコールする必要があります。それ以外の場合はパスワード変更操作はORA-1017
エラーにより失敗します。
関連トピック
26.9.6 OCIPing()
接続とサーバーがアクティブであることを確認します。
用途
サーバーへのラウンドトリップ・コールを行い、接続とサーバーがアクティブであることを確認します。
構文
sword OCIPing ( OCISvcCtx *svchp, OCIError *errhp, ub4 mode );
パラメータ
コメント
OCIPing()
は、サーバーに対してダミーのラウンドトリップ・コールを実行します。つまり、応答としてダミー・パケットがサーバーに送信されます。ラウンドトリップの完了後、OCIPing()
が戻されます。このコール自体に対して、サーバーは操作を実行しません。
OCIPing()
を使用して、サーバーに対する軽量コールを行うことができます。コールが正常に終了した場合は、接続とサーバーがアクティブであることを示します。コールがブロックされた場合、接続が別のスレッドによって使用されている可能性があります。このコールが失敗した場合、接続やサーバーに問題が発生している可能性があり、エラーをエラー・ハンドルから取り出すことができます。OCIPing()
はラウンドトリップ・コールであるため、これを使用して、サーバーに対する保留状態のOCIクライアント側のコール(存在する場合)をすべてフラッシュすることもできます。たとえば、OCIHandleFree()
の後にOCIPing()
をコールすることにより、保留状態のコールの実行を強制し、バックエンド・カーソルをクローズすることができます。このコールは、通常であればその接続の次のラウンドトリップでクローズされるバックエンド・カーソルをアプリケーションで即座にクローズする必要がある場合に便利です。また、OCI_ATTR_SERVER_STATUS
の拡張機能を使用すれば、要件が接続の状態のチェックのみの場合、OCIPingは必要ありません。詳細は、「サーバー・ハンドル属性」のOCI_ATTR_SERVER_STATUS
属性を参照してください。
関連トピック
26.9.7 OCIReset()
割り込まれた非同期操作およびプロトコルをリセットします。
用途
非ブロック操作の処理中にOCIBreak()
コールが発行された場合に、コールする必要があります。
構文
sword OCIReset ( void *hndlp, OCIError *errhp );
パラメータ
コメント
このコールは、非ブロック・モードでのみコールされます。割り込まれた非同期操作およびプロトコルをリセットします。非ブロック操作の処理中にOCIBreak()
コールが発行された場合に、OCIReset()をコールする必要があります。
関連トピック
26.9.8 OCIRowidToChar()
ユニバーサルROWID
を拡張文字(BASE64)表現に変換します。
用途
ユニバーサルROWID
を拡張文字(BASE64)表現に変換します。
構文
sword OCIRowidToChar ( OCIRowid *rowidDesc, OraText *outbfp, ub2 *outbflp OCIError *errhp );
パラメータ
- rowidDesc (IN)
-
OCIDescriptorAlloc()
で割り当てられ、前に実行されたSQL文で挿入されたROWID
記述子です。 - outbfp (OUT)
-
このコールが正常に実行された後、文字表現が格納されるバッファへのポインタです。
- outbflp (IN/OUT)
-
出力バッファ長へのポインタです。実行前は、バッファ長には
outbfp
のサイズが格納されています。実行後は、変換されたバイト数が格納されます。変換時に切捨てがある場合、
outbfp
には、変換を正常終了するために必要な長さが格納されます。エラーも戻されます。 - errhp (IN)
-
エラー発生時の診断情報のために
OCIErrorGet()
に渡すエラー・ハンドルです。
コメント
この変換を行った後は、文字形式のROWID
をOCIBindByPos()
コールまたはOCIBindByName()
コールにバインドし、指定されたROWID
の行の問合せに使用できます。
charset
およびncharset
パラメータがOCI_UTF16ID
に設定された状態でOCIEnvNlsCreate()
を使用して環境が作成されている場合、関数OCIRowidToChar()
は、予期されるUTF-16ではなくASCIIのROWID表現を戻します。
26.9.9 OCIServerRelease()
Oracle Databaseリリース文字列を戻します。
用途
Oracle Databaseリリース文字列を戻します。
構文
sword OCIServerRelease ( void *hndlp, OCIError *errhp, OraText *bufp, ub4 bufsz ub1 hndltype ub4 *version );
パラメータ
コメント
バッファ・ポインタ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 */
関連トピック
26.9.10 OCIServerRelease2()
Oracle Databaseリリース文字列を戻します。
用途
Oracle Databaseリリース文字列を戻します。
構文
sword OCIServerRelease2( void *hndlp,
OCIError *errhp,
OraText *bufp,
ub4 bufsz,
ub1 hndltype,
ub4 *versionp,
ub4 mode);
パラメータ
- hndlp (IN)
-
サービス・コンテキスト・ハンドルまたはサーバー・コンテキスト・ハンドルです。
- errhp (IN/OUT)
-
エラー発生時の診断情報のために
OCIErrorGet()
に渡すエラー・ハンドルです。 - bufp (IN/OUT)
-
リリース文字列が戻されるバッファです。
- bufsz (IN)
-
バイト数で示したバッファの長さです。
- hndltype (IN)
-
関数に渡されたハンドル型です。
- versionp (IN/OUT)
-
整数書式でのリリース文字列です。
- mode (IN)
-
有効な値は、
OCI_SRVRELEASE2_CACHED
およびOCI_DEFAULT
です。モードに
OCI_SRVRELEASE2_CACHED
を指定すると、キャッシュされたバージョンのサーバー・リリースがある場合はそれが戻されます。アプリケーションがこの関数を複数回コールする場合は、これによってラウンドトリップの回数が減ります。このモードでは、アプリケーションはnullのbufp
を指定することを選択できます。この場合は、versionp
パラメータのみが移入されます。OCI_DEFAULT
では、ラウンドトリップが行われます。
コメント
bufp
は、NULL
終端文字を含む、サイズbufsz
までの文字列表現内のリリース情報を指し示しています。バッファ・サイズが小さい場合、結果はサイズbufsz
まで切り捨てられます。version
引数には、5桁のOracle Databaseリリース文字列が整数形式で含まれており、これは次のマクロを使用して取得されます。 OCI_SERVER_RELEASE_REL(v)
/* old: version number */
/* new: feature release */
OCI_SERVER_RELEASE_REL_UPD(v)
/* old: release number */
/* new: release update */
OCI_SERVER_RELEASE_REL_UPD_REV(v)
/* old: update number */
/* new: release update revision */
OCI_SERVER_RELEASE_REL_UPD_INC(v)
/* old: porting release number */
/* new: release update increment */
OCI_SERVER_RELEASE_EXT(v)
/* old: porting update number */
/* new: extension */
「old」は、バージョン18.1より前のデータベースに接続した場合に適用できることを意味します。「new」は、バージョン18.1以上のデータベースに接続した場合に適用できることを意味します。
26.9.11 OCIServerVersion()
Oracle Databaseバージョン文字列を戻します。
用途
Oracle Databaseバージョン文字列を戻します。
構文
sword OCIServerVersion ( void *hndlp, OCIError *errhp, OraText *bufp, ub4 bufsz ub1 hndltype );
パラメータ
コメント
このコールは、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
関連トピック
26.9.12 OCISvcCtxToLda()
バージョン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以上かを判断できます。
26.9.13 OCIUserCallbackGet()
ハンドルに対して登録されたコールバックを判断します。
用途
ハンドルに対して登録されたコールバックを判断します。
構文
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 );
パラメータ
- hndlp (IN)
-
typeパラメータによって指定された型のハンドルです。
- type (IN)
-
ハンドル・タイプです。有効なハンドル・タイプは
OCI_HTYPE_ENV
です。このコールバックは、環境ハンドル上で生成されたfcode
によって指定される関数の、すべてのコールに対して登録されます。 - ehndlp (IN)
-
OCIエラー・ハンドルまたは環境ハンドルです。エラーがある場合は、
ehndlp
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
のコールによって診断情報を取得できます。 - fcode (IN)
-
OCI関数の一意の関数コードです。これらは表26-9にリスト表示されています。
- when (IN)
-
コールバックがいつ呼び出されるかを定義します。次のモードが有効です。
-
OCI_UCBTYPE_ENTRY
- このコールバックは、OCI関数の開始時に呼び出されます。 -
OCI_UCBTYPE_EXIT
- このコールバックは、OCI関数の終了前に呼び出されます。 -
OCI_UCBTYPE_REPLACE
- このコールバックでOCI_CONTINUE
以外が戻された場合は、次の置換コールバックおよびOCI関数に対するOCIコードはコールされません。かわりに、最後のコールバックの処理が開始されます。このパラメータの詳細は、「OCIUserCallbackRegister()
」を参照してください。
-
- callbackp (OUT)
-
コールバック関数ポインタへのポインタです。
fcode
、when
およびhndlp
の値に対して現在登録されている関数を戻します。この場合、コールバックが登録されていないときは、戻り値はNULL
です。関連項目:
callbackp
のパラメータの詳細は、「OCIUserCallbackRegister()
」を参照してください - ctxpp (OUT)
-
現在登録されているコールバックに対して戻されるコンテキストへのポインタです。
- ucbDesc (IN)
-
OCIで指定される記述子です。この記述子は、環境コールバックでOCIによって渡されます。この記述子には、コールバックを登録する場合の優先度が格納されます。
ucbDesc
パラメータにNULL
を指定すると、このコールバックの優先度が最も高くなります。パッケージで動的に登録されたユーザー・コールバックとは対照的に、静的に登録されたユーザー・コールバックは、使用する
ucb
記述子がないため、NULL
記述子を使用します。
コメント
この関数は、特定のハンドルに対して登録されているコールバックを検出します。
26.9.14 OCIUserCallbackRegister()
ユーザー作成コールバック関数を登録します。
用途
ユーザー作成コールバック関数を登録します。
構文
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 );
パラメータ
- hndlp (IN)
-
typeパラメータによって指定された型のハンドルです。
- type (IN)
-
ハンドル・タイプです。有効なハンドル・タイプは
OCI_HTYPE_ENV
です。このコールバックは、環境ハンドル上で生成されたfcode
によって指定される関数の、すべてのコールに対して登録されます。
- ehndlp (IN)
-
OCIエラー・ハンドルまたは環境ハンドルです。エラーがある場合は、
ehndlp
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
のコールによって診断情報を取得できます。OCIEnvCallback
では、エラー・ハンドルを使用することができないため、環境ハンドルはehndlp
として渡されます。 - callback (IN)
-
コールバック関数ポインタです。
OCIUserCallback
関数プロトタイプの変数引数のリストは、OCI関数に渡されるパラメータです。OCIUserCallback
のtypedefについては、後で説明します。最初のコールバックで
OCI_CONTINUE
以外が戻された場合、リターン・コードは後続の最初のコールバックまたは置換コールバック(存在する場合)に渡されます。このコールバックが最新の最初のコールバックで、置換コールバックがない場合、OCIコードは実行されてリターン・コードは無視されます。置換コールバックが
OCI_CONTINUE
以外を戻した場合、後続の置換コールバックおよびOCIコードは迂回されて最後のコールバックの処理が開始されます。終了コールバックが
OCI_CONTINUE
以外を戻した場合、戻り値はOCI関数によって戻されます。そうでない場合、OCIコードまたは置換コールバックからの戻り値(置換コールバックがOCI_CONTINUE
を戻さず、結果的にOCIコードをバイパスした場合)が、このコールによって戻されます。コールバックに対して
NULL
値が渡された場合は、when
値および指定されたハンドルのコールバックが削除されます。これは、NULL
のucbDesc
を含む指定のucbDesc
値に対するコールバックを登録解除する方法です。 - ctxp (IN)
-
コールバックのコンテキスト・ポインタです。
- fcode (IN)
-
OCI関数の一意の関数コードです。これらは表26-9にリスト表示されています。
- when (IN)
-
コールバックがいつ呼び出されるかを定義します。次のモードが有効です。
-
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 (IN)
-
登録コールバック関数内で
ctxp
として渡されるコンテキストです。 - hndlp (IN)
-
type
パラメータで指定された型のハンドルです。コールバックを呼び出すためのハンドルです。OCI_HTYPE_ENV
型以外は使用できないため、環境ハンドルenv
はここに渡されます。 - type (IN)
-
hndlp
に対して登録された型です。有効なハンドル・タイプはOCI_HTYPE_ENV
です。このコールバックは、環境ハンドル上で生成されたfcode
によって指定される関数の、すべてのコールに対して登録されます。
- fcode (IN)
-
OCIコールの関数コードです。これらは表26-9にリスト表示されています。コールバックは、表26-3に示されているOCIコールに対してのみ登録できます。
- when (IN)
-
コールバックの
when
値です。 - returnCode (IN)
-
直前のコールバックまたはOCIコードからのリターン・コードです。1回目の最初のコールバックでは、
OCI_SUCCESS
が常に渡されます。後続のコールバックでは、OCIコードまたは前のコールバックからのリターン・コードが渡されます。 - errnop (IN/OUT)
-
1回目の最初のコールバックをコールすると、
*errnop
の入力値は0 (ゼロ)になります。コールバックによりOCI_CONTINUE
以外の値が戻される場合は、*errnop
にエラー番号を設定する必要があります。この値は、OCIコール内に渡されるエラー・ハンドルで設定されます。後続のすべてのコールバックの場合、
*errnop
の入力値はエラー・ハンドル内のエラー番号の値です。このため、前のコールバックからOCI_CONTINUE
が戻されなかった場合、前のコールバックからの*errnop
の出力値はエラー・ハンドル内の値となり、この値が、ここで後続のコールバックに渡されます。ただし、前のコールバックによってOCI_CONTINUE
が戻された場合、エラー・ハンドル内の値はすべてここで渡されます。*errnop
にOracle以外のエラー番号が戻された場合は、そのエラー番号に対して適切なテキストを戻すために、コールバックをOCIErrorGet()
関数に登録する必要があります。 - arglist (IN)
-
これは、引数の可変数としてここに渡されるOCIコールのパラメータです。ユーザー・コールバックのデモ・プログラムに示されているように、
va_arg
を使用して間接参照する必要があります。関連項目:
表26-9 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 |
(未使用) |
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 |
(未使用) |
15 |
(未使用) |
47 |
OCILobRead |
79 |
(未使用) |
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 |
表26-10 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 |