アプリケーション開発の手引き

DB2GENERAL UDF およびストアード・プロシージャー

PARAMETER STYLE DB2GENERAL UDF およびストアード・プロシージャーは Java で作成されるので、これ以降は単に Java UDF およびストアード・プロシージャーと呼びます。 DB2GENERAL UDF およびストアード・プロシージャーを作成することは、サポートされている他のプログラム言語で UDF およびストアード・プロシージャーを作成することと非常によく似ています。いったんそれらを作成して登録すると、どの言語のプログラムからでも呼び出すことができます。一般的に、ストアード・プロシージャーから JDBC API を呼び出すことはできますが、 UDF からそれらを呼び出すことはできません。

サポートされる SQL データ・タイプ

PARAMETER STYLE DB2GENERAL UDF およびストアード・プロシージャーを呼び出す場合、 表 54 に記述されているように、 DB2 は SQL タイプと Java タイプとを変換します。これらのクラスのいくつかは、Java パッケージの COM.ibm.db2.app にあります。

表 54. DB2 SQL タイプおよび Java オブジェクト
SQL 列名 Java タイプ (UDF) Java タイプ (ストアード・プロシージャー)
SMALLINT (500/501) short short
INTEGER (496/497) int int
BIGINT (492/493) long long
FLOAT (480/481) double double
REAL (480/481)(1) float float
DECIMAL(p,s) (484/485) java.math.BigDecimal java.math.BigDecimal
NUMERIC(p,s) (504/505) java.math.BigDecimal java.math.BigDecimal
CHAR(n) (452/453) String String
CHAR(n) FOR BIT DATA (452/453) Blob Blob
C NULL 終了ストリング (400/401)(2) n/a String
VARCHAR(n)(448/449) String String
VARCHAR(n) FOR BIT DATA (448/449) Blob Blob
LONG VARCHAR (456/457) String String
LONG VARCHAR FOR BIT DATA (456/457) Blob Blob
GRAPHIC(n) (468/469) String String
C NULL 終了グラフィック・ストリング (460/461)(2) n/a String
VARGRAPHIC(n) (464/465) String String
LONG VARGRAPHIC (472/473)(3) String String
BLOB(n)(404/405)(3) Blob Blob
CLOB(n) (408/409)(3) Clob Clob
DBCLOB(n) (412/413)(3) Clob Clob
DATE (384/385)(4) String String
TIME (388/389)(4) String String
TIMESTAMP (392/393)(4) String String

注:

  1. SQLDA での REAL と DOUBLE の違いは長さの値です (4 または 8)。

  2. C NULL 終了グラフィック・ストリングなどのような、括弧で囲まれたタイプは、呼び出しているアプリケーションがいくつかのタイプのホスト変数の付いた組み込み SQL を使用する場合に、ストアード・プロシージャーで発生します。

  3. Blob および Clob クラスは COM.ibm.db2.app パッケージ中にあります。それらのインターフェースはルーチンを組み込んで、Blob に対しては読み書きを行い、 Clob には Reader および Writer となる InputStream および OutputStream を生成します。クラスの詳細は、Java ストアード・プロシージャーと UDF のクラスを参照してください。

  4. C でコード化される UDF と同様に、SQL DATE、TIME、および TIMESTAMP 値は、Java で符号化される ISO ストリングを使用します。

COM.ibm.db2.app.Blob および COM.ibm.db2.app.Clob クラスの例は、 LOB データ・タイプ (BLOB、 CLOB、および DBCLOB) を示します。これらのクラスは、入力として渡される LOB を読み込み、出力として戻される LOB を書き込む限定インターフェースを提供します。 LOB の読み込みおよび書き込みは、標準 Java I/O ストリーム・オブジェクトを通して起こります。 Blob クラスの場合、getInputStream() および getOutputStream() ルーチンは、 BLOB の内容を一度にバイト単位で処理する、 InputStream または OutputStream オブジェクトを戻します。 Clob の場合、getReader() および getWriter() は、 CLOB または DBCLOB の内容を一度に文字単位で処理する、 Reader または Writer オブジェクトを戻します。

set() メソッドを使用して、そのようなオブジェクトが出力として戻される場合、データベースのコード・ページ中の Java Unicode 文字を表示する目的で、コード・ページ変換が適用される場合があります。

Java ストアード・プロシージャーと UDF のクラス

Java ストアード・プロシージャーは、Java UDF と非常によく似ています。表関数のように、複数の出力がある場合があります。ヌル値の規則も同じですし、出力にも同じ set ルーチンを使用します。主な違いは、ストアード・プロシージャーを含む Java クラスは、 COM.ibm.db2.app.UDF クラスの代わりに、 COM.ibm.db2.app.StoredProc クラスから継承することです。 COM.ibm.db2.app.StoredProc クラスの詳細については、 COM.ibm.db2.app.StoredProc を参照してください。

このインターフェースは、JDBC 接続を組み込みアプリケーション・コンテキストに取り出すための以下のルーチンを提供します。

     public java.sql.Connection getConnection()

SQL ステートメントを実行するためにこの処理を使用できます。 StoredProc インターフェースの他のメソッドは、 sqllib/samples/java/StoredProc.java ファイルにリストされています。

Java ストアード・プロシージャーまたは UDF で使用できるクラス / インターフェースは、以下の 5 つです。

以下の節では、これらのクラスの動作のパブリックな要素を説明します。

COM.ibm.db2.app.StoredProc

PARAMETER STYLE DB2GENERAL ストアード・プロシージャーとして呼び出されるメソッドが含まれる Java クラスは、パブリックでなければならず、この Java インターフェースを実現するものでなければなりません。そのようなクラスを次のように宣言する必要があります。

public class <user-STP-class> extends COM.ibm.db2.app.StoredProc{ ... }

現在実行しているストアード・プロシージャーのコンテキストでは、 COM.ibm.db2.app.StoredProc インターフェースの継承メソッドだけを呼び出せます。たとえば、ストアード・プロシージャーが戻った後には、結果設定呼び出しあるいは状況設定呼び出しなど、LOB 引き数での操作を行えません。この規則に違反すると、Java 例外が出されます。

引き数関連の呼び出しは、列索引を使用して参照する列を識別します。これは、最初の引き数の 1 から開始します。 PARAMETER STYLE DB2GENERAL ストアード・プロシージャーのすべての引き数は INOUT、つまり入出力であるとみなされます。

ストアード・プロシージャーから例外が戻されると、データベースによって捕そくされ、SQLCODE -4302、SQLSTATE 38501 と共に呼び出し元に戻されます。 JDBC SQLException または SQLWarning が特別に処理され、その SQLCODE、SQLSTATE などが呼び出しアプリケーションに逐次渡されます。

次のメソッドは、COM.ibm.db2.app.StoredProc クラスに関連付けられています。

public StoredProc() [default constructor]

このコンストラクターは、ストアード・プロシージャー呼び出しの前にデータベースによって呼び出されます。

public boolean isNull(int) throws Exception

この関数は、所定の索引の付いた入力引き数が SQL NULL であるかどうかをテストします。

public void set(int, short) throws Exception
public void set(int, int) throws Exception
public void set(int, double) throws Exception
public void set(int, float) throws Exception
public void set(int, java.math.BigDecimal) throws Exception
public void set(int, String) throws Exception
public void set(int, COM.ibm.db2.app.Blob) throws Exception
public void set(int, COM.ibm.db2.app.Clob) throws Exception

この関数は、所定の索引の付いた出力引き数を所定の値に設定します。この索引は有効な出力引き数を参照し、データ・タイプは一致し、値は有効な長さと内容である必要があります。 Unicode 文字のストリングは、データベース・コード・ページで表せるストリングでなければなりません。エラーがあると、例外が生じます。

public java.sql.Connection getConnection() throws Exception

この関数は、呼び出しアプリケーションとデータベースの接続を示す JDBC オブジェクトを戻します。これは、C ストアード・プロシージャーでの NULL SQLConnect() 呼び出しの結果と似ています。

COM.ibm.db2.app.UDF

PARAMETER STYLE DB2GENERAL UDF として呼び出されるメソッドが含まれる Java クラスは、パブリックでなければならず、この Java インターフェースを実現するものでなければなりません。そのようなクラスを次のように宣言する必要があります。

public class <user-UDF-class> extends COM.ibm.db2.app.UDF{ ... }

現在実行している UDF のコンテキストでは、 COM.ibm.db2.app.UDF インターフェースのメソッドだけを呼び出せます。たとえば、UDF が戻った後には、結果設定呼び出しあるいは状況設定呼び出しなど、LOB 引き数での操作は行えません。この規則に違反すると、Java 例外が出されます。

引き数関連の呼び出しは、列索引を使用して設定する列を識別します。これは、最初の引き数の 1 から開始します。出力引き数は、入力引き数よりも大きな番号が付けられます。たとえば、3 つの入力があるスカラー UDF の場合は、出力には索引 4 が使用されます。

UDF から例外が戻されると、データベースによって捕そくされ、 SQLCODE -4302、SQLSTATE 38501 と共に発呼者に戻されます。

次のメソッドは、COM.ibm.db2.app.UDF クラスに関連付けられています。

public UDF() [default constructor]

このコンストラクターは、一連の UDF 呼び出しの最初にデータベースによって呼び出されます。これは、UDF への最初の呼び出しの前に行われます。

public void close()

この関数は、FINAL CALL オプションで UDF が作成された場合、 UDF の計算の最後にデータベースによって呼び出されます。これは、C UDF での最終呼び出しと似ています。表関数の場合、close() を呼び出すのは、 UDF メソッドに対する CLOSE 呼び出しの後 (NO FINAL CALL がコーディングされているか、または省略時値として設定されている場合)、または FINAL 呼び出しの後 (FINAL CALL がコーディングされている場合) です。 Java UDF クラスがこの関数を実現しない場合、ノーオペレーション・スタブはこのイベントを処理または無視します。

public int getCallType() throws Exception

表関数の UDF メソッドは、getCallType() を使って特定の呼び出しの呼び出しタイプを検出します。これによって次のような値が戻されます (これらの値に対する記号定義は、 COM.ibm.db2.app.UDF クラス定義で提供されています)。

public boolean isNull(int) throws Exception

この関数は、所定の索引の付いた入力引き数が SQL NULL であるかどうかをテストします。

public boolean needToSet(int) throws Exception

この関数は、所定の索引の付いた出力引き数を設定する必要があるかどうかをテストします。その列が UDF 発呼者によって使用されていない場合、 DBINFO で宣言された表 UDF についてはこのことが当てはまらない可能性があります。

public void set(int, short) throws Exception
public void set(int, int) throws Exception
public void set(int, double) throws Exception
public void set(int, float) throws Exception
public void set(int, java.math.BigDecimal) throws Exception
public void set(int, String) throws Exception
public void set(int, COM.ibm.db2.app.Blob) throws Exception
public void set(int, COM.ibm.db2.app.Clob) throws Exception

この関数は、所定の索引の付いた出力引き数を所定の値に設定します。この索引は有効な出力引き数を参照し、データ・タイプは一致し、値は有効な長さと内容である必要があります。 Unicode 文字のストリングは、データベース・コード・ページで表せるストリングでなければなりません。エラーがあると、例外が生じます。

public void setSQLstate(String) throws Exception

この関数は、この呼び出しから SQLSTATE を戻すよう設定するために、 UDF から呼び出すことができます。表 UDF は、表の終了条件を通知するために、 "02000" の付いたこの関数を呼び出す必要があります。ストリングが SQLSTATE の値として受け入れられないものである場合、例外が出されます。

public void setSQLmessage(String) throws Exception

この関数は、setSQLstate 関数と似ています。これにより、SQL メッセージの結果が設定されます。ストリングが受け入れられない (たとえば、70 文字を超えている) ものである場合、例外が出されます。

public String getFunctionName() throws Exception

この関数は、実行中の UDF の名前を戻します。

public String getSpecificName() throws Exception

この関数は、実行中の UDF の特定名を戻します。

public byte[] getDBinfo() throws Exception

この関数は、実行中の UDF の未処理の DBINFO 構造をバイト配列で戻します。まず、 DBINFO 構造をバイト配列で戻すことを DBINFO オプションで宣言しておく必要があります。

public String getDBname() throws Exception
public String getDBauthid() throws Exception
public String getDBtbschema() throws Exception
public String getDBtbname() throws Exception
public String getDBcolname() throws Exception
public String getDBver_rel() throws Exception
public String getDBplatform() throws Exception
public String getDBapplid() throws Exception

これらの関数は、実行中の UDF の DBINFO 構造から該当するフィールドの値を戻します。

public int[] getDBcodepg() throws Exception

この関数は、DBINFO 構造から SBCS、DBCS、およびデータベースの複合コード・ページ番号を戻します。戻された整数の配列には、最初の 3 つの要素に該当する番号が入れられます。

public byte[] getScratchpad() throws Exception

この関数は、現在実行中の UDF のスクラッチパッドのコピーを戻します。まず SCRATCHPAD オプションで UDF を宣言する必要があります。

public void setScratchpad(byte[]) throws Exception

この関数は、所定のバイト配列の内容で、現在実行中の UDF のスクラッチパッドを上書きします。まず SCRATCHPAD オプションで UDF を宣言する必要があります。バイト配列のサイズは、getScratchpad() が戻すサイズと同じでなければなりません。

COM.ibm.db2.app.Lob

このクラスは、ユーザー定義関数やストアード・プロシージャーの内部で計算を行うための、 Blob または Clob 一時オブジェクトを作成するユーティリティー・ルーチンを提供します。

次のメソッドは、COM.ibm.db2.app.Lob クラスに関連付けられています。

public static Blob newBlob() throws Exception

この関数は、一時的な Blob を作成します。これは、可能であれば LOCATOR を使用して実現します。

public static Clob newClob() throws Exception

この関数は、一時的な Clob を作成します。これは、可能であれば LOCATOR を使用して実現します。

COM.ibm.db2.app.Blob

このクラスのインスタンスは、BLOB を示すために UDF またはストアード・プロシージャー入力としてデータベースによって渡されます。そのインスタンスが出力として戻されることもあります。アプリケーションはインスタンスを作成することがありますが、実行中の UDF またはストアード・プロシージャーの中だけで作成します。 その外にあるオブジェクトを使用すると、例外が出されます。

次のメソッドは、COM.ibm.db2.app.Blob クラスに関連付けられています。

public long size() throws Exception

この関数は、BLOB の長さ (バイト単位) を戻します。

public java.io.InputStream getInputStream() throws Exception

この関数は、BLOB の内容を読み取るために新しい InputStream を戻します。そのオブジェクト上で、有効なシーク / マーク操作を行えます。

public java.io.OutputStream getOutputStream() throws Exception

この関数は、BLOB に何バイトか追加するために新しい OutputStream を戻します。追加したバイトは、このオブジェクトの getInputStream() 呼び出しによって作成された既存のすべての InputStream インスタンス上にすぐに反映されます。

COM.ibm.db2.app.Clob

このクラスのインスタンスは、CLOB または DBCLOB を示すために UDF またはストアード・プロシージャー入力としてデータベースによって渡されます。このインスタンスは、出力として戻されることもあります。アプリケーションはインスタンスを作成することがありますが、実行中の UDF またはストアード・プロシージャーの中だけで作成します。その外にあるオブジェクトを使用すると、例外が出されます。

Clob インスタンスは、文字をデータベース・コード・ページとして保管します。 Unicode 文字によってはこのコード・ページ形式で表せないものもあるため、変換時に例外が出されることがあります。これは、追加操作時、あるいは UDF または StoredProc set() 呼び出し時に生じる可能性があります。このことは、Java プログラマーから CLOB と DBCLOB の違いを隠すために必要です。

次のメソッドは、COM.ibm.db2.app.Clob クラスに関連付けられています。

public long size() throws Exception

この関数は、CLOB の長さ (文字単位) を戻します。

public java.io.Reader getReader() throws Exception

この関数は、CLOB または DBCLOB の内容を読み取るために新しい Reader を戻します。そのオブジェクト上で、有効なシーク / マーク操作を行えます。

public java.io.Writer getWriter() throws Exception

この関数は、この CLOB または DBCLOB に何文字か追加するために新しい Writerを戻します。追加した文字は、このオブジェクトの GetReader() 呼び出しによって作成された既存のすべての Reader インスタンス上にすぐに反映されます。

NOT FENCED ストアード・プロシージャー

DB2DARI ストアード・プロシージャーが NOT FENCED ストアード・プロシージャーとして実行されるよう指示するには、 アプリケーション構築の手引き に示されているディレクトリーの中にこれを指定してください。 NOT FENCED ストアード・プロシージャーの詳細については、 NOT FENCED ストアード・プロシージャーを参照してください。


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]