C および C++ におけるホスト変数

C および C++ プログラムでは、数値、文字、グラフィック、バイナリー、LOB、 XML、および ROWID のホスト変数を指定できます。また、結果セット、表、および LOB のロケーター、および LOB と XML のファイル参照変数を指定することもできます。

制約事項:

有効な C 宣言のうちの一部だけが、有効なホスト変数宣言として認識されます。ある変数の宣言が無効な場合に、その変数を参照する SQL ステートメントがあると、メッセージ UNDECLARED HOST VARIABLE が出される場合があります。
C 言語は、SQL に同等のものがない一部のデータ・タイプおよびストレージ・クラスをサポートします。例えば、レジスター・ストレージ・クラス、typedef、および long long です。
次のロケーター・データ・タイプは、C に同等なものがない特殊な SQL データ・タイプです。
- 結果セット・ロケーター
- 表ロケーター
- LOB ロケーター
これらを使用して列タイプを定義することはできません。
Db2Cアプリケーションプログラムで適切に形成されたLリテラルを使用することはできますが、 Db2 CコンパイラがLリテラルに課すすべての制限を検査するわけではありません。 \
SQL ステートメントでは、L リテラルを使用しないでください。 SQL ステートメントで Db2 グラフィック・ストリング定数を使って、L-literalを処理します。

推奨事項:

オーバーフローには注意してください。例えば、INTEGER 列値を取り出して短整数ホスト変数に入れたとき、その列値が 32767 より大きいとします。この場合、標識変数が指定されているかどうかに応じて、オーバーフロー警告またはエラーが出されます。
切り捨てには注意してください。宣言するホスト変数には、必要に応じて、データおよび NUL 終止符が入る可能性があることを確認してください。浮動小数点または 10 進の列の値を取り出して長整数のホスト変数に入れると、その値の小数部分はすべて除去されます。

数値ホスト変数

次の図は、数値ホスト変数の宣言の構文です。

注:

¹ ホスト変数のポインタ表記を使用する場合は、 Db2 コプロセッサを使用する必要があります。

制約事項:

C コンパイラーに 10 進数データ・タイプがない場合、SQL DECIMAL データ・タイプに厳密に同等のデータ・タイプは存在しません。この場合、次のいずれかの変数または手法を使用して、10 進数を処理できます。
- 整数または浮動小数点変数。値を変換します。整変数を使用すると、その小数部分は失われます。 10 進数が整数の最大値を超える可能性がある場合、あるいは小数部の値を保持する必要がある場合には、浮動小数点変数を使用します。浮動小数点数は、実数の近似値です。したがって、10 進数を浮動小数点変数に割り当てると、結果が元の数値と異なる場合があります。
- 文字ストリング・ホスト変数。 CHAR 関数を使用することができ、10 進数のストリング表現を得ることができます。
- 以下の例のように、値を明示的に 10 進データ・タイプに変換する DECIMAL 関数。
```
long duration=10100;  /* 1 year and 1 month */
char result_dt[11];
 
EXEC SQL SELECT START_DATE + DECIMAL(:duration,8,0)
         INTO :result_dt FROM TABLE1;
```
z/OS® 1.10 またはそれ以上（ z/OS V1R10 XL C/C++ ）は、小数浮動小数点ホストデータ型を使用するために必要です。
C 専用の「複素数浮動小数点」ホスト・データ・タイプは、ホスト変数にサポートされるタイプではありません。
FLOAT プリコンパイラー・オプションは、10 進浮動小数点ホスト変数タイプには適用されません。
10 進浮動小数点ホスト変数を使用するには、Db2 コプロセッサーを使わなければなりません。

浮動小数点データ型の場合、FLOAT SQL処理オプションを使用して、ホスト変数がIEEEバイナリ浮動小数点形式か z/Architecture® 16進浮動小数点形式かを指定します。 Db2 ホスト変数内容のフォーマットが、FLOAT SQL 処理オプションで指定したフォーマットと一致しているかどうかは確認しません。したがって、浮動小数点ホスト変数の内容が、FLOAT SQL 処理オプションで指定したフォーマットと一致していることを確認する必要があります。 Db2 すべての浮動小数点入力データを、格納前に z/Architecture の16進浮動小数点形式に変換します。

文字ホスト変数

次の形式の文字ホスト変数を指定できます。

単一文字形式
NUL 終止符文字形式
VARCHAR 構造書式
CLOB

以下の図は、CLOB 以外の各形式の構文を示しています。

次の図は、単一文字ホスト変数の宣言の構文です。

注:

¹ ホスト変数のポインタ表記を使用する場合は、 Db2 コプロセッサを使用する必要があります。

次の図は、NUL 終止符文字ホスト変数の宣言の構文です。

注:

¹ ホスト変数のポインタ表記を使用する場合は、 Db2 コプロセッサを使用する必要があります。
² この変数に割り当てられる文字列は、すべて NUL 文字で終了していなければなりません。この変数から取り出されるストリングは NUL 終止符です。
³ NUL文字で終端する文字ホスト変数は、可変長文字列（NUL文字を除く）にマッピングされます。

次の図は、VARCHAR 構造化形式を使用する可変長文字ホスト変数の宣言の構文です。

注:

¹ 構造体タグを使用して他の変数を定義することはできますが、SQLのホスト変数としてそれらを使用することはできません。
² あなたは使用できません。 var-1 および var-2 SQLステートメントでホスト変数として使用することはできません。
³ ホスト変数のポインタ表記を使用する場合は、 Db2 コプロセッサを使用する必要があります。

例

次のサンプル・コードで、VARCHAR 構造化形式の有効な宣言と無効な宣言を示します。

EXEC SQL BEGIN DECLARE SECTION;

    /* valid declaration of host variable VARCHAR vstring */
    struct VARCHAR {
      short len;
      char s[10];
      } vstring;

    /* invalid declaration of host variable VARCHAR wstring */
    struct VARCHAR wstring;

NUL 終止符ストリング・ホスト変数の場合は、SQL 処理オプション PADNTSTR および NOPADNTSTR を使用して、変数をブランクで埋めるかどうかを指定します。指定するオプションによって、NUL 終止符を配置する場所が決まります。

長さ n のストリングを NUL 終止符ストリング・ホスト変数に割り当てると、変数には次の表に示す値のいずれかが入ります。

表 1. NUL文字で終端する文字列のホスト変数に、 `長さnの`文字列が代入された値
NUL 終止符ストリング・ホスト変数の長さ	変数の値
`n` より小か等しい	長さ `n`-1 までのソース・ストリング、およびストリングの末尾に NUL。 ¹ Db2 SQLWARN [1]をWに設定し、ソース文字列の元の長さに指定したインジケーター変数を設定します。
`n`+1 に等しい	ソース・ストリング、およびストリングの末尾に NUL。 ¹
`n`+1 より大きく、ソースは固定長ストリング	PADNTSTR が有効である場合ソース・ストリング、値の埋め込みブランク、およびストリングの末尾に NUL。 NOPADNTSTR が有効である場合ソース・ストリング、およびストリングの末尾に NUL。
`n`+1 より大きく、ソースは可変長ストリング	ソース・ストリング、およびストリングの末尾に NUL。 ¹
注: これらの場合、NOPADNTSTR または PADNTSTR が有効かどうかは関係ありません。

制限事項： Db2 プリコンパイラを使用している場合、NUL文字で終了する形式のホスト変数をPREPAREまたはDESCRIBE文で使用することはできません。ただし、 Db2 コプロセッサを使用している場合は、NUL文字で終了する形式のホスト変数をPREPARE、DESCRIBE、およびEXECUTE IMMEDIATE文で使用することができます。

グラフィック・ホスト変数

次の形式のグラフィック・ホスト変数を指定できます。

シングルグラフィックフォーム
NUL 終止符グラフィック形式
VARGRAPHIC 構造化形式
DBCLOB

推奨：グラフィックおよび vargraphic ホスト変数を定義する際に C データ型 wchar_t を使用するのではなく、以下のいずれかのテクニックを使用してください

次の typedef ステートメントを使用して、sqldbchar データ・タイプを定義する。
```
typedef unsigned short sqldbchar;
```
次のファイルまたはライブラリーのいずれかの typedef ステートメントで定義される sqldbchar データ・タイプを使用する。
- SQL ライブラリー、sql.h
- Db2 CLI ライブラリー、 sqlcli.h
- データセットDSN1210.SDSNC.H のSQLUDFファイル
C データ・タイプ unsigned short を使用する。

sqldbchar または unsigned short を使うと、DBCSとUnicode UTF-16 データを、 Db2に保管されているのと同じフォーマットで操作できます。 sqldbchar を使用すると、アプリケーションを別のプラットフォームに移植するのも容易になります。

以下の図は、DBCLOB 以外の各形式の構文を示しています。

次の図は、単一グラフィック・ホスト変数の宣言の構文です。

注:

¹ 変数名に配列記法を使用することはできません。
² 単一グラフィック形式は、固定長グラフィック文字列の長さを1と宣言します。

次の図は、NUL 終止符グラフィック・ホスト変数の宣言の構文です。

注:

¹ ホスト変数のポインタ表記を使用する場合は、 Db2 コプロセッサを使用する必要があります。
² の長さは、1より大きく16352より小さい十進整数定数でなければなりません。
³ この変数に割り当てられる文字列は、すべてNUL文字で終了していなければなりません。この変数から取り出されるストリングは NUL 終止符です。
⁴ NUL文字で終了するグラフィック形式では、変数にシングルバイト文字を使用することはできません。

次の図は、VARGRAPHIC 構造化形式を使用するグラフィック・ホスト変数の宣言の構文です。

注:

¹ 構造体タグを使用して他の変数を定義することはできますが、SQLのホスト変数としてそれらを使用することはできません。
²var-1 長さ以下でなければなりません。
³ あなたは使用できません。 var-1 または var-2 SQLステートメントでホスト変数として使用することはできません。
⁴ 長さは、1 より大きく16352 より小さい十進整数定数でなければなりません。
⁵ ホスト変数のポインタ表記を使用する場合は、 Db2 コプロセッサを使用する必要があります。

例

次の例で、VARGRAPHIC 構造化形式を使用するグラフィック・ホスト変数の有効宣言と無効宣言を示します。

EXEC SQL BEGIN DECLARE SECTION;
 
   /* valid declaration of host variable structured vgraph */
   struct VARGRAPH {
      short len;
      sqldbchar d[10];
      } vgraph;
 
   /* invalid declaration of host variable structured wgraph */
   struct VARGRAPH wgraph;

バイナリー・ホスト変数

次の形式のバイナリー・ホスト変数を指定できます。

固定長ストリング
可変長ストリング
BLOB

以下の図は、BLOB 以外の各形式の構文を示しています。

次の図は、バイナリー・ホスト変数の宣言の構文です。

注:

¹ 長さは1～255の範囲の値でなければなりません。

次の図は、VARBINARY ホスト変数の宣言の構文です。

注:

¹ VARBINARY ホスト変数の場合は、長さは 1～32704 の範囲でなければなりません。

C 言語には、SQL バイナリー・データ・タイプ BINARY と VARBINARY に対応する変数がありません。これらのデータ・タイプに使用できるホスト変数を作成するには、SQL TYPE IS 文節を使用します。 SQL プリコンパイラーが、この宣言を出力ソース・メンバー内で C 言語構造に置き換えます。

SQL ステートメント内で BINARY または VARBINARY のホスト変数を参照する際には、SQL TYPE 宣言で指定した変数を使用する必要があります。ホスト言語ステートメントでホスト変数を参照する場合は、Db2 が生成する変数を使わなければなりません。

バイナリーの変数宣言の例

下表に、バイナリー・ホスト変数を宣言するときにDb2 が生成する変数の例を示します。

表 2. C の BINARY および VARBINARY 変数宣言の例
C プログラムに組み込む変数宣言	Db2出力ソースメンバーで生成される対応変数
`SQL TYPE IS BINARY(10) bin_var;`	`char bin_var[10]`
`SQL TYPE IS VARBINARY(10) vbin_var;`	`struct { short length; char data[10]; } vbin_var;`

推奨： CおよびC++でバイナリホスト変数を使用する際には注意が必要です。BINARYおよびVARBINARYのSQL TYPE宣言では、Cが期待するNUL終端文字列は考慮されていません。これは、バイナリ文字列がNUL終端文字列ではないためです。さらに、バイナリー・ホスト変数には、ストリング内のいずれかの位置にゼロが含まれている可能性があります。

結果セット・ロケーター

次の図は、結果セット・ロケーターの宣言の構文です。

表ロケーター

次の図は、表ロケーターの宣言の構文です。

LOB 変数、ロケーター、およびファイル参照変数

次の図は、BLOB、CLOB、および DBCLOB のホスト変数、ロケーター、およびファイル参照変数の宣言の構文です。

注:

¹ 初期値を式の列として指定します。例えば、={expression, expression}を指定します。 BLOB_FILE、CLOB_FILE、および DBCLOB_FILE の場合は、={name_length, data_length, file_option_map, file_name} を指定します。

XML データ・ホストおよびファイル参照変数

次の図は、XML データ・タイプの BLOB、CLOB、および DBCLOB のホスト変数、およびファイル参照変数の宣言の構文です。

注:

¹ 初期値を式の列として指定します。例えば、={expression, expression}を指定します。 BLOB_FILE、CLOB_FILE、および DBCLOB_FILE の場合は、={name_length, data_length, file_option_map, file_name} を指定します。

ROWID ホスト変数

次の図は、ROWID ホスト変数の宣言の構文です。

定数

C および C++ プログラムの定数の構文は、SQL ステートメントの定数の構文と次の点で異なります。

C/C++ は、さまざまな形式の数値リテラルを使用します (可能な接尾部: ll、LL、u、U、f、F、l、L、df、DF、dd、DD、dl、DL、d、D)。例えば、C/C++ では次のようになります。
- 4850976 は 10 進数リテラル
- 0x4bD は 16 進整数リテラル
- 03245 は 8 進整数リテラル
- 3.2E+4 は double 浮動小数点リテラル
- 3.2E+4f は float 浮動小数点リテラル
- 3.2E+4l は long double 浮動小数点リテラル
- 0x4bDP+4 は double 16 進浮動小数点リテラル
- 22.2df は _Decimal32 10 進浮動小数点リテラル
- 0.00D 固定小数点リテラルです（ LANGLVL(EXTENDED) が指定されている場合のみ）。 z/OS
C/C++ リテラル形式は、SQL ステートメントの外側でのみ使用します。 SQL ステートメント内では、数値定数を使用します。
C では、文字定数およびストリング定数でエスケープ・シーケンスを使用することができます。エスケープ・シーケンスは、SQL ステートメントではサポートされていません。
アポストロフィと引用符の意味は、C と SQL ではそれぞれ異なります。 C では、ストリング定数を区切るのに二重引用符を使用し、文字定数を区切るのにアポストロフィを使用できます。
例 : Cで引用符の使用
```
printf(  "%d lines read. \n", num_lines);
```
例 : C でアポストロフィの使用
```
#define NUL '\0'
```
SQL では、ID を区切るのに二重引用符を使用し、ストリング定数を区切るのにアポストロフィを使用できます。
例: SQLの引用符
```
SELECT "COL#1" FROM TBL1;
```
例: SQLのアポストロフィ
```
SELECT COL1 FROM TBL1 WHERE COL2 = 'BELL';
```
SQL では、文字データと整数データは区別されます。 C では、文字データは整数データのサブタイプになります。