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 |