PARAMETER STYLE DB2GENERAL UDF およびストアード・プロシージャーは Java で作成されるので、これ以降は単に Java UDF およびストアード・プロシージャーと呼びます。 DB2GENERAL UDF およびストアード・プロシージャーを作成することは、サポートされている他のプログラム言語で UDF およびストアード・プロシージャーを作成することと非常によく似ています。いったんそれらを作成して登録すると、どの言語のプログラムからでも呼び出すことができます。一般的に、ストアード・プロシージャーから JDBC API を呼び出すことはできますが、 UDF からそれらを呼び出すことはできません。
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 |
注:
|
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 ストアード・プロシージャーは、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 つです。
以下の節では、これらのクラスの動作のパブリックな要素を説明します。
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() 呼び出しの結果と似ています。
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() が戻すサイズと同じでなければなりません。
このクラスは、ユーザー定義関数やストアード・プロシージャーの内部で計算を行うための、 Blob または Clob 一時オブジェクトを作成するユーティリティー・ルーチンを提供します。
次のメソッドは、COM.ibm.db2.app.Lob クラスに関連付けられています。
public static Blob newBlob() throws Exception
この関数は、一時的な Blob を作成します。これは、可能であれば LOCATOR を使用して実現します。
public static Clob newClob() throws Exception
この関数は、一時的な Clob を作成します。これは、可能であれば LOCATOR を使用して実現します。
このクラスのインスタンスは、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 インスタンス上にすぐに反映されます。
このクラスのインスタンスは、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 インスタンス上にすぐに反映されます。
DB2DARI ストアード・プロシージャーが NOT FENCED ストアード・プロシージャーとして実行されるよう指示するには、 アプリケーション構築の手引き に示されているディレクトリーの中にこれを指定してください。 NOT FENCED ストアード・プロシージャーの詳細については、 NOT FENCED ストアード・プロシージャーを参照してください。