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

カートリッジ・サービスのOCI外部プロシージャ関数をリストし、説明します。

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

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

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

OCIExtProcAllocCallMemory()

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

用途

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

構文

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

パラメータ

with_context (IN)

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

With_Context型 — C言語におけるPL/SQL外部プロシージャへのコール可能なインタフェースでは、with_contextパラメータを渡す必要があります。この構造体の型はOCIExtProcContextで、ユーザーには認識されません。

ユーザーは、with_contextパラメータをアプリケーションで次のように宣言できます。

OCIExtProcContext *with_context;

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

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

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

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

戻り値

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

例

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

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

OCIExtProcGetEnv()

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

用途

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

構文

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

パラメータ

with_context (IN)

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

ユーザーは、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を戻します。

OCIExtProcRaiseExcp()

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

用途

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

構文

size_t OCIExtProcRaiseExcp ( OCIExtProcContext    *with_context, 
                             int                   errnum );

パラメータ

with_context (IN)

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

ユーザーは、with_contextパラメータをアプリケーションで次のように宣言できます。

OCIExtProcContext *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パラメータをアプリケーションで次のように宣言できます。

OCIExtProcContext *with_context;

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

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

戻り値

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