ユーザー定義関数 (UDF) サンプル・プログラムにアクセスするには、以下の項目をインストールしておく必要があります。
複数の PL/I プログラムが、UDF をコーディングし、使用する方法を示すために用意されています。 以下は、それらのプログラムの使用方法を簡単に説明するものです。
ファイル UDFDLL.PLI には、5 つのサンプル UDF が格納されています。 サンプルは、本質的に単純なものですが、UDF の基本概念を示しています。
コマンド・ファイル bldudfdll を使用して、コンパイルして、udfdll ライブラリーにリンクします。
udfdll ライブラリーのコンパイルとリンクが完了したら、使用中のデータベース・インスタンスの ユーザー定義関数ディレクトリーにコピーします。 例えば、PL/I for AIX を使用していて、/u/inst1/sqllib/function が、AIX マシン上のデータベース・インスタンスに対する ユーザー定義関数ディレクトリーである場合は、udfdll をそこにコピーします。
ユーザー定義関数は、使用する前に、DB2 に対して定義しておく必要があります。 これは、CREATE FUNCTION コマンドを使用して行います。 サンプル・プログラム addudf.pli が、各 UDF に対する CREATE FUNCTION コールを実行するために用意されています。 CREATE FUNCTION コールは、例えば、以下のような形式をしています。
CREATE FUNCTION MyAdd ( INT, INT ) RETURNS INT NO SQL
LANGUAGE C FENCED VARIANT NO EXTERNAL ACTION PARAMETER
STYLE DB2SQL EXTERNAL NAME 'udfdll!MyAdd'
CREATE FUNCTION MyDiv ( INT, INT ) RETURNS INT NO SQL
LANGUAGE C FENCED VARIANT NO EXTERNAL ACTION PARAMETER
STYLE DB2SQL EXTERNAL NAME 'udfdll!MyDiv'
CREATE FUNCTION MyUpper ( VARCHAR(61) ) RETURNS VARCHAR(61) NO SQL
LANGUAGE C FENCED VARIANT NO EXTERNAL ACTION PARAMETER
STYLE DB2SQL EXTERNAL NAME 'udfdll!MyUpper'
CREATE FUNCTION MyCount ( ) RETURNS INT NO SQL
LANGUAGE C FENCED VARIANT NO EXTERNAL ACTION PARAMETER
STYLE DB2SQL EXTERNAL NAME 'udfdll!MyCount'
SCRATCHPAD
CREATE FUNCTION ClobUpper ( CLOB(5K) ) RETURNS CLOB(5K) NO SQL
LANGUAGE C FENCED VARIANT NO EXTERNAL ACTION PARAMETER
STYLE DB2SQL EXTERNAL NAME 'udfdll!ClobUpper'
上記は、CREATE FUNCTION コマンドのサンプルにすぎません。 詳細情報または改良については、DB2 マニュアルを参照してください。
コマンド・ファイル bldaddudf を使用して、addudf.pli プログラムをコンパイル、リンクします。 コンパイル、リンクが完了した後、実行して、ユーザー定義関数をデータベースに対して定義します。
上記で作成し、データベースに追加の完了したユーザー定義関数を呼び出す場合に使用できるサンプル PL/I プログラムが複数用意されています。
上記の PL/I サンプル・プログラムは、そのコンパイル、リンクが終了し、DB2 に対する UDF の定義も終了すると、コマンド行から 実行することが可能になります。
それらの UDF は、他の DB2 組み込み関数とまったく同様に、DB2 コマンド行からも呼び出すことができます。UDF のカスタマイズと活用方法の詳細については、DB2 マニュアルを参照してください。
SQL ステートメント内の PL/I ホスト変数は、ホスト変数を使用する列のタイプと互換性がなければなりません。
グラフィック・データ型は、相互に互換性があります。GRAPHIC または VARGRAPHIC の列は、固定長または可変長の PL/I グラフィック文字ホスト変数 と互換性があります。
必要に応じて、データベース・マネージャーは自動的に固定長文字ストリングを 可変長ストリングに変換したり、可変長ストリングを固定長文字ストリング に変換したりします。
構造体または共用体でないメンバーをもつ構造体の名前を、PL/I ホスト構造体の名前にすることができます。次に例を示します。
dcl 1 A,
2 B,
3 C1 char(...),
3 C2 char(...);
この例で、B はスカラー C1 と C2 からなるホスト構造体の名前です。
ホスト構造体は 2 レベルに制限されます。ホスト構造体は、ホスト変数の名前付き集合と考えることができます。
宣言の終わりにセミコロンを入力することによって、ホスト構造体変数を 区切る必要があります。次に例を示します。
dcl 1 A,
2 B char,
2 (C, D) char;
dcl (E, F) char;
ホスト変数属性は、PL/I で許容できる任意の順序で指定できます。例えば、BIN FIXED(31)、BINARY FIXED(31)、BIN(31) FIXED、および FIXED BIN(31) はすべて許容できます。
次の図は、有効なホスト構造体の構文を示しています。
>>-+-DECLARE-+--level--variable-name----------------------------> '-DCL-----' >--+----------------------+--,----------------------------------> '-Scope and/or storage-' .-,------------------------------------------. V | >----level--+-var-1-----------+--| Attributes |-+--;------------> | .-,-----. | | V | | '-(----var-2-+--)-' >--| Attributes: |----------------------------------------------> >------+-+-BINARY--+--+-FIXED--+-----------------------------+-+-+----->< | +-BIN-----+ | '-(--precision--+--------+--)-' | | | +-DECIMAL-+ | '-,scale-' | | | '-DEC-----' '-FLOAT--+-----------------+-------------' | | '-(--precision--)-' | +-+-CHARACTER-+--+---------------+--+---------+-----------+ | '-CHAR------' '-(--integer--)-' +-VARYING-+ | | '-VAR-----' | '-GRAPHIC--+---------------+--+---------+-----------------' '-(--integer--)-' +-VARYING-+ '-VAR-----'
標識変数は 2 バイトの整数 (BIN FIXED(15)) です。検索時には、関連したホスト変数にヌル値が割り当てられている かどうかを示すために、標識変数が使用されます。列への割り当て時には、ヌル値を割り当てる必要があるかどうかを 示すために、負の標識変数が使用されます。
標識変数はホスト変数と同じ方法で宣言され、両変数の宣言は プログラマーの裁量でどのように組み合わせることもできます。
次のステートメントがあるとします。
exec sql fetch Cls_Cursor into :Cls_Cd,
:Day :Day_Ind,
:Bgn :Bgn_Ind,
:End :End_Ind;変数は次のように宣言できます。
exec sql begin declare section; dcl Cls_Cd char(7); dcl Day bin fixed(15); dcl Bgn char(8); dcl End char(8); dcl (Day_Ind, Bgn_Ind, End_Ind) bin fixed(15); exec sql end declare section;
次の図は、有効な標識変数の構文を示しています。
>>-+-DECLARE-+--variable-name--+-BINARY-+--FIXED(15)--;-------->< '-DCL-----' '-BIN----'
次の図は、有効な標識配列の構文を示しています。
>>-+-DECLARE-+--+-variable-name--(--dimension--)-----------+----> '-DCL-----' | .-,------------------------------. | | V | | '-(----variable-name--(--dimension--)-+--)-' >--+-BINARY-+--FIXED(15)--;------------------------------------>< '-BIN----'
次の例では、ホスト構造体と標識配列の宣言を示し、その次に 2 つの同等な SQL ステートメントを示しています。これらのステートメントのどちらかを使用して、ホスト構造体にデータを取り込むことができます。
dcl 1 games,
5 sunday,
10 opponents char(30),
10 gtime char(10),
10 tv char(6),
10 comments char(120) var;
dcl indicator(4) fixed bin (15);
exec sql
fetch cursor_a
into :games.sunday.opponents:indicator(1),
:games.sunday.gtime:indicator(2),
:games.sunday.tv:indicator(3),
:games.sunday.comments:indicator(4);
exec sql
fetch cursor_a
into :games.sunday:indicator;
アプリケーションの接続先のデータベースは、例えば、以下のように、ホスト変数を使用して表すことができます。
exec sql connect to :dbase;
ホスト変数を指定する場合は、次のことに注意します。
dcl dbase char (10); dbase = 'SAMPLE'; /* blanks are padded automatically */ exec sql connect to :dbase;
IBM1214I W xxx.x A dummy argument is created for argument
number 6 in entry reference SQLESTRD_APIプリプロセッサーは、DECLARE TABLE ステートメントをすべて無視します。
プリプロセッサーは、DECLARE STATEMENT ステートメントをすべて無視します。
プリプロセッサーは、SQL ステートメント内で以下の変換を行います。
PL/I には、表示用の複数行メッセージに SQLCODE を変換する場合に使用できるサンプル・プログラム DSNTIAR.PLI が用意されています。この PL/I プログラムには、メインフレーム DB2* の DSNTIAR プログラムと同じ機能が備わっています。
DSNTIAR をコンパイルする場合は、DSNTIAR を使用するプログラムをコンパイルするために用いる DEFAULT と SYSTEM コンパイル時オプションと同じものを使用する必要があります。
呼び出し側が、メインフレーム DB2 資料の説明通りに、エントリーを宣言し、インターフェースに従う必要があります。ご参考までに、宣言文は、以下のような形式をとります。
dcl dsntiar entry options(asm inter retcode);
3 つの引数を常に引き渡します。
dcl 1 Message,
2 Buffer_length fixed bin(15) init(n), /* input */
2 User_buffer char(n); /* output */ n には、該当する値を入力します。
コンパイル時オプション DFT(EBCDIC NONNATIVE) を指定し、データベースへの入力として、可変長ストリング・ホスト変数を使用する場合は、ホスト変数を初期設定する必要があり、その初期設定を怠ると、プログラムの実行時に、記憶保護例外が発生する可能性があります。
メインフレーム DB2 で、未初期設定の可変長ストリングを使用すると、プログラムは、エラー状態になり、記憶保護例外も引き起こす場合があります。
入力/出力文字ホスト変数を含む SQL ステートメントでコンパイル時オプション DEFAULT(EBCDIC) を使用すると、SQL プリプロセッサーは、文字データが、FOR BIT DATA 列属性を持っていない場合に限り、追加のコードを SQL ステートメントの拡張部に挿入し、ASCII と EBCDIC の間で文字データを変換します。
データを変換しない場合は、プリプロセッサーに対して明示的にコマンドを指定する必要があります。例えば、CHARACTER 変数と FOR BIT DATA 列間の変換を行う必要のない場合は、以下の例に示すように PL/I コメントを挿入することもできます。
dcl SL1 /* %ATTR FOR BIT DATA */ char(9);
コメント内の最初の非ブランク文字は、パーセント (%) 記号にし、その後に、キーワード ATTR FOR BIT DATA を続ける必要があります。
このコメントは、変数の宣言文の最後までに存在する限り、変数名の後の任意の箇所に置くことができます。以下の例では、SL2 と SL4 は、いずれも変換されません。
Dcl SL2 /* %ATTR FOR BIT DATA */ char(9),
SL3 char (20); /* %ATTR FOR BIT DATA */
Dcl (SL4 /* %ATTR FOR BIT DATA */,
SL5) char (9);
DEFAULT(EBCDIC) を使用したことで行われる変換を回避する別の方法は、DCLGEN ユーティリティーを使用することです。 DCLGEN ユーティリティーは、データベース・テーブルに対する宣言文を作成するため、PL/I for Windows に添付されています。
DCLGEN は、列が FOR BIT DATA 属性で定義されていると認識すると、必要なコメント・ディレクティブを出力内に自動的に生成します。
10 進数フィールドを記述する SQLDA とともにコンパイル時オプション DEFAULT(NONNATIVE) を使用する場合は、SQL プリプロセッサーによる変換の終了後に、SQLLEN フィールドを再反転する必要があります。