ホスト変数に対する参照

動的 SQL ステートメントでは、ホスト変数を参照できません。代わりに、パラメーター・マーカーを使用する必要があります。パラメーター・マーカーについての詳細は、動的 SQL での変数を参照してください。

SQL ステートメント中のホスト変数 は、ホスト変数の宣言の規則に従ってプログラム内で記述されたホスト変数でなければなりません。

Java、REXX、および RPG 以外のすべてのホスト言語では、SQL ステートメントで使用されるホスト変数はすべて、SQL 宣言セクションで宣言されていなければなりません。 REXX では、変数は宣言されている必要はありません。Java と RPG には、宣言セクションはありませんが、 ホスト変数は、そのプログラム全体にわたって宣言されます。 SQL 宣言セクションで宣言されている変数と同じ名前を持つ変数を、SQL 宣言セクションの外側で宣言してはなりません。 SQL 宣言セクションは、BEGIN DECLARE SECTION で開始し、END DECLARE SECTION で終了します。

ホスト変数の使用についての詳細は、 「組み込み SQL プログラミング」トピックを参照してください。

FETCH、SELECT INTO、SET 変数の INTO 文節、GET DESCRIPTOR ステートメント、または VALUE INTO ステートメントにおける変数は、結果列の値を割り当てるホスト変数を識別します。GET DIAGNOSTICS ステートメント内の変数は、診断値を割り当てるホスト変数を識別します。 CALL または EXECUTE ステートメント内のホスト変数は、プロシージャーの実行後に値を割り当てられる出力引数、プロシージャーに入力値を提供する入力引数、または入力引数と出力引数の両方にすることができます。その他のすべてのコンテキストでの変数は、 アプリケーション・プログラムからデータベース・マネージャーに渡される値を指定します。

非 Java 変数参照:

Java 以外のすべての言語では、変数 参照の一般的な形式は次のとおりです。

それぞれのホスト ID は、ソース・プログラム内で宣言しておく必要があります。 2 番目のホスト ID によって指定される変数は標識変数 と呼ばれ、 データ・タイプは短整数でなければなりません。標識変数には正常標識変数 と拡張標識変数 の 2 つの形式があります。

正常標識変数は、次のような用途に使用します。

• NULL 以外の値を指定します。標識変数を 0 (ゼロ) または正の値にすると、関連した最初のホスト ID がこのホスト変数参照の値を提供することを指定します。
• NULL 値を指示します。標識変数の負の値は、NULL 値を示します。
• 出力で、以下の数値変換エラーのいずれかを示します。
  • 数値変換エラー (アンダーフローまたはオーバーフロー)。
  • 算術式エラー (0 による除算)。
  • 数値が無効。
  標識変数の値 -2 は、これらのいずれかの警告があるので、NULL の結果を示します。
• 出力で、以下のストリング・エラーのいずれかを示します。
  • 文字を変換できなかった。
  • 混合 (MIXED) データが正しく形成されていない。
  標識変数の値 -2 は、これらのいずれかの警告があるので、NULL の結果を示します。
• 出力で、以下の日時エラーのいずれかを示します。
  • 日付またはタイム・スタンプの変換エラー (指定されている日付形式の有効な範囲内にない日付またはタイム・スタンプ)。
  • 日付/時刻の値のストリング表現が正しくない。
  標識変数の値 -2 は、これらのいずれかの警告があるので、NULL の結果を示します。
• 出力で、以下の各種エラーのいずれかを示します。
  • スカラー関数 SUBSTR の引数が範囲外。
  • 暗号化解除関数の引数に無効なデータ・タイプが含まれている。
  標識変数の値 -2 は、これらのいずれかの警告があるので、NULL の結果を示します。
• 出力で、ホスト変数に割り当てたストリングが切り捨てられた場合に、そのストリングの元の長さを記録します。 標識変数が用意されていない場合にストリングが切り捨てられても、エラー条件とはなりません。
• 出力で、ホスト変数に割り当てた時刻が切り捨てられた場合に、その時刻の秒の部分を記録します。 標識変数が用意されていない場合に時刻が切り捨てられても、エラー条件とはなりません。

例えば、:V1:V2 というホスト変数参照を使用して挿入値または更新値を指定した場合に、V2 の値が負ならば、指定した値が NULL 値であることを示します。V2 が負でない場合、指定した値が V1 の値になります。

同様に、:V1:V2 を CALL、FETCH、SELECT INTO、または VALUES INTO ステートメントで指定した場合に、 戻された値が NULL であれば、V1 は未定義であり、V2 に負の値がセットされます。 セットされる負の値は、次のとおりです。

• -1、これは選択された値が NULL 値であったことを示します。
• -2、これは、外側の副選択の選択リストのデータ・マッピング・エラーにより NULL 値が戻されたことを示します。¹

参照によって戻された値が NULL 値でなければ、その値が V1 に割り当てられ、V2 にはゼロがセットされます (ただし、V1 への割り当ての際に切り捨てが必要だった場合は、V2 にそのストリングの元の長さがセットされます)。また、割り当ての際に、時刻の秒の部分を切り捨てる必要があった場合は、切り捨てられた秒数が V2 にセットされます。

2 番目のホスト ID が省略された場合は、 そのホスト変数 は標識変数をもちません。 このような場合、ホスト変数 :V1 によって指定された値は常に V1 の値になり、NULL 値をその変数に割り当てることはできません。 したがって、対応する結果列に NULL 値を入れることができない場合以外は、この形式を使用してはなりません。 この形式を使用し、しかも列に NULL 値が含まれている場合、データベース・マネージャーは実行時にエラーを戻します (SQLSTATE 23502)。

拡張標識変数は、入力ホスト変数に限定されます。 その目的は次のとおりです。

• NULL 以外の値を指定します。0 (ゼロ) または正の値にすると、関連したホスト ID がこのホスト変数参照の値を提供することを指定します。
• NULL 値を指示します。値 -1、-2、-3、-4、および -6 は、NULL 値を指定します。
• DEFAULT 値を指定します。値 -5 は、このホスト変数のターゲット列がそのデフォルト値に設定されることを指定します。
• UNASSIGNED 値を指定します。値 -7 は、このホスト変数のターゲット列が、ステートメントで指定されなかったかのように扱われることを指定します。

拡張標識変数は、要求される場合のみ使用可能になります。 それ以外の場合、すべての標識変数は正常標識変数です。正常標識変数と比較すると、拡張標識変数には、NULL 値と NULL 以外の値の使用に関する追加の制限がありません。拡張標識は、ホスト構造のある標識構造で使用できます。拡張標識変数値 DEFAULT および UNASSIGNED が使用可能になる場合に関する制限は、それらの値がどのようにホスト・アプリケーションで表示されていても、一様に適用されます。 DEFAULT および UNASSIGNED 拡張標識変数は、ある 1 つの列に割り当てられる単一のホスト・パラメーターを含む式として、 または、そういったホスト・パラメーター のキャストとしてのみ使用できます。 出力標識変数値は、拡張標識変数ではありません。

拡張標識変数が有効になっている場合は、正の値、ゼロ、上記の 6 つの負の値以外の標識変数値を使用しないでください。DEFAULT 値および UNASSIGNED 値 は、それらがサポートされているコンテキスト (INSERT、 MERGE、および UPDATE ステートメント) でのみ指定されなければなりません。これらは CALL ステートメント 内ではサポートされません。

C、C++、ILE RPG、および PL/I でホスト変数を参照する SQL ステート メントは、そのホスト変数の宣言の有効範囲になければなりません。 カーソルに対する SELECT ステートメントでホスト変数を参照する場合、そのホスト変数の宣言の有効範囲内になければならないのは、DECLARE CURSOR ステートメントではなく、OPEN ステートメントです。

ストリング・ホスト変数の CCSID は、次のいずれかです。

• DECLARE VARIABLE ステートメントで指定された CCSID、または
• 該当のホスト変数に対して CCSID 文節を伴う DECLARE VARIABLE の指定がない場合には、そのホスト変数を含む SQL ステートメントが実行される時点のアプリケーション・リクエスターのデフォルト CCSID (ただし、ASCII などの、Unicode 以外の外部コード化体系に対する CCSID でない場合のみ)。外部コード体系に対する CCSID である場合には、ホスト変数は、現行サーバーのデフォルトの CCSID に変換されます。

Java 変数参照:

Java の場合、ホスト変数参照の一般形式は次のとおりです。

>>-:--+-------+--+-Java-identifier-------+---------------------><
      +-IN----+  '-(--Java-expression--)-'   
      +-OUT---+                              
      '-INOUT-'                              

Java の場合、標識変数は使用されません。その代わりに、Java クラスのインスタンスは NULL 値に設定できます。 Java プリミティブ・タイプとして定義されている変数は、NULL 値に設定できません。

IN、OUT、または INOUT を指定しない場合、 変数を使用するコンテキストによってデフォルトが変わります。 Java 変数が INTO 文節で使用される場合、OUT がデフォルトです。 それ以外の場合は、IN がデフォルトです。 Java 変数について詳しくは、「IBM® Developer Kit for Java」を参照してください。

例

PROJECT 表を使用して、プロジェクト (PROJNO) ‘IF1000’ について、ホスト変数 PNAME (VARCHAR(26)) をプロジェクト名 (PROJNAME) に、ホスト変数 STAFF (DECIMAL(5,2)) を平均人員レベル (PRSTAFF) に、そしてホスト変数 MAJPROJ (CHAR(6)) を主プロジェクト (MAJPROJ) に設定します。PRSTAFF と MAJPROJ の列には NULL 値が入っている可能性があるので、標識変数 の STAFF_IND (SMALLINT) と MAJPROJ_IND (SMALLINT) を指定しています。