PREPARE ステートメント

呼び出し

このステートメントは、アプリケーション・プログラムに組み込む方法のみ可能です。 これは、動的に作成できない実行可能ステートメントです。

許可

ステートメントの準備時に許可検査が行われるステートメント (DML) の場合、 ステートメントの許可 ID の特権には、 PREPARE ステートメントで指定されている SQL ステートメントの実行に必要な特権が含まれていなければなりません。 ステートメントの許可 ID は、DYNAMICRULES バインド・オプションの影響を受けることがあります。

ステートメントの実行時に許可検査が行われるステートメント (DDL、GRANT、および REVOKE ステートメント) の場合、このステートメントを使用するために必要な許可は特にありません。ただし、準備済みステートメントの実行時にその許可が検査されます。

セキュリティー・ポリシーで保護された表が関係するステートメントの場合、そのセキュリティー・ポリシーに関連した規則は、常にステートメントの実行時に評価されます。

このステートメントの許可 ID に EXPLAIN、SQLADM、または DBADM 権限が保持されている場合には、ユーザーは任意のステートメントを準備できますが、ステートメントの実行が可能かどうかは、ステートメントの実行時に再検査されます。

構文

説明

statement-name

準備済みステートメントの名前を指定します。 名前として既存の準備済みのステートメントを指定した場合、 前もって準備されたそのステートメントは破棄されます。 名前として、オープン・カーソルの SELECT ステートメントである 準備済みステートメントを指定することはできません。

OUTPUT INTO

OUTPUT INTO を使用すると、PREPARE ステートメントを正常に実行した場合に、 準備済みステートメント中の出力パラメーター・マーカーについての情報が、 result-descriptor-name で指定する SQLDA に入れられます。

結果記述子名 (result-descriptor-name)

SQLDA の名前を指定します。 (この節の代わりに、DESCRIBE ステートメントを使用できます。)

INPUT INTO

INPUT INTO を使用すると、PREPARE ステートメントを正常に実行した場合に、 準備済みステートメント中の入力パラメーター・マーカーについての情報が、 input-descriptor-name で指定する SQLDA に入れられます。 入力パラメーター・マーカーは、使用法に関係なく常に NULL 可能と見なされます。

入力記述子名 (input-descriptor-name)

SQLDA の名前を指定します。 (この節の代わりに、DESCRIBE ステートメントを使用できます。)

FROM

この後に、ステートメント・ストリングを指定します。 ステートメント・ストリングは、指定するホスト変数の値です。

ホスト変数 (host-variable)

文字ストリング変数の宣言規則に従って そのプログラムで記述されているホスト変数を指定します。 これは、最大のステートメント・サイズの 2 097 152 バイトより小さい固定長または可変長の文字ストリング変数でなければなりません。 CLOB(2097152) には最大サイズのステートメントを含めることができますが、VARCHAR には含めることができないので注意してください。

expression

ステートメント・ストリングを指定する式。 この式では、最大のステートメント・サイズの 2 097 152 バイトより小さい固定長または可変長の文字ストリング・タイプを戻さなければなりません。

ルール

• ステートメント・ストリングの規則: ステートメント・ストリングは、動的に準備可能な実行可能ステートメントでなければなりません。 以下のいずれかの SQL ステートメントでなければなりません。
  • ALTER
  • CALL
  • COMMENT
  • COMMIT
  • コンパウンド SQL (コンパイル済み)
  • コンパウンド SQL (インライン化)
  • CREATE
  • DECLARE GLOBAL TEMPORARY TABLE
  • DELETE
  • DROP
  • EXPLAIN
  • FLUSH EVENT MONITOR
  • FLUSH PACKAGE CACHE
  • GRANT
  • INSERT
  • LOCK TABLE
  • MERGE
  • REFRESH TABLE
  • RELEASE SAVEPOINT
  • RENAME
  • REVOKE
  • ROLLBACK
  • SAVEPOINT
  • select-statement
  • SET COMPILATION ENVIRONMENT
  • SET CURRENT DECFLOAT ROUNDING MODE
  • SET CURRENT DEFAULT TRANSFORM GROUP
  • SET CURRENT DEGREE
  • SET CURRENT EXPLAIN MODE
  • SET CURRENT EXPLAIN SNAPSHOT
  • SET CURRENT FEDERATED ASYNCHRONY
  • SET CURRENT IMPLICIT XMLPARSE OPTION
  • SET CURRENT ISOLATION
  • SET CURRENT LOCALE LC_MESSAGES
  • SET CURRENT LOCALE LC_TIME
  • SET CURRENT LOCK TIMEOUT
  • SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION
  • SET CURRENT MDC ROLLOUT MODE
  • SET CURRENT OPTIMIZATION PROFILE
  • SET CURRENT QUERY OPTIMIZATION
  • SET CURRENT REFRESH AGE
  • SET CURRENT TEMPORAL BUSINESS_TIME
  • SET CURRENT TEMPORAL SYSTEM_TIME
  • SET ENCRYPTION PASSWORD
  • SET EVENT MONITOR STATE (DYNAMICRULES の実行動作がパッケージに効力を持つ場合のみ)
  • SET INTEGRITY
  • SET PASSTHRU
  • SET PATH
  • SET ROLE (DYNAMICRULES 実行動作がパッケージに対して有効な場合のみ)
  • SET SCHEMA
  • SET SERVER OPTION
  • SET SESSION AUTHORIZATION
  • SET SQL_CCFLAGS
  • SET USAGE LIST STATE (DYNAMICRULES の実行動作がパッケージに効力を持つ場合のみ)
  • SET 変数
  • TRANSFER OWNERSHIP (DYNAMICRULES 実行動作がパッケージに対して有効な場合のみ)
  • TRUNCATE (DYNAMICRULES 実行動作がパッケージに対して有効な場合のみ)
  • UPDATE

注

• パラメーター・マーカー: ステートメント・ストリングにホスト変数への参照を組み込むことはできませんが、 パラメーター・マーカー を組み込むことはできます。 準備済みステートメントの実行時に、パラメーター・マーカーはホスト変数の値に置き換えることができます。 CALL ステートメントの場合、プロシージャーに対する OUT 引数や INOUT 引数に、パラメーター・マーカーを使用することもできます。 CALL の実行後に、引数の戻り値は、パラメーター・マーカーに対応するホスト変数に割り当てられます。

  パラメーター・マーカーは疑問符 (?) で表されます。または、後に名前 (:name) が続くコロン でも表されます。これらはステートメント・ストリングが静的 SQL ステートメントであれば、ホスト変数を使用できる場所に使用できます。 パラメーター・マーカーがどのように値で置き換えられるかについては、『OPEN』と『EXECUTE』を参照してください。

  パラメーター・マーカーに名前を付ける場合は、名前には文字、数字、記号の @、#、$、および _ を含めることができます。この名前は大文字に変換されません。

  名前付きパラメーター・マーカーにはホスト変数と同じ構文がありますが、これら 2 つは交換可能ではありません。 1 つのホスト変数には 1 つの値が保持され、静的 SQL ステートメント内で直接使用されます。 1 つの名前付きパラメーター・マーカーは、動的 SQL ステートメント内の 1 つの値のためのプレースホルダーで、この値はステートメントの実行時に提供されます。

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

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

  ターゲットのデータ・タイプと一緒に指定するパラメーター・マーカー。 一般的な形式は、次のとおりです。

     CAST(? AS data-type)

  この表記は関数呼び出しではなく、実行時のパラメーター・タイプが指定のデータ・タイプであること、または指定のデータ・タイプに変換できるデータ・タイプであることを「保証」するものです。 例えば、以下の例で、

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

  TRANSLATE 関数の引数の値は、実行時に与えられます。 その値のデータ・タイプは、VARCHAR(12)、または VARCHAR(12) に変換可能なタイプになるはずです。

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

  ターゲットのデータ・タイプを指定しないで指定するパラメーター・マーカー。 これは、1 つの疑問符の形式です。 型なしパラメーター・マーカーのデータ・タイプは、そのコンテキストによって決まります。 例えば、上記の UPDATE ステートメントの述部にある型なしパラメーター・マーカーは、EMPNO 列のデータ・タイプと同じになります。

  型付きパラメーター・マーカーは、動的 SQL ステートメントで、 ホスト変数がサポートされている場所であれば、どこにでも使用でき、 そのデータ・タイプは CAST 関数で行った保証に基づきます。

  型なしパラメーター・マーカーは、パラメーター・マーカーのデータ・タイプが SQL ステートメント内のコンテキストに基づいて派生される限り、 動的 SQL ステートメントで使用できます (SQLSTATE 42610)。

  以下の例では、最初のコンテキストで c1 がストリング・データ・タイプに解決されますが、2 番目のコンテキストで c1 は数値データ・タイプに解決されるため、エラーになります。

  SELECT 'Hello' || c1, 5 + c1 FROM (VALUES(?)) AS T(c1)

  しかし、次のステートメントは、派生列に関連付けられたパラメーター・マーカーの c1 が両方のコンテキストで数値データ・タイプに解決されるため、正常に実行されます。

  SELECT 7 + c1, 5 + c1 FROM (VALUES(?)) AS T(c1)

  型なしパラメーター・マーカーの入力規則については、『Determining data types of untyped expressions (型なし式のデータ・タイプの決定)』を参照してください。
• PREPARE ステートメントが実行される時点で、 ステートメント・ストリングの構文解析が行われ、エラーの有無が検査されます。 ステートメント・ストリングが無効な場合には、エラー条件が SQLCA に報告されます。 エラーが訂正されない限り、 そのステートメントを参照するそれ以降の EXECUTE または OPEN ステートメントも 同じエラーになります (システムにより行われる暗黙の準備によって)。
• 準備済みステートメントは、以下の種類のステートメントで、示された制限付きで参照できます。

  入力 ...

  準備済みステートメント

  DESCRIBE

  任意のステートメント

  DECLARE CURSOR

  SELECT でなければならない

  EXECUTE

  SELECT であってはならない

• 準備済みステートメントは、何回でも実行できます。 実際に、準備済みステートメントが 1 回しか実行されず、 しかもパラメーター・マーカーが含まれていない場合には、 PREPARE と EXECUTE ステートメントを使用するよりも、 EXECUTE IMMEDIATE ステートメントを使用する方が効率が良くなります。
• ある作業単位によって作成されたすべての準備済みステートメントは、以下の例外を除き、アプリケーションが終了するまで準備済み状態のままになります。
  • KEEPDYNAMC NO を指定してバインドされたパッケージ内で準備され、WITH HOLD オプションを指定して宣言されたオープン・カーソルによって使用されていないステートメントは、作業単位が終了すると準備済み状態ではなくなります。
  • KEEPDYNAMIC NO を指定してバインドされ、WITH HOLD オプションを指定して宣言されたオープン・カーソルによって使用されている動的ステートメントは、カーソルがクローズされる次の作業単位境界まで準備済み状態になります。

例

EXEC SQL  PREPARE STMT_NAME FROM :HOLDER
END-EXEC.
EXEC SQL  EXECUTE STMT_NAME
END-EXEC.

EXEC SQL  PREPARE STMT_NAME FROM :holder;
EXEC SQL  EXECUTE STMT_NAME USING DESCRIPTOR :insert_da;

INSERT INTO DEPT VALUES(?, ?, ?, ?)

DEPT 表の列は、以下のように定義されています。

DEPT_NO   CHAR(3) NOT NULL, -- department number
DEPTNAME  VARCHAR(29), -- department name
MGRNO     CHAR(6), -- manager number
ADMRDEPT  CHAR(3)  -- admin department number