DSNTEP2 および DSNTEP4

DSNTEP2 または DSNTEP4 プログラムは、SQL ステートメントを動的に実行するために使用します。

DSNTEP4は、複数行フェッチを使用してパフォーマンスを強化していることを除いて、 DSNTEP2 と同じです。複数行フェッチが使用されると、照会のトップレベル照会ブロック内の最後の並列グループで、並列処理が使用不可になる場合があります。非常に単純な照会の場合、複数行フェッチが使用されると、照会全体で並列処理が使用不可になる場合があります。完全並列処理を行うには、DSNTEP2 を使用するか、DSNTEP4 に対してSET MULT_FETCH 1 制御オプションを指定します。

DSNTEP2 および DSNTEP4 は、その結果を、SYSPRINT DD ステートメントにより定義されているデータ・セットに書き込みます。SYSPRINT データは、133 バイトの論理レコード長である必要があります (LRECL=133)。それ以外の場合、プログラムは、異常終了コード U4038 および理由コード 1 とともに戻りコード 12 を発行します。この異常終了は、PL/I ファイル例外エラー IBM0201S ONCODE=81 により発生します。次のエラー・メッセージが発行されます。
DECLARE 属性と OPEN 属性の競合が原因で、UNDEFINEDFILE 状態が発生しました
(FILE= SYSPRINT)。 

変更の始まりアプリケーションまたはその他の自動化を使用して DSNTEP2 または DSNTEP4 からの出力を処理する場合、サービスまたは機能拡張の結果として形式に若干の変更が加えられることがある点に注意してください。 そのような変更により、これらのプログラムの出力を使用するプロセスに調整を加える必要が生じることがあります。変更の終わり

重要: SYSPRINT DD ステートメントで新規データ・セットを割り振るときには、DCB に RECFM=FBA および LRECL=133 を指定するか、あるいは DCB パラメーターを指定しないでください。

DSNTEP2 および DSNTEP4 のパラメーター

ALIGN(MID) または ALIGN(LHS)
配置を指定します。
ALIGN(MID)
DSNTEP2 または DSNTEP4 出力を中央合わせすることを指定します。デフォルトは ALIGN(MID) です。
ALIGN(LHS)
DSNTEP2 または DSNTEP4 出力を左寄せにすることを指定します。
NOMIXED または MIXED
DSNTEP2 または DSNTEP4 に DBCS 文字が含まれるかどうかを指定します。
NOMIXED
DSNTEP2 または DSNTEP4 入力に DBCS 文字 が含まれないことを指定します。デフォルトは NOMIXED です。
MIXED
DSNTEP2 または DSNTEP4 入力に DBCS 文字 が含まれることを指定します。
PREPWARN
PREPARE 時に検出される SQL 警告についての詳細を DSNTEP2 または DSNTEP4 で表示することを指定します。

PREPWARN を指定するかどうかに関わらず、PREPARE 時に SQL 警告が検出された場合、プログラムは SQLWARNING ON PREPARE というメッセージを表示して戻りコードを 4 に設定します。DSNTEP2 が REOPT(ALWAYS) を使用してバインドされている場合、増分バインドが発生したときに PREPARE の前に SQL 警告が検出されて戻りコードが 4 に設定されるのは正常な動作です。 PREPWARN を指定すると、プログラムは SQL 警告に関する詳細も表示します。

SQLFORMAT
DSNTEP2 または DSNTEP4 が SQL ステートメントを Db2® に 渡す前にどのように前処理するのかを指定します。以下のオプションの 1 つを選択してください。
SQL
SQL プロシージャー型言語以外の SQL ステートメントに推奨される モードです。デフォルトであるこのオプションを使用すると、DSNTEP2 または DSNTEP4 は、 SQL ステートメントの各行を 1 つの行に縮小してから、その ステートメントを Db2 に渡します。DSNTEP2 または DSNTEP4 は、すべての SQL コメントの廃棄も行います。
SQLCOMNT
このモードは、すべての SQL に適していますが、主に SQL プロシージャー型言語の処理 のために用意されているモードです。このオプションが有効になっている場合の動作は、 DSNTEP2 または DSNTEP4 が SQL コメントを廃棄しないことを除いて、SQL モードの動作と同様です。 コメントは廃棄されるのではなく、自動的に各 SQL コメントは、既に 1 つ以上の書式制御文字で終わっている場合を除いて、 改行文字 (16 進 25) で終わります。DSNTEP2 または DSNTEP4 による修正を最小限に 抑えて SQL プロシージャー型言語を処理する場合に、このオプションを使用してください。
SQLPL
このモードは、すべての SQL に適していますが、主に SQL プロシージャー型言語の処理 のために用意されているモードです。このオプションが有効になっている場合、DSNTEP2 または DSNTEP4 は SQL コメントを 保持し、SQL ステートメントの各行を改行文字 (16 進 25) で終了させてから、 ステートメントを Db2 に渡します。分割トークンで終了 する行は、改行文字で終了されません。SQL プロシージャー型言語の上級診断およびデバッグを行う場合に、 このモードを使用してください。
SQLTERM(termchar)
各 SQL ステートメントを終わらせるために使用する文字を指定します。表 1 にリストされた文字を除く任意の文字を使用できます。デフォルトは SQLTERM(;) です。

組み込みセミコロンが含まれているステートメントを実行する予定の場合、 セミコロン以外の文字を使用してください。

例: パラメーター SQLTERM(#) を指定して、 ステートメント終了文字として文字 # を指定すると想定します。そうすると、組み込みセミコロンのある CREATE TRIGGER ステートメントは、 次のようになります。

CREATE TRIGGER NEW_HIRE
  AFTER INSERT ON EMP
  FOR EACH ROW MODE DB2SQL
  BEGIN ATOMIC
    UPDATE COMPANY_STATS SET NBEMP = NBEMP + 1;
  END#

組み込みセミコロンのある CREATE PROCEDURE ステートメント は、次のようになります。

CREATE PROCEDURE PROC1 (IN PARM1 INT, OUT SCODE INT) 
  LANGUAGE SQL                                       
  BEGIN                                              
    DECLARE SQLCODE INT;                             
    DECLARE EXIT HANDLER FOR SQLEXCEPTION            
      SET SCODE = SQLCODE;                           
    UPDATE TBL1 SET COL1 = PARM1;                    
  END #                                              

ステートメント内で使用されない文字をステートメント終了文字として 選択するよう注意してください。

--#SET TERMINATOR 制御ステートメントを使用すると、一連の SQL ステートメント内で SQL 終了文字を変更できます。

例: 既存の SQL ステートメントのセットに、 組み込みセミコロンが含まれている CREATE TRIGGER ステートメントを追加するとします。既存のすべての SQL ステートメントに対しては、デフォルトの SQLTERM 値であるセミコロンを使用できます。 CREATE TRIGGER ステートメントを実行する前に、次のように --#SET TERMINATOR # 制御ステートメントを組み込むことによって、SQL 終了文字を文字 # に変更します。

SELECT * FROM DEPT;
SELECT * FROM ACT;
SELECT * FROM EMPPROJACT;
SELECT * FROM PROJ;
SELECT * FROM PROJACT;
--#SET TERMINATOR #
CREATE TRIGGER NEW_HIRE
  AFTER INSERT ON EMP
  FOR EACH ROW MODE DB2SQL
  BEGIN ATOMIC
    UPDATE COMPANY_STATS SET NBEMP = NBEMP + 1;
  END#

--#SET 制御ステートメントについて詳しくは、SYSIN データ・セット に関する下記の説明を参照してください。

TOLWARN
SQL 警告を受け取った後、DSNTEP2 または DSNTEP4 が SQL SELECT ステートメントの処理を続けるかどうかを示します。 以下のいずれかの値を指定できます。
NO
プログラムが SELECT ステートメントに関して OPEN または FETCH を実行する際に警告が発生した場合、プログラムがその SELECT ステートメントの処理を停止することを示します。 TOLWARN では NO がデフォルト値です。

以下の例外があります。

  • DSNTEP2 または DSNTEP4 が SELECT ステートメントの ために FETCH を実行しているときに SQLCODE +445 または SQLCODE +595 が発生した場合、プログラムはその SELECT ステートメント の処理を継続します。
  • 変更の始まりDSNTEP4 が SELECT ステートメントに対して FETCH を実行したときに SQLCODE +354 が発生した場合、プログラムは SELECT ステートメントの処理を続行します。変更の終わり
  • DSNTEP2 または DSNTEP4 が SELECT ステートメントの ために FETCH を実行しているときに SQLCODE +802 が発生した場合、プログラムは、TOLARTHWRN 制御ステートメントが YES に 設定されていれば、その SELECT ステートメントの処理を継続します。
YES
プログラムが SELECT ステートメントに関して OPEN または FETCH を実行する際に警告が発生した場合、プログラムがその SELECT ステートメントの処理を続けることを示します。

DSNTEP2 and DSNTEP4 data sets:

以下のデータ・セットが DSNTEP2 および DSNTEP4 によって使用されます。

SYSIN
入力データ・セット。このデータ・セットには、任意の数の SQL ステートメント (それぞれがセミコロンで 終わっている) を入れることができます。ステートメントは複数の行にまたがることができますが、DSNTEP2 または DSNTEP4 が読み取れるのは、 各の行の先頭 72 バイトのみです。 最後の SQL ステートメント以外のすべての SQL ステートメントは、明示的にコミットする必要があります。

DSNTEP2 または DSNTEP4 の入力データには、1 列目にアスタリスク (*)、あるいは行の任意の場所に 2 つのハイフン (--) を付けて、コメントを入力できます。アスタリスクに続くテキストは、コメント・テキストと見なされます。 2 つのハイフンに続くテキストは、コメント・テキストである場合も、制御ステートメントである場合もあります。 コメントは、動的ステートメント・キャッシュでは考慮されません。 コメントおよび制御ステートメントは、複数の行にまたがることができません。

DSNTEP2 および DSNTEP4 の入力データ・セットには、次の形式の制御ステートメントを入力できます。
--#SET control-option value

以下の制御オプションを指定できます。 このリストのいずれかのオプションに値 NO を指定した場合、プログラムは、パラメーターが指定されていないかのように動作します。

TERMINATOR
SQL ステートメント終止符。値は、DSNTIAD にリストされた文字以外の任意の 1 バイト文字です。デフォルトは、SQLTERM パラメーターの値です。
ROWS_FETCH
結果表からフェッチされる行数。value は、-1 と結果表の行数の間の数値リテラルです。-1 は、すべての行を取り出すことを意味します。デフォルトは、-1 です。
ROWS_OUT
出力データ・セットに送信されるフェッチ行の数。value は、-1 とフェッチされた行数の間の数値リテラルです。-1 は、フェッチされた行すべてを出力データ・セットに送信することを意味します。デフォルトは、-1 です。
MULT_FETCH
このオプションは、DSNTEP4 にのみ有効です。MULT_FETCH を使用して、結果表から一度にフェッチされる行数を指定します。DSNTEP4 の場合のデフォルトのフェッチ量は 100 行ですが、1 行から 32676 行までを指定できます。
TOLWARN
SQL 警告を受け取った後、DSNTEP2 または DSNTEP4 が SQL SELECT ステートメントの処理を続けるかどうかを示します。 以下のいずれかの値を指定できます。
NO
プログラムが SELECT ステートメントに関して OPEN または FETCH を実行する際に警告が発生した場合、プログラムがその SELECT ステートメントの処理を停止することを示します。 TOLWARN では NO がデフォルト値です。

以下の例外があります。

  • DSNTEP2 または DSNTEP4 が SELECT ステートメントの ために FETCH を実行しているときに SQLCODE +445 または SQLCODE +595 が発生した場合、プログラムはその SELECT ステートメント の処理を継続します。
  • 変更の始まりDSNTEP4 が SELECT ステートメントに対して FETCH を実行したときに SQLCODE +354 が発生した場合、プログラムは SELECT ステートメントの処理を続行します。変更の終わり
  • DSNTEP2 または DSNTEP4 が SELECT ステートメントの ために FETCH を実行しているときに SQLCODE +802 が発生した場合、プログラムは、TOLARTHWRN 制御ステートメントが YES に 設定されていれば、その SELECT ステートメントの処理を継続します。
YES
プログラムが SELECT ステートメントに関して OPEN または FETCH を実行する際に警告が発生した場合、プログラムがその SELECT ステートメントの処理を続けることを示します。
TOLARTHWRN
算術計算 SQL 警告 (SQLCODE +802) が戻された後で DSNTEP2 および DSNTEP4 が SQL SELECT ステートメントの処理を続行するかどうかを示します。value は NO (デフォルト) または YES です。
PREPWARN
PREPARE 時に検出される SQL 警告についての詳細を DSNTEP2 または DSNTEP4 で表示することを指定します。

PREPWARN を指定するかどうかに関わらず、PREPARE 時に SQL 警告が検出された場合、プログラムは SQLWARNING ON PREPARE というメッセージを表示して戻りコードを 4 に設定します。DSNTEP2 が REOPT(ALWAYS) を使用してバインドされている場合、増分バインドが発生したときに PREPARE の前に SQL 警告が検出されて戻りコードが 4 に設定されるのは正常な動作です。 PREPWARN を指定すると、プログラムは SQL 警告に関する詳細も表示します。

SQLFORMAT
DSNTEP2 または DSNTEP4 が SQL ステートメントを Db2 に 渡す前にどのように前処理するのかを指定します。以下のオプションの 1 つを選択してください。
SQL
SQL プロシージャー型言語以外の SQL ステートメントに推奨される モードです。デフォルトであるこのオプションを使用すると、DSNTEP2 または DSNTEP4 は、 SQL ステートメントの各行を 1 つの行に縮小してから、その ステートメントを Db2 に渡します。DSNTEP2 または DSNTEP4 は、すべての SQL コメントの廃棄も行います。
SQLCOMNT
このモードは、すべての SQL に適していますが、主に SQL プロシージャー型言語の処理 のために用意されているモードです。このオプションが有効になっている場合の動作は、 DSNTEP2 または DSNTEP4 が SQL コメントを廃棄しないことを除いて、SQL モードの動作と同様です。 コメントは廃棄されるのではなく、自動的に各 SQL コメントは、既に 1 つ以上の書式制御文字で終わっている場合を除いて、 改行文字 (16 進 25) で終わります。DSNTEP2 または DSNTEP4 による修正を最小限に 抑えて SQL プロシージャー型言語を処理する場合に、このオプションを使用してください。
SQLPL
このモードは、すべての SQL に適していますが、主に SQL プロシージャー型言語の処理 のために用意されているモードです。このオプションが有効になっている場合、DSNTEP2 または DSNTEP4 は SQL コメントを 保持し、SQL ステートメントの各行を改行文字 (16 進 25) で終了させてから、 ステートメントを Db2 に渡します。分割トークンで終了 する行は、改行文字で終了されません。SQL プロシージャー型言語の上級診断およびデバッグを行う場合に、 このモードを使用してください。
MAXERRORS
変更の始まり処理を停止する前に DSNTEP2 および DSNTEP4 が処理するエラーの数を指定します。デフォルトは 10 です。 プログラムが無制限の数のエラーを容認することを指定するには、-1 の値を使用します。変更の終わり
SYSPRINT
出力データ・セット。DSNTEP2 および DSNTEP4 は、このデータ・セットに通知メッセージとエラー・メッセージを書き込みます。DSNTEP2 および DSNTEP4 は、最大で 133 バイトの出力レコードを書き込みます。

すべてのデータ・セットを順次データ・セットとして定義してください。

DSNTEP2 および DSNTEP4 戻りコード

表 1. DSNTEP2 および DSNTEP4 戻りコード
戻りコード 意味
0 正常終了。
4 警告コードを受け取った SQL ステートメントがある。
8 エラー・コードを受け取った SQL ステートメントがある。
12 長さが 32760 バイトを超えた SQL ステートメントがあるか、 重大エラー・コード (-8nn または -9nn) を戻した SQL ステートメントがあるか、 または、SQL メッセージ・フォーマット設定ルーチンでエラーが発生した。

DSNTEP2 呼び出しの例

DSNTEP2 を使用して、DBCS 文字が含まれている可能性がある SQL SELECT ステートメントを実行するとします。また、出力を左寄せにする必要もあります。この場合の呼び出しは、次の図の ようになります。
//RUNTEP2 EXEC PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
 DSN SYSTEM(DSN)
 RUN  PROGRAM(DSNTEP2) PLAN(DSNTEPB1) PARMS('/ALIGN(LHS) MIXED TOLWARN(YES)') -
       LIB('DSN1110.RUNLIB.LOAD')
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSIN    DD *
SELECT * FROM DSN8B10.PROJ;

DSNTEP4 呼び出しの例

DSNTEP4 を使用して、DBCS 文字が含まれている可能性がある SQL SELECT ステートメントを実行し、出力を中央揃えにするとします。また、DSNTEP4 に一度に 250 行をフェッチさせる必要もあります。この場合の呼び出しは、次の図の ようになります。
//RUNTEP2 EXEC PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
 DSN SYSTEM(DSN)
 RUN  PROGRAM(DSNTEP4) PLAN(DSNTEPB1) PARMS('/ALIGN(MID) MIXED') -
       LIB('DSN1110.RUNLIB.LOAD')
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSIN    DD *
--#SET MULT_FETCH 250
SELECT * FROM DSN8B10.EMP;