Rational Developer for System z
PL/I for Windows, Version 8.0, プログラミング・ガイド

ユーザー定義関数のサンプル・プログラム

ユーザー定義関数 (UDF) サンプル・プログラムにアクセスするには、以下の項目をインストールしておく必要があります。

複数の PL/I プログラムが、UDF をコーディングし、使用する方法を示すために用意されています。 以下は、それらのプログラムの使用方法を簡単に説明するものです。

ファイル UDFDLL.PLI には、5 つのサンプル UDF が格納されています。 サンプルは、本質的に単純なものですが、UDF の基本概念を示しています。

MyAdd
2 つの整数を加算して、第 3 の整数に結果を戻します。
MyDiv
2 つの整数を除算して、第 3 の整数に結果を戻します。
MyUpper
小文字の a、e、i、o、u をすべて大文字に変更します。
MyCount
スクラッチパッドを使用したカウンター機能を簡単に実現したものです。
ClobUpper
CLOB 内の小文字の a、e、i、o、u をすべて大文字に変更した後、ファイルに書き込みます。

コマンド・ファイル 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 プログラムが複数用意されています。

UDFMYADD.PLI
STAFF テーブルから ID Dept を取り出した後、MyAdd UDF を呼び出して、それらを一緒に 追加します。 コマンド・ファイル bldmyadd を使用して、このプログラムをコンパイル、リンクします。
UDFMYDIV.PLI
STAFF テーブルから ID Dept を取り出した後、MyDiv UDF を呼び出して、それらを除算します。 コマンド・ファイル bldmydiv を使用して、このプログラムをコンパイル、リンクします。
UDFMYUP.PLI
STAFF テーブルから Name を取り出した後、MyUpper 呼び出し、母音字を大文字に変更します。コマンド・ファイル bldmyup を使用して、このプログラムをコンパイル、リンクします。
UDFMYCNT.PLI
STAFF テーブルから ID を取り出し、コール数を出力した後、ID をコール数で除算します。コマンド・ファイル bldmycnt を使用して、このプログラムをコンパイル、リンクします。
UDFCLOB.PLI
従業員 '000150' の経歴を取り出した後、ClobUpper を呼び出し、母音文字を大文字に変更します。 コマンド・ファイル bldclobu を使用して、このプログラムをコンパイルおよびリンクします。 プログラムの実行後、ファイル udfclob.txt を調べ、結果をチェックします。

上記の PL/I サンプル・プログラムは、そのコンパイル、リンクが終了し、DB2 に対する UDF の定義も終了すると、コマンド行から 実行することが可能になります。

それらの UDF は、他の DB2 組み込み関数とまったく同様に、DB2 コマンド行からも呼び出すことができます。UDF のカスタマイズと活用方法の詳細については、DB2 マニュアルを参照してください。

SQL データ型と PL/I データ型の互換性の判別

SQL ステートメント内の 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;

CONNECT TO ステートメント

アプリケーションの接続先のデータベースは、例えば、以下のように、ホスト変数を使用して表すことができます。

  exec sql connect to :dbase;

ホスト変数を指定する場合は、次のことに注意します。

DECLARE TABLE ステートメント

プリプロセッサーは、DECLARE TABLE ステートメントをすべて無視します。

DECLARE STATEMENT ステートメント

プリプロセッサーは、DECLARE STATEMENT ステートメントをすべて無視します。

論理 NOT 記号 (¬)

プリプロセッサーは、SQL ステートメント内で以下の変換を行います。

SQL エラー戻りコードの処理

PL/I には、表示用の複数行メッセージに SQLCODE を変換する場合に使用できるサンプル・プログラム DSNTIAR.PLI が用意されています。この PL/I プログラムには、メインフレーム DB2* の DSNTIAR プログラムと同じ機能が備わっています。

DSNTIAR をコンパイルする場合は、DSNTIAR を使用するプログラムをコンパイルするために用いる DEFAULT と SYSTEM コンパイル時オプションと同じものを使用する必要があります。

呼び出し側が、メインフレーム DB2 資料の説明通りに、エントリーを宣言し、インターフェースに従う必要があります。ご参考までに、宣言文は、以下のような形式をとります。

  dcl dsntiar entry options(asm inter retcode);

3 つの引数を常に引き渡します。

arg 1
この入力引数は、必ず SQLCA とします。
arg 2
この入出力引数は、以下の形式の構造体とします。
  dcl 1 Message,
        2 Buffer_length fixed bin(15) init(n), /* input  */
        2 User_buffer char(n);         /* output */
n には、該当する値を入力します。
arg 3
この入力引数は、論理レコード長を指定する FIXED BIN(31) 値とします。

DFT(EBCDIC NONNATIVE) のもとでの可変長ストリングの使用

コンパイル時オプション DFT(EBCDIC NONNATIVE) を指定し、データベースへの入力として、可変長ストリング・ホスト変数を使用する場合は、ホスト変数を初期設定する必要があり、その初期設定を怠ると、プログラムの実行時に、記憶保護例外が発生する可能性があります。

メインフレーム DB2 で、未初期設定の可変長ストリングを使用すると、プログラムは、エラー状態になり、記憶保護例外も引き起こす場合があります。

DEFAULT(EBCDIC) コンパイル時オプションの使用

入力/出力文字ホスト変数を含む 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);
DCLGEN を使用する自動変換の回避

DEFAULT(EBCDIC) を使用したことで行われる変換を回避する別の方法は、DCLGEN ユーティリティーを使用することです。 DCLGEN ユーティリティーは、データベース・テーブルに対する宣言文を作成するため、PL/I for Windows に添付されています。

DCLGEN は、列が FOR BIT DATA 属性で定義されていると認識すると、必要なコメント・ディレクティブを出力内に自動的に生成します。

DEFAULT(NONNATIVE) コンパイル時オプションの使用

10 進数フィールドを記述する SQLDA とともにコンパイル時オプション DEFAULT(NONNATIVE) を使用する場合は、SQL プリプロセッサーによる変換の終了後に、SQLLEN フィールドを再反転する必要があります。


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)