29.2 カートリッジ・サービス: OCI外部プロシージャ
カートリッジ・サービスのOCI外部プロシージャ関数をリストし、説明します。
表29-1は、この項で説明しているCのOCI外部プロシージャ関数を示しています。
表29-1 外部プロシージャ関数
関数 | 用途 |
---|---|
外部プロシージャの継続時間にメモリーを割り当てます。 |
|
OCI環境ハンドル、サービス・コンテキスト・ハンドルおよびエラー・ハンドルを取得します。 |
|
PL/SQLに例外を呼び出します。 |
|
例外をメッセージ付きで呼び出します。 |
29.2.1 OCIExtProcAllocCallMemory()
外部プロシージャの継続時間にNバイトのメモリーを割り当てます。
用途
外部プロシージャの継続時間にNバイトのメモリーを割り当てます。
構文
void * OCIExtProcAllocCallMemory ( OCIExtProcContext *with_context, size_t amount );
パラメータ
コメント
このコールは、外部プロシージャのコール継続時間にamount
バイトのメモリーを割り当てます。
このコールで割り当てられたメモリーは、外部プロシージャから戻るとすぐにPL/SQLによって解放されます。アプリケーションでは、OCIExtProcAllocCallMemory()
で割り当てたメモリーにfree()
関数を使用しないでください。この関数を使用して、関数の戻り値用のメモリーを割り当ててください。
0 (ゼロ)の戻り値はエラーとして扱われます。
戻り値
割り当てたメモリーを指し示す未定義の型(不透明な)ポインタを戻します。
例
OCIExtProcAllocCallMemory()を使用した1024バイトのメモリーの割当て
text *ptr = (text *)OCIExtProcAllocCallMemory(wctx, 1024)
関連トピック
29.2.2 OCIExtProcGetEnv()
OCI環境、サービス・コンテキストおよびエラー・ハンドルを取得します。
用途
OCI環境、サービス・コンテキストおよびエラー・ハンドルを取得します。
構文
sword OCIExtProcGetEnv ( OCIExtProcContext *with_context, OCIEnv **envh, OCISvcCtx **svch, OCIError **errh );
パラメータ
- with_context (IN)
-
C外部プロシージャに渡される
with_context
ポインタです。With_Context
型 — C言語におけるPL/SQL外部プロシージャへのコール可能なインタフェースでは、with_context
パラメータを渡す必要があります。この構造体の型はOCIExtProcContext
で、ユーザーには認識されません。ユーザーは、
with_context
パラメータをアプリケーションで次のように宣言できます。OCIExtProcContext *with_context;
- envh (OUT)
-
OCI環境ハンドルを格納する変数のポインタです。
- svch (OUT)
-
OCIサービス・ハンドルを格納する変数のポインタです。
- errh (OUT)
-
OCIエラー・ハンドルを格納する変数のポインタです。
コメント
この関数の主な目的は、OCIコールバックで同じトランザクションのデータベースを使用可能にすることです。この関数で取得するOCIハンドルは、データベースに対するOCIコールバックで使用する必要があります。これらのハンドルを標準のOCIコールを介して取得した場合、これらのハンドルはデータベースへの新規接続を使用するので、同一トランザクション内のコールバックには使用できません。1つの外部プロシージャで使用できるのは、コールバックと新規接続のどちらか一方で、両方は使用できません。
コールの例:
OCIEnv *envh; OCISvcCtx *svch; OCIError *errh; ... OCIExtProcGetEnv(ctx,&envh,&svch,&errh);
戻り値
この関数は、コールが成功した場合は、OCI_SUCCESS
を戻します。コールが失敗した場合は、OCI_ERROR
を戻します。
29.2.3 OCIExtProcRaiseExcp()
PL/SQLに例外を呼び出します。
用途
PL/SQLに例外を呼び出します。
構文
size_t OCIExtProcRaiseExcp ( OCIExtProcContext *with_context, int errnum );
パラメータ
コメント
この関数をコールすると、例外がPL/SQLに通知されます。この関数が問題なく戻されると、外部プロシージャは終了処理を開始し、PL/SQLに戻ります。いったん例外がPL/SQLに通知されると、IN/OUT引数とOUT引数(ある場合)は処理されません。
戻り値
この関数は、コールが正常に行われるとOCIEXTPROC_SUCCESS
を戻します。コールに失敗するとOCIEXTPROC_ERROR
を戻します。
関連トピック
29.2.4 OCIExtProcRaiseExcpWithMsg()
例外をメッセージ付きで呼び出します。
用途
例外をメッセージ付きで呼び出します。
構文
size_t OCIExtProcRaiseExcpWithMsg ( OCIExtProcContext *with_context, int errnum, char *errmsg, size_t msglen );
パラメータ
コメント
このコールによってPL/SQLに例外が呼び出されます。さらに、後続のエラー・メッセージ文字列を標準のOracle Databaseエラー・メッセージ文字列内で代入します。
戻り値
この関数は、コールが正常に行われるとOCIEXTPROC_SUCCESS
を戻します。コールに失敗するとOCIEXTPROC_ERROR
を戻します。
関連トピック