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

Cに対応するOCI外部プロシージャ関数を次に示します。

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

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

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（ゼロ）の戻り値はエラーとして扱われます。

戻り値

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

例

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

関連関数

OCIErrorGet()およびOCIMemoryAlloc()

OCIExtProcRaiseExcp()

用途

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

構文

size_t OCIExtProcRaiseExcp ( OCIExtProcContext    *with_context,
                             int                   errnum );

パラメータ

with_context (IN)

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

関連項目:

「With_Context型」

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

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

関連項目:

詳細は、OCIExtProcRaiseExcp()の説明を参照してください。

戻り値

この関数は、コールが成功した場合は、OCIEXTPROC_SUCCESSを戻します。コールが失敗した場合は、OCIEXTPROC_ERRORを戻します。

関連関数

OCIExtProcRaiseExcp()

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を戻します。