PREPARE

呼び出し

このステートメントは、アプリケーション・プログラム、SQL 関数、 SQL プロシージャー、またはトリガー内にのみ組み込むことができます。 これは実行可能ステートメントですが、動的に準備することはできません。Java™ では指定できません。

権限

権限の規則は、その PREPARE ステートメントに指定された SQL ステートメントに対して定義されている規則と同じです。 例えば、SELECT ステートメントを準備する場合に適用される権限規則については、 選択ステートメントを参照してください。

CRTSQLxxx コマンドに DLYPRP(*NO) が指定されていると、以下の場合を除き、 権限の検査は該当のステートメントが準備される時点で行われます。

• DROP SCHEMA ステートメントが準備済みの場合、スキーマの中の全オブジェクトに対する特権は、そのステートメントが実行されるまで検査されません。
• DROP TABLE ステートメントが準備済みの場合、該当の表を参照するすべてのビュー、索引、および論理ファイルに対する特権は、そのステートメントが実行されるまで検査されません。
• DROP VIEW ステートメントが準備済みの場合、そのビューを参照するすべてのビューに対する特権は、そのステートメントが実行されるまで検査されません。
• CREATE TRIGGER ステートメントが準備済みの場合、トリガー・アクション で参照されるオブジェクトに対する特権は、ステートメントが実行されるまで検査されません。
• FUNCTION、PROCEDURE、SEQUENCE、TYPE、TRIGGER、VARIABLE、または XSROBJECT ステートメントの DROP、COMMENT、または LABEL が準備済みの場合、権限は、そのステートメントが実行されるまで検査されません。
• GRANT または REVOKE ステートメントが準備済みの場合、権限は、そのステートメントが実行されるまで検査されません。

CRTSQLxxx コマンドに DLYPRP(*YES) が指定されている場合、該当のステートメントが実行されるか、 または OPEN ステートメントで使用されるまで、権限の検査はすべて据え置かれます。

ステートメントの権限 ID は、 プログラムが作成されたときに CRTSQLxxx コマンドに USRPRF(*OWNER) および DYNUSRPRF(*OWNER) が 指定された場合を除いて、実行時の権限 ID です。詳しくは、権限 ID と権限名を参照してください。

ステートメントでグローバル変数を参照する場合は、ステートメントの権限 ID が保持する特権に、少なくとも次のいずれか 1 つが含まれなければなりません。

• ステートメント内で識別されるグローバル変数に対して、
  • そのグローバル変数に対する READ 特権
  • そのグローバル変数を含むライブラリーに対する *EXECUTE システム権限
• データベース管理者権限

説明

statement-name

準備済みステートメントの名前を指定します。 この名前に、既存の準備済みステートメントを指定すると、 その準備済みステートメントは次の場合に破棄されます。

• そのステートメントが同じプログラムの同じインスタンス内で準備された場合。
• 両方のステートメントに関連した CRTSQLxxx コマンドに CLOSQLCSR(*ENDJOB)、 CLOSQLCSR(*ENDACTGRP)、 または CLOSQLCSR(*ENDSQL) が指定されている場合。

この名前に、プログラムの同じインスタンスの中のオープン・カーソルに関連する SELECT ステートメントを指定してはなりません。

USING SQL DESCRIPTOR SQL-descriptor-name

SQL 記述子を識別します。USING が指定されると、PREPARE ステートメントが正常に実行されたときに、準 備済みステートメントに関する情報が、SQL 記述子名 で指定した SQL 記述子内に入ります。したがって、次の PREPARE ステートメントは、

   EXEC SQL PREPARE S1 USING SQL DESCRIPTOR :sqldescriptor FROM :V1;

上記のステートメントは、次のステートメントと同等です。

   EXEC SQL PREPARE S1 FROM :V1;
   EXEC SQL DESCRIBE S1 USING SQL DESCRIPTOR :sqldescriptor;

LOCAL

記述子の名前の有効範囲はプログラム呼び出しのローカルであることを指定します。

GLOBAL

記述子の名前の有効範囲は SQL セッション全体であることを指定します。

SQL-descriptor-name

SQL 記述子の名前を指定します。名前は、指定の有効範囲を持つ既存の記述子を識別するものでなければなりません。

SQL 記述子に入る情報の説明については、GET DESCRIPTORを参照してください。

INTO

INTO を使用すると、PREPARE ステートメントが正常に実行されたときに、準 備済みステートメントに関する情報が、記述子名 で指定した SQLDA 内に入ります。 したがって、次の PREPARE ステートメントは、

   EXEC SQL PREPARE S1 INTO :SQLDA FROM :V1;

上記のステートメントは、次のステートメントと同等です。

   EXEC SQL PREPARE S1 FROM :V1;
   EXEC SQL DESCRIBE S1 INTO :SQLDA;

descriptor-name

SQL 記述子域 (SQLDA) を指定します。これについては、SQLDA (SQL 記述子域)で説明しています。PREPARE ステートメントを実行する前に、SQLDA に次の変数を設定しておく必要があります。(REXX の場合の規則は異なります。 詳しくは、「組み込み SQL プログラミング」トピック集を参照してください。):

SQLN

SQLVAR によって表される変数の個数を示します。 (SQLN によって、SQLVAR 配列の大きさ (エレメント数) が指定されます。) SQLN は PREPARE ステートメントの実行に先立ってゼロよりも大きいか、または等しい値に設定しなければなりません。 必要なオカレンスの数を決定する手法については、必要な SQLVAR オカレンスの数の決定を参照してください。

SQLDA に入れられる情報の説明については、DESCRIBEを参照してください。

USING

SQLDA のそれぞれの SQLNAME 変数に、どのような値を割り当てるかを 指定します。要求した値が存在しない場合または名前が 30 より長い場合、SQLNAME の長さは 0 にセットされます。

NAMES

列の名前を割り当てます。これはデフォルトです。準備されたステートメントで名前がその選択リストに明示的に指定されている場合、 指定されたそれらの名前が戻されます。

SYSTEM NAMES

列のシステム列名を割り当てます。

LABELS

列のラベルを割り当てます。(列のラベルは、LABEL ステートメントによって定義されます。) ラベルの最初の 20 バイトだけが戻されます。

ANY

列のラベルを割り当てます。列がラベルを持たない場合、ラベルとして列名が使用されます。

BOTH

列のラベルと名前の両方を割り当てます。この場合、追加情報に応じ るために、1 つの列ごとに SQLVAR の 2 つから 3 つのオカレンスが必要になり ますが、その数は、結果セットに特殊タイプが入っているか否かによって決 まります。この拡張の SQLVAR 配列を指定するには、SQLN を 2*n か 3*n (この場合の n は、表やビュー内の列数) に設定します。 SQLVAR の最初の n 個のオカレンスには、列の名前が入り、 2 番目または 3 番目の n オカレンスには、列のラベルが含まれます。 特殊タイプがない場合、SQLVAR 項目の 2 番目のセットにそのラベルが戻されます。 それ以外の場合、ラベルは、SQLVAR 項目の 3 番目のセット内に戻されます。

同じ SQLDA を以後の FETCH ステートメントで使用する場合には、 その PREPARE が完了したあと、SQLN を n に設定してください。

ALL

ラベル、列名、およびシステム列名を割り当てます。この場合、追加情報に応じるために、 1 つの列ごとに SQLVAR の 3 つから 4 つのオカレンスが必要になりますが、その数は、 結果セットに特殊タイプが入っているか否かによって決まります。この拡張の SQLVAR 配列を指定するには、SQLN を 3*n か 4*n (この場合の n は、結果表内の列数) に設定します。 SQLVAR の最初の n オカレンスには、システム列名が入ります。 2 番目または 3 番目の n オカレンスには、列のラベルが含まれます。 列名がシステム列名とは異なる場合、列名は 3 番目または 4 番目の n オカレンスに含まれます。 特殊タイプが指定されていない場合、ラベルは、SQLVAR 記入項目の 2 番目のセット内に戻され、 列名は、SQLVAR 記入項目の 3 番目のセット内に戻されます。 それ以外の場合、ラベルは、SQLVAR 記入項目の 3 番目のセット内に戻され、列名は、 SQLVAR 記入項目の 4 番目のセット内に戻されます。

同じ SQLDA を以後の FETCH ステートメントで使用する場合には、 その PREPARE が完了したあと、SQLN を n に設定してください。

ATTRIBUTES attr-variable

対応する属性が、関連付けられた SELECT ステートメントの最外部の全選択の一部として指定されていない場合に、このカーソルに有効な属性を指定します。属性が最外部の全選択に指定されている場合、それらは PREPARE ステートメント上で指定された対応する属性の代わりに使用されます。逆に、属性が PREPARE ステートメントに指定されている場合、DECLARE CURSOR ステートメントに指定された対応する属性の代わりにそれらの属性が使用されます。

作成したステートメントが select-statement ではない場合、USE CURRENTLY COMMITTED および WAIT FOR OUTCOME 以外のすべての属性は無視されます。

attr-variable は、ストリング変数の宣言に関する規則に従ってプログラム内で宣言される、文字ストリングまたは Unicode グラフィック変数を識別する必要があります。属性変数 は、長さ属性が VARCHAR の最大長を超えない ストリング変数 (固定長または可変長のいずれか) でなければなりません。 先頭ブランクおよび末尾ブランクは、変数の値から除去されます。 変数には、有効な属性ストリング が含まれている必要があります。

標識変数を使用して、属性が PREPARE ステートメント上に実際に指定されているかどうかを示すことができます。このようにして、属性を指定する必要があるかどうかには関係なく、 アプリケーションは同じ PREPARE ステートメントを使用できます。 attribute-string の一部として指定できるオプションは以下のとおりです。

ASENSITIVE、SENSITIVE、または INSENSITIVE

カーソルが変更に対して反応を決めない、反応する、または反応しないことを指定します。 詳しくは、DECLARE CURSORを参照してください。

SENSITIVE を指定した場合、FETCH FIRST 文節 は指定できません。 INSENSITIVE を指定した場合、UPDATE 文節 は指定できません。

NO SCROLL または SCROLL

カーソルがスクロール可能かどうかを指定します。詳しくは、DECLARE CURSORを参照してください。

WITHOUT HOLD または WITH HOLD

コミット操作の結果として、カーソルがクローズされるのを防止するかどうかを指定します。 詳しくは、DECLARE CURSORを参照してください。

WITHOUT RETURN または WITH RETURN

カーソルの結果表をプロシージャーから戻される結果セットとして使用するかどうか指定します。 詳しくは、DECLARE CURSORを参照してください。

offset-clause

行が取得される前にスキップする行の数を指定します。 詳しくは、offset-clauseを参照してください。 offset-row-count は定数でなければなりません。

offset-clause を指定した場合、update-clause は指定できません。

fetch-first-clause

最大数の行を検索するように指定します。 詳しくは、FETCH FIRST 文節を参照してください。 fetch-first-row-count は定数でなければなりません。

FETCH FIRST 文節 を指定した場合、UPDATE 文節 は指定できません。

READ-ONLY 文節 または UPDATE 文節

結果表が読み取り専用であるか更新可能であるかを指定します。 UPDATE 文節 は、列名なしで指定する必要があります (FOR UPDATE)。 詳しくは、READ-ONLY 文節、および UPDATE 文節を参照してください。

optimize-clause

データベース・マネージャーが、プログラムが整数 で指定された行数を超えて 結果表から検索を行う意図はないことを想定するように指定します。 詳しくは、OPTIMIZE 文節を参照してください。

isolation-clause

SELECT ステートメントを実行する分離レベルを指定します。 詳しくは、ISOLATION 文節を参照してください。

concurrent-access-resolution-clause

SELECT ステートメントで使用する並行アクセスの解決方法を指定します。詳しくは、concurrent-access-resolution-clauseを参照してください。

WITHOUT EXTENDED INDICATORS または WITH EXTENDED INDICATORS

INSERT または UPDATE の実行中に標識変数に指定された値が NULL 値を示すための標準 SQL セマンティクスに従っているかどうか、または拡張機能を使用して DEFAULT または UNASSIGNED 値の割り当てを示すことができるかどうかを指定します。

WITH EXTENDED INDICATORS を指定する必要があるのは、このステートメントが INSERT ステートメントの VALUES 形式を使用する INSERT である場合、UPDATE ステートメントである場合、またはこのステートメントに INSERT ステートメントの VALUES 形式を使用する INSERT が含まれる場合のみです。

WITHOUT ROW CHANGE COLUMNS、WITH ROW CHANGE COLUMNS POSSIBLY DISTINCT 、または WITH ROW CHANGE COLUMNS ALWAYS DISTINCT

準備された選択ステートメント の結果セットに列を追加するかどうかを指定します。この列は後で、その行の列の値が変更された可能性があるかどうかを識別するために使用できます。 この行変更列は、単一の表 (または更新可能ビュー) が最外部の副選択で参照される場合にのみ追加されます。 DESCRIBE および GET DESCRIPTOR ステートメントは、どの行が追加されたかを示します。

WITHOUT ROW CHANGE COLUMNS

行変更列は、結果セットには追加されません。これはデフォルトです。

WITH ROW CHANGE COLUMNS POSSIBLY DISTINCT

行変更列は、単一の行を一意的に表していない場合でも結果セットに追加されます。 追加された列を使用して、その行の列の値が最初に取り出された後に変更された可能性があるかどうかを判別することができます。

• 行変更列の値が最初の取り出し以降に変更されていない場合は、その行のどの列も最初の取り出し以降に変更されていません。
• 行変更列の値が最初の取り出し以降に変更された場合は、行変更値が単一の行を表しているかどうかが確実ではないため、その行の列は変更された可能性も、変更されていない可能性もあります。

WITH ROW CHANGE COLUMNS ALWAYS DISTINCT

行変更列は、単一の行を一意的に表している場合にのみ結果セットに追加されます。 そうでない場合、行変更列は結果セットに追加されません。 追加された列を使用して、その行の列の値が最初の取り出し以降に変更されたかどうかを判別することができます。 (行の行変更列が確実に単一の行を一意的に識別するには、表に行変更タイム・スタンプ列が必要となることに注意してください。)

• 行変更列の値が最初の取り出し以降に変更されていない場合は、その行のどの列も最初の取り出し以降に変更されていません。
• 行変更列の値が最初の取り出し以降に変更された場合、その行の列は変更されています。

WITH ROW CHANGE COLUMNS ALWAYS DISTINCT が指定され、データベース・マネージャーが特殊な行変更列を返すことができない場合は、警告が返されます (SQLSTATE 0168T)。

FROM

ステートメント・ストリングを指定します。ステートメント・ストリングは、指定される式、ストリング式、 または変数 の値です。

variable

variable を識別します。この変数は、文字ストリングまたは Unicode グラフィック変数の宣言に関する規則に従ってプログラム内で宣言されます。この変数に、標識変数を指定してはなりません。

expression

集約関数または列名を含まない、式で説明されているタイプの式。 これは、文字ストリングまたは Unicode グラフィック・ストリングの 値を戻す必要があります。式 の中に 変数が指定される場合、その変数の CCSID は 65535 であってはなりません。¹

ステートメント・ストリング は、以下の SQL ステートメントのいずれかである必要があります。

ALLOCATE CURSOR	INSERT	SET CURRENT DEGREE
ALTER	LABEL	SET CURRENT IMPLICIT XMLPARSE OPTION
ASSOCIATE LOCATORS	LOCK TABLE	SET CURRENT TEMPORAL SYSTEM_TIME
CALL	MERGE	SET ENCRYPTION PASSWORD
COMMENT	REFRESH TABLE	SET PATH
COMMIT	RELEASE SAVEPOINT	SET SCHEMA
コンパウンド (動的)	RENAME	SET SESSION AUTHORIZATION
CREATE	REVOKE	SET TRANSACTION
DECLARE GLOBAL TEMPORARY TABLE	ROLLBACK	SET 変数2
DELETE	SAVEPOINT	TRANSFER OWNERSHIP
DROP	select-statement	TRUNCATE
FREE LOCATOR	SET CURRENT DEBUG MODE	UPDATE
GRANT	SET CURRENT DECFLOAT ROUNDING MODE	VALUES INTO
HOLD LOCATOR

ステートメント・ストリングは、次のようなストリングであってはなりません。

• EXEC SQL で始める。
• END-EXEC またはセミコロンで終了する。
• 変数への参照を含むストリング。グローバル変数を使用できます。

注

パラメーター・マーカー: ステートメント・ストリングには変数への参照を入れることはできませんが、パラメーター・マーカー を含めることはできます。パラメーター・マーカーは、準備されたステートメントの実行時点で、変数の値によって置き換えられます。 パラメーター・マーカーは疑問符 (?) で表し、そのステートメント・ストリングが静的 SQL ステートメントで あった場合に変数を使用することができる個所で使用します。パラメーター・マーカーが、 値によってどのように置き換えられるかについては、OPENおよび EXECUTEを参照してください。

パラメーター・マーカーには、次の 2 つのタイプがあります。

型付きパラメーター・マーカー

ターゲット・データ・タイプが一緒に指定されているパラメーター・マーカー。 その汎用形式は、次のとおりです。

   CAST(? AS データ・タイプ)

この表記は関数呼び出しではありませんが、実行時のそのパラメーターのタイプが指定のデータ・タイプになるか、指定のデータ・タイ プに変換できるデータ・タイプになることを「約束」します。 例えば、次の場合、

  UPDATE EMPLOYEE
    SET LASTNAME = TRANSLATE(CAST(? AS VARCHAR(12)))
   WHERE EMPNO = ?

TRANSLATE 関数の引数の値は、実行時に提供されます。その値のデータ・タイプは、VARCHAR(12)、あるいは VARCHAR(12) に 変換できるデータ・タイプになります。 詳しくは、CAST の指定を参照してください。

型なしパラメーター・マーカー

ターゲット・データ・タイプが指定されていないパラメーター・マーカー。その形式は、単一の疑問符 (?) です。 型なしパラメーター・マーカーのデータ・タイプは、コンテキストによって提供されます。例えば、上記の更新ステートメントの述部にある型なしパラメーター・マーカーは、EMPNO 列のデータ・タイプと同じになります。

タイプ付きパラメーター・マーカーは、変数がサポートされており、 データ・タイプが CAST 関数の約束に基づいていれば、動的 SQL ステートメント内のどこでも使用できます。

エラー検査: PREPARE ステートメントが実行されると、 ステートメント・ストリングが解析され、エラーがないか検査されます。 ステートメント・ストリングが無効な場合は、準備済みステートメントは作 成されず、エラーが戻されます。

ローカルおよびリモート処理では、DLYPREP(*YES) オプションを指定すると 、一部の SQL ステートメントで「遅延」エラーを受け取ることがあります。 例えば、DESCRIBE、EXECUTE、および OPEN で、通常は PREPARE 処理中に 出される SQLCODE を受け取ることがあります。

参照および実行の規則: 準備済みステートメントは、以下のようなステートメントから参照 できます (ただし、ステートメントによっては、参照できる準備済みステ ートメントが制約されることがあります)。

準備済みステートメントは、何度でも実行することができます。 準備済みステートメントを一度しか実行せず、ステートメントの中でパラメ ーター・マーカーも使用しない場合は、PREPARE ステートメントと EXECUTE ステートメントを使用するより、EXECUTE IMMEDIATE ステートメントを使用 した方が効率的です。

拡張標識の使用法: EXTENDED INDICATORS 節 は、拡張標識変数値が UPDATE ステートメントの SET 割り当て文節、INSERT ステートメントの VALUES 式リスト、 または MERGE ステートメントの挿入操作または更新操作において使用可能かどうかを 示します。

拡張標識変数とエラー検査の据え置き: 拡張標識変数が使用可能な場合、UNASSIGNED 標識変数値により、ステートメントから確実にそのターゲット列が除外されます。 このため、通常はステートメント準備中に行われる妥当性検査は、ステートメントの実行時まで遅延されます。

準備済みステートメントの持続性: 準備済みステートメントはすべて、次の場合に破棄されます。 ⁷

• CONNECT (タイプ 1) ステートメントが実行された場合。
• 準備済みステートメントが関連する接続が、DISCONNECT ステートメントにより切り離された場合。
• 準備済みステートメントが解除保留の接続に関連し、正常なコミットが行われた場合。
• SQL ステートメントに関連した有効範囲 (ジョブ、活動化グループ、ま たはプログラム) が終了した場合。

ステートメントの有効範囲: statement-name の有効範囲は、それが定義されているソース・プログラムです。準備済みステートメントを他の SQL ステートメントから参照できるのは、 その SQL ステートメントが PREPARE ステートメントによってプリコンパイルされたものである場合だけです。 例えば、別にコンパイルされた他のプログラムから呼び出されたプログラムは、 呼び出し側プログラムによって作成された準備済みステートメントを使用することができません。

また、ステートメント名の有効範囲は、そのステートメントを含むプログラムが実行しているスレッドに限定されます。 例えば、同じジョブの中にある別々の 2 つのスレッドで同じプログラムが実行している場合、2 番目のスレッドは、 最初のスレッドが準備したステートメントを使用することができません。

ステートメントが定義されているプログラムがそのステートメントの有効範囲ですが、 そのプログラムから作成された各パッケージはそれぞれ準備されたステートメントの別個のインスタンスを含み、 実行時に準備されたステートメントが複数存在することがあります。例えば、CONNECT (タイプ 2) ステートメントを使用して、 次の順序でロケーション X とロケーション Y に接続するプログラムを想定します。

S の 2 番目の準備は、Y で S の別個のインスタンスを準備します。

CRTSQLxxx コマンドに CLOSQLCSR(*ENDJOB)、CLOSQLCSR(*ENDACTGRP)、または CLOSQLCSR(*ENDSQL) が 指定されていない場合、準備済みステートメントを参照できるのは、プログラム・スタックにある プログラムの同一のインスタンスに制限されます。

• CLOSQLCSR(*ENDJOB) が指定されている場合、 プログラム・スタックにあるそのプログラム (ステートメントを準備したプログラム) の どのインスタンスでも準備済みステートメントを参照できます。この場合、 準備済みステートメントはジョブの終わりに破棄されます。
• CLOSQLCSR(*ENDSQL) が指定されている場合、 プログラム・スタック内の最後の SQL プログラムが終了するまでの間、 プログラム・スタックにあるそのプログラム (ステートメントを準備したプログラム) のどのインスタンスでも、 準備済みステートメントを参照できます。 この場合、準備済みステートメントはプログラム・スタックの最後の SQL プログラムが終了すると破棄されます。
• CLOSQLCSR(*ENDACTGRP) が指定されている場合、その活動化グループが終了するまでは、 そのステートメントを準備したプログラムのモジュールのすべてのインスタンスで、その準備済みステートメントを参照できます。 この場合、準備済みステートメントは活動化グループが終了すると破棄されます。

SQL 記述子の割り振り: USING 文節が指定される場合、PREPARE ステートメントを実行する前に、ALLOCATE DESCRIPTOR ステートメントを使用して SQL 記述子を割り振らなければなりません。 割り振られた記述子項目の数が結果列の数よりも小さい場合、警告 (SQLSTATE 01005) が戻されます。

PREPARE および *LIBL: 通常、オブジェクトの非修飾名は、ステートメントが準備される際に解決されます。 したがって、ステートメントが準備された後に CURRENT SCHEMA または CURRENT PATH が変更されても、ステートメントの実行またはオープン時にどのオブジェクトが参照されるかに対しては影響しません。 ただし、システム名が使用され、オブジェクト名が *LIBL で暗黙に修飾されている場合、オブジェクトは実行時またはオープン時に解決されます。 ステートメントが準備された後、ただし、実行時またはオープン時より前にライブラリー・リストが変更されると、ステートメントの実行時またはオープン時にどのオブジェクトが参照されるかに影響します。

例

例 1: COBOL プログラムで、選択ステートメント 以外のステートメントを準備して実行します。 このステートメントは、変数 HOLDER に入っているものとします。プ ログラムでは、ユーザーからの何らかの指示に基づいて、変数 HOLDER にステートメント・ストリングを入れます。準備するステートメントには、パラメーター・マーカーは入っていません。

例 2: 例 1 と同様に、選択ステートメント 以外のステートメントを準備して実行し ますが、準備するステートメントには、任意の数のパラメーター・マーカー を含めることができるものとします。

以下のステートメントを準備するものとします。

部門番号 G01、部門名 COMPLAINTS、管理者なし、報告先部門は部門 A00 という行を挿入するとすれば、 EXECUTE ステートメントを実行する前に、構造体 INSERT_DA には次のような値が入っていなければなりません。