1. データ・カートリッジ開発者ガイド
  2. リファレンス
  3. C、C++およびJavaを使用したカートリッジ・サービス

18 C、C++およびJavaを使用したカートリッジ・サービス

C/C++およびJavaを使用するプログラマは、カートリッジ・サービスを使用できます。

関連項目:

Cを使用したカートリッジ・サービスの詳細は、『Oracle Call Interfaceプログラマーズ・ガイド』を参照してください。

18.1 外部プロシージャ用のOCIアクセス・ファンクション

外部プロシージャからコールされたサービス・ルーチンは、例外の発生、メモリーの割当ておよびサーバーへのコールバックに使用するOCIハンドルの取得を行うことができます。ファンクションを使用するには、外部プロシージャにコンテキスト構造を渡せるように、WITH CONTEXT句を指定する必要があります。コンテキスト構造は、ヘッダー・ファイルociextp.h内で次のように宣言されます。 

typedef struct OCIExtProcContext OCIExtProcContext;

サービス・ルーチンがコンテキスト情報をどのように使用するかを考えます。使用方法の詳細および例は、『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』を参照してください。

18.1.1 OCIExtProcAllocCallMemory

このサービス・ルーチンは、外部プロシージャ・コールの間、nバイトのメモリーを割り当てます。ファンクションにより割り当てられたメモリーは、制御がPL/SQLに戻ると解放されます。

メモリーの割当てや解放には他のファンクションを使用しないでください。

この関数のCプロトタイプは、次のとおりです。 

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

パラメータwith_contextおよびamountは、それぞれ、コンテキスト・ポインタと割り当てられるバイト数です。この関数は、割り当てられたメモリーを指す型が未定のポインタを戻します。戻り値が0(ゼロ)の場合は、失敗を示します。

18.1.2 OCIExtProcRaiseExcp

このサービス・ルーチンは、事前定義の例外を呼び出します。この例外には、1から32767の有効なOracleエラー番号が割り当てられている必要があります。必要なクリーン・アップ処理後、外部プロシージャはすぐに制御を戻す必要があります。クリーン・アップ処理後、外部プロシージャをすぐに戻す必要があります(OUTまたはIN OUTパラメータには値は何も割り当てられません)。この関数のCプロトタイプは、次のとおりです。 

int OCIExtProcRaiseExcp(
   OCIExtProcContext *with_context, 
   size_t error_number);

パラメータwith_contextおよびerror_numberは、それぞれコンテキスト・ポインタおよびOracleエラー番号です。戻り値のOCIEXTPROC_SUCCESSおよびOCIEXTPROC_ERRORは、正常終了および失敗を示します。

18.1.3 OCIExtProcRaiseExcpWithMsg

このサービス・ルーチンは、ユーザー定義例外を発生させてユーザー定義のエラー・メッセージを戻します。この関数のCプロトタイプは、次のとおりです。 

int OCIExtProcRaiseExcpWithMsg(
   OCIExtProcContext *with_context, 
   size_t error_number,
   text   *error_message, 
   size_t  len);

パラメータwith_context、error_numberおよびerror_messageは、コンテキスト・ポインタ、Oracleエラー番号およびエラー・メッセージ・テキストです。パラメータlenには、エラー・メッセージの長さが格納されます。メッセージがNULL文字で終了する文字列の場合、lenは0(ゼロ)です。戻り値のOCIEXTPROC_SUCCESSおよびOCIEXTPROC_ERRORは、正常終了および失敗を示します。

18.1.4 OCIExtProcGetEnv

このサービス・ルーチンを使用すると、外部プロシージャ・コール中にデータベースへのOCIコールバックが可能になります。このファンクションで取得されるOCIハンドルは、コールバックにのみ使用してください。そのOCIハンドルを標準OCIコールに使用すると、データベースへの新規接続が確立され、同じトランザクションではコールバックに使用できません。つまり、外部プロシージャ・コール時には、OCIハンドルをコールバックまたは新規接続に使用できますが、両方に使用することはできません。

この関数のCプロトタイプは、次のとおりです。 

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

パラメータwith_contextはコンテキスト・ポインタで、パラメータenvh、svch、errhは、それぞれ、OCI環境、サービス、エラー・ハンドルです。戻り値のOCIEXTPROC_SUCCESSおよびOCIEXTPROC_ERRORは、正常終了および失敗を示します。

「コールバックの使用」では、OCIExtProcGetEnvをコールバックで使用する方法を示しています。実際の例については、PL/SQLデモ・ディレクトリのスクリプトextproc.sqlを参照してください。(このディレクトリの場所については、ご使用のOracleインストール・ガイドまたはユーザーズ・ガイドを参照してください。)このスクリプトは、外部プロシージャのコール方法を示しています。付属ファイルextproc.cには、外部プロシージャのCソース・コードが含まれています。デモを実行するには、extproc.sqlにある指示に従ってください。CREATE LIBRARY権限を持つアカウントを使用する必要があります。

18.2 Javaカートリッジ・サービス・ファイルのインストール

ここで説明するJavaクラスを使用するには、ODCI.jarおよびCartridgeServices.jarファイルをSYSスキーマにインストールする必要があります。

Javaオプションをインストール済の場合は、ODCI.jarおよびCartridgeServices.jarファイルをインストールする必要があります。Javaオプションをインストールしていない場合、このタスクを実行する必要はありません。

ODCI.jarおよびCartridgeServices.jarファイルをインストールする方法

  1. SQL*Plusプロンプトを起動します。
    C:\sqlplus
  2. 起動したら、systemアカウントを使用してログインします。
    Enter user-name: system
Enter password: password
  3. サーバー側のloadjavaコマンドを使用してクラスをインストールし、SYSTEMスキーマにシノニムを作成します。
    SQL> call dbms_java.loadjava('-resolve -synonym -grant public 
     -verbose vobs/jilip/Cartridge Services.jar');
SQL> call dbms_java.loadjava('-resolve -synonym -grant public
     -verbose vobs/jlib/ODCI.jar');

jarファイルのインストールの詳細は、『Oracle Databaseアップグレード・ガイド』を参照してください。

18.3 カートリッジ・サービス: コンテキストのメンテナンス

Javaカートリッジ・サービスは、コンテキストのメンテナンスに使用されます。これはOCIコンテキスト管理サービスに似ています。サーバーおよびカートリッジ・コード間でコンテキストを切り替えるには、このクラスが必要です。

18.3.1 ContextManager

ContextManagerはObjectを拡張するOracleクラスのコンストラクタです。

クラス・インタフェース

public static Hashtable ctx extends Object

変数

ctx public static Hashtable ctx

コンストラクタ

ContextManager public ContextManager()

メソッド

次のメソッドを使用できます。

setContext (static method in class oracle)
getContext (static method in class oracle)
clearContext (static method in class oracle)

18.3.2 CountException()

Exceptionを拡張するコンストラクタ。 

Class oracle.CartridgeServices.CountException

18.3.3 CountException(String)

Exceptionを拡張するコンストラクタ。 

public CountException(String s)

18.3.4 InvalidKeyException()

Exceptionを拡張するコンストラクタ。 

public InvalidKeyException(String s)

18.3.5 InvalidKeyException(String)

Exceptionを拡張するコンストラクタ。 

public InvalidKeyException(String s)