カートリッジ・サービス — OCI外部プロシージャ

表20-1は、この項で説明しているCのOCI外部プロシージャ関数を示しています。

表20-1 外部プロシージャ関数

関数	用途
「OCIExtProcAllocCallMemory()」	外部プロシージャの継続時間にメモリーを割り当てます。
「OCIExtProcGetEnv()」	OCI環境ハンドル、サービス・コンテキスト・ハンドルおよびエラー・ハンドルを取得します。
「OCIExtProcRaiseExcp()」	PL/SQLに例外を呼び出します。
「OCIExtProcRaiseExcpWithMsg()」	例外をメッセージ付きで呼び出します。

OCIExtProcAllocCallMemory()

用途

外部プロシージャの継続時間にNバイトのメモリーを割り当てます。

構文

void  * OCIExtProcAllocCallMemory ( OCIExtProcContext    *with_context,
                                    size_t                amount );

パラメータ

with_context (IN)

C外部プロシージャに渡されるwith_contextポインタです。

関連項目:

「With_Context型」

amount (IN): 割り当てるバイト数です。

このコールは、外部プロシージャのコール継続時間にamountバイトのメモリーを割り当てます。

このコールで割り当てられたメモリーは、外部プロシージャから戻るとすぐにPL/SQLによって解放されます。アプリケーションでは、OCIExtProcAllocCallMemory()で割り当てたメモリーにfree()関数を使用しないでください。この関数を使用して、関数の戻り値用のメモリーを割り当ててください。

0 (ゼロ)の戻り値はエラーとして扱われます。

戻り値

割り当てたメモリーを指し示す未定義の型(不透明な)ポインタを戻します。

例

例20-1 OCIExtProcAllocCallMemory()を使用した1024バイトのメモリーの割当て

text *ptr = (text *)OCIExtProcAllocCallMemory(wctx, 1024)

関連関数

OCIErrorGet()およびOCIMemoryAlloc()

OCIExtProcGetEnv()

用途

OCI環境、サービス・コンテキストおよびエラー・ハンドルを取得します。

構文

sword OCIExtProcGetEnv ( OCIExtProcContext    *with_context, 
                         OCIEnv               **envh, 
                         OCISvcCtx            **svch, 
                         OCIError             **errh );

パラメータ

with_context (IN): C外部プロシージャに渡されるwith_contextポインタです。「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を戻します。

OCIExtProcRaiseExcp()

用途

PL/SQLに例外を呼び出します。

構文

size_t OCIExtProcRaiseExcp ( OCIExtProcContext    *with_context, 
                             int                   errnum );

パラメータ

with_context (IN)

C外部プロシージャに渡されるwith_contextポインタです。

関連項目:

「With_Context型」

errnum (IN): PL/SQLへシグナルを送るOracle Databaseエラー番号です。errnumの値は、1から32767の正数にしてください。

この関数をコールすると、例外がPL/SQLに通知されます。この関数が問題なく戻されると、外部プロシージャは終了処理を開始し、PL/SQLに戻ります。いったん例外がPL/SQLに通知されると、IN/OUT引数とOUT引数(ある場合)は処理されません。

戻り値

この関数は、コールが正常に行われるとOCIEXTPROC_SUCCESSを戻します。コールに失敗するとOCIEXTPROC_ERRORを戻します。

関連関数

OCIExtProcRaiseExcpWithMsg()

用途

例外をメッセージ付きで呼び出します。

構文

size_t OCIExtProcRaiseExcpWithMsg ( OCIExtProcContext   *with_context,
                                    int                  errnum, 
                                    char                 *errmsg, 
                                    size_t               msglen );

パラメータ

with_context (IN)

C外部プロシージャに渡されるwith_contextポインタです。

関連項目:

「With_Context型」

errnum (IN): PL/SQLへシグナルを送るOracle Databaseエラー番号です。errnumは、1から32767の正数にしてください。
errmsg (IN): errnumに対応付けられたエラー・メッセージです。
msglen (IN): エラー・メッセージの長さです。errmsgがNULLで終了する文字列の場合は、0 (ゼロ)が渡されます。

このコールによってPL/SQLに例外が呼び出されます。さらに、後続のエラー・メッセージ文字列を標準のOracle Databaseエラー・メッセージ文字列内で代入します。

関連項目:

OCIExtProcRaiseExcp()の説明

戻り値

この関数は、コールが正常に行われるとOCIEXTPROC_SUCCESSを戻します。コールに失敗するとOCIEXTPROC_ERRORを戻します。

関連関数

OCIExtProcRaiseExcp()