ホスト変数

ホスト変数は、ホスト言語のステートメントを使用して直接に定義するか、または SQL 拡張機能によって間接的に定義します。 SQL ステートメント内の host-variable は、ホスト変数を宣言する際の規則に従ってプログラム内で記述されたホスト変数を指定する必要があります。ホスト変数は、動的 SQL ステートメント内では参照できず、代わりにパラメーター・マーカーを使用する必要があります。

ホスト変数 は、SQL ステートメントで参照する以下のいずれかの項目です。

PL/I 変数、C変数、 Fortran 変数、REXX変数、Java™変数、 COBOL データ項目、またはアセンブラ言語記憶領域などのホスト言語の変数
SQL 拡張機能を使って宣言された変数から SQL のプリコンパイラーによって生成されたホスト言語構成

ホスト変数は、ホスト言語のステートメントによって直接定義されるか、 Db2 のオブジェクトリレーショナル拡張で説明されているように、SQL拡張によって間接的に定義されます。ホスト変数は、動的 SQL ステートメント内では参照できず、代わりにパラメーター・マーカーを使用する必要があります。パラメータマーカーの詳細については、「ダイナミックSQLの変数」を参照してください。

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

PL/I、C、および COBOL では、Fortran やアセンブラー言語には適用されない方法でホスト変数の参照ができます。これについては、 PL/I、C、および COBOL のホスト構造」で説明されています。まずはじめに、すべてのホスト言語に適用される内容について述べることにします。

構文図などで使っているホスト変数という用語は、ホスト変数に対する参照を示します。 SETホスト変数文およびFETCH、SELECT INTO、またはVALUES INTO文のINTO節において、ホスト変数は、 Db2 によって値が割り当てられる出力変数です。 CALL ステートメント内では、ホスト変数はプロシージャーの実行後に割り当てられる出力引数、プロシージャーの入力値を指定する入力引数、または入出力両用の引数です。その他のすべてのコンテキストでは、ホスト変数は、 Db2 に値を提供する入力変数です。

Java以外の変数参照

Java以外のすべての言語におけるホスト変数参照の一般的な形式は次のとおりです

REXXで書かれたプログラムを除き、各ホスト識別子はソースプログラムで宣言する必要があります。最初の host-identifier はメイン変数を指定し、2 番目の host-identifier は関連する標識変数を指定します。標識変数は短精度整数でなければなりません。操作に応じて、メイン変数はデータベース・マネージャーに値を提供するか、またはデータベース・マネージャーから値を提供されます。入力ホスト変数は、ランタイム・アプリケーション・コード・ページの値を提供します。出力ホスト変数には、データが出力アプリケーション変数にコピーされるときに、必要に応じてランタイム・アプリケーション・コード・ページに変換される値が提供されます。指定されるホスト変数は、同じプログラム内で入力変数と出力変数の両方として機能できます。

標識変数の目的は、以下のとおりです。

NULL 以外の値を指定する。標識変数の 0 (ゼロ) または正の値は、関連付けられた最初の host-identifier がこのホスト変数参照の値を提供することを指定します。
NULL 値を指定する。標識変数の負の値は、NULL 値を指定するものとなります。

さらに、出力では、標識変数の目的は以下のとおりです。

数値変換エラー (0 による除算やオーバーフローなど) が発生したことを示します。標識変数の値が -2 の場合は、数値の切り捨てか算術計算の警告のために、結果が NULL であることを示します。
文字の変換ができないことを示す。標識変数の値が -2 の場合は、文字ストリング変換の警告のために、結果が NULL であることを示します。
値が返されなかったことを示します。標識変数の値が -3 の場合は、カーソルの現在行が、複数行 FETCH 時に検出されたホールにあるために、結果が NULL であることを示します。
ストリングが LOB でない場合に、切り捨てられたストリングの元の長さを報告します。
時刻がホスト変数への割り当ての際に切り捨てられた場合に、その時刻の秒の部分を報告します。

2 番目の host-identifier を省略すると、ホスト変数は標識変数を持ちません。ホスト変数 V1 によって指定される値は常に V1 の値であり、NULL 値を変数に割り当てることはできません。したがって、対応する結果列に NULL 値を入れることができない場合を除き、この形式を出力に使用しないでください。この形式が出力ホスト変数に使用され、戻り値が NULL の場合、Db2は実行時にエラーを返します。

INSERT、 MERGE、または UPDATE ステートメント内の入力ホスト変数のインジケーター変数は、ターゲット列がデフォルト値に設定されることを示す特殊値に設定することも、値をターゲット列に割り当てないことを示す場合にも、ある特殊値に設定することができます。これらの特殊値は、拡張インジケーターが有効な場合にのみ使用できます。拡張標識は、EXTENDEDINDICATOR (YES) バインド・オプションが使用されるとき、またはステートメントに WITH EXTENDED INDICATORS 準備属性が指定されるときに使用可能になります。

拡張標識が使用可能な場合、INSERT、MERGE、または UPDATE ステートメントの割り当ての入力標識変数は、関連するホスト変数のターゲット列に以下のいずれかのタイプの値が割り当てられることを指定します。

NULL 以外の値: 0 (ゼロ) または正の値は、関連する host-identifier がこのホスト変数参照の値を提供することを指定します。
NULL: -1、-2、-3、-4、または -6 の値は NULL 値を指定します。
DEFAULT: -5 の値は、ターゲット列のデフォルト値を指定します。
UNASSIGNED: -7 の値は、このホスト変数が、ステートメントのターゲット列への割り当てに値が指定されていないかのように扱われることを指定します。

これらの標識値は、ホスト構造を持つ標識構造で使用することもできます。拡張標識が使用可能な場合には、前にリストされた正の値、ゼロ、および負の値以外の標識値を使用してはなりません。 DEFAULT および UNASSIGNED 拡張標識値は、それらがサポートされているコンテキスト (INSERT、MERGE、および UPDATE ステートメント) でのみ使用する必要があります。 DEFAULT および UNASSIGNED 拡張標識値は、単一ホスト・パラメーターを含む式、または列に割り当てられる単一ホスト・パラメーターの CAST に対してのみ使用できます。出力インジケーターは、拡張インジケーター値に設定されません。

拡張標識が有効になっている場合、割り当ておよび比較におけるデータ・タイプ検証の規則は、関連付けられた標識値が負の値であるホスト変数に対して緩和されます。関連付けられた標識値が NULL、DEFAULT、または ASSIGNED であるホスト変数に対しては、データ・タイプ割り当ておよび比較検証の規則は適用されません。

ホスト変数を参照する SQL ステートメントは、対象のホスト変数の宣言の範囲内にある必要があります。カーソルの SELECT ステートメントで参照されるホスト変数の場合、この規則は DECLARE CURSOR ステートメントではなく、OPEN ステートメントに適用されます。

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

ホスト変数に CCSID 節を含む DECLARE VARIABLE ステートメントが指定されている場合、ホスト変数の CCSID は DECLARE VARIABLE ステートメントの CCSID になります。
CCSID 節を指定した DECLARE VARIABLE ステートメントがホスト変数に指定されていない場合、CCSID が外部コード化スキーム用でない限り、ホスト変数を含む SQL ステートメントの実行時に、ホスト変数 CCSID はアプリケーション・リクエスターのデフォルト CCSID になります。その場合、ホスト変数は現行サーバーのデフォルト CCSID に変換されます。

ホスト変数へのすべての参照には、その前にコロンを付ける必要があります。先行するコロンがないホスト変数を SQL ステートメントが参照した場合、プリコンパイラーはコロンの欠落に関するエラーを出します。あるいは、ホスト変数を非修飾の列名として解釈して、予測しない結果を生じる可能性があります。コロンがないホスト変数を列名として解釈することは、列名を参照できるコンテキストでホスト変数を参照した場合に発生します。

Java変数参照

Javaにおけるホスト変数参照の一般的な形式は次のとおりです

各 Java ID はソース・プログラム内で宣言される必要があります。第 2 Java ID によって指定される変数は標識変数と呼ばれる変数であり、単精度である必要があります。

Javaでは、インジケータ変数は常に必要というわけではありません。その代わりに、Javaクラスのインスタンスをnull値に設定することができます。 Javaのプリミティブ型として定義された変数は、null値に設定することはできません。拡張インジケータ変数を使用する場合、またはJavaのプリミティブ型でnull値を代入する場合、またはJavaのプリミティブ型がnullを出力する可能性がある場合、インジケータ変数を使用しなければなりません。

IN、OUT、または INOUT を指定しない場合、デフォルトは変数が使用されるコンテキストによって異なります。 Java変数がINTO句で使用される場合、OUTがデフォルトです。それ以外の場合は、IN がデフォルトです。

Db2 precompiler を使用している場合は、変数や変数配列が異なるブロック、クラス、プロシージャ、関数、サブルーチンにある場合でも、ホスト変数およびホスト変数配列の名前がプログラム内で一意であることを確認してください。このホスト変数およびホスト変数配列の名前は、構造体名で修飾して固有にすることができます。