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)