VAR (Oracle埋込みSQLディレクティブ)

用途

ホスト変数の同値化を行うか、特定の外部データ型を個々のホスト変数に割り当て、デフォルトのデータ型割当てを上書きします。また、オプションのCONVBUFSZ句を使用して、キャラクタ・セットを変換するためのバッファ・サイズを指定します。

前提条件

ホスト変数がPro*C/C++プログラムで宣言済である必要があります。

構文

図GUID-CD623546-35B3-4DB5-AD2E-9ADCB691D8B9-print.epsの説明

キーワードおよびパラメータ

キーワードおよびパラメータ	説明
host_variable	前に宣言された入力または出力ホスト変数(あるいはホスト表)。 VARCHARおよびVARRAW外部データ型が2バイト長のフィールドで、nバイトのデータ・フィールドが続く場合、nの値の範囲は1から65533になります。そのため、type_nameがVARCHARまたはVARRAWの場合、host_variableには少なくとも3バイトの長さが必要です。 LONG VARCHARおよびLONG VARRAW外部データ型が4バイト長のフィールドで、nバイトのデータ・フィールドが続く場合、nの値の範囲は1から2147483643になります。そのため、type_nameがLONG VARCHARまたはLONG VARRAWの場合、host_variableには少なくとも5バイトの長さが必要です。
dtyp	Pro*C/C++によって認識される内部データ型ではない外部データ型。データ型には、長さ、精度または位取りを含めることができます。この外部データ型がhost_variableに割り当てられます。外部データ型のリストは、外部データ型を参照してください。
length	データ型の長さ。有効な長さをバイト数で指定する定数式または整定数です。lengthの値は、外部データ型を指定するのに十分な長さにする必要があります。 type_nameがROWIDまたはDATEの場合、lengthは事前に定義されているために指定できません。他の外部データ型の場合、lengthはオプションです。デフォルトでhost_variableの長さに設定されます。 lengthを指定するときに、type_nameがVARCHAR、VARRAW、LONG VARCHARまたはLONG VARRAWの場合は、データ・フィールドの最大長を指定してください。この長さフィールドは、Pro*C/C++が指定します。type_nameがLONG VARCHARまたはLONG VARRAWで、データ・フィールドが65534バイト以上の場合は、lengthフィールドに「-1」を入れてください。
precisionおよびscale	それぞれ有効桁数と四捨五入が実行される点を表す定数式または定数。たとえば位取りが2のときは、1/100の倍数の近似値に値が四捨五入される(3.456は3.46になる)ことを意味します。また位取りが-3のときは、1000の倍数の近似値に値が四捨五入される(3456が3000になる)ことを意味します。 1から99までのprecisionおよび-84から99までのscaleを指定できます。ただし、データベース列の精度および位取りの最大値は、それぞれ38と127です。したがって、precisionが38を超えていると、host_variableの値はデータベース列に挿入できません。一方、列値の位取りが99を超えていると、host_variableに入れる値の選択もフェッチもできません。
size	指定したhost_variableから他のキャラクタ・セットへの変換に使用されるバッファのバイト単位のサイズ。定数または定数式です。ランタイム・ライブラリ内のバッファのバイト単位のサイズ。これを使用して、host_variableのキャラクタ・セットを変換します。

使用上の注意

length、precision、scaleおよびsizeは定数式になる場合があります。

ホスト変数の同値化は、一種のデータ型の同値化です。データ型の同値化は次の目的に有効です。

文字ホスト変数を自動的にヌル文字で終了します。
プログラム・データをバイナリ・データとしてデータベースに格納します。
デフォルトのデータ型のかわりに使用します。

size、length、precision、scaleには、プリコンパイラの実行時に値が認識される複雑なC言語の定数式を任意に使用できることに注意してください。

次に例を示します。

#define LENGTH 10
...
char character set is nchar_cs ename[LENGTH+1];
exec sql var ename is string(LENGTH+1) convbufsz is (LENGTH*2);

また、この文ではマクロも使用できるため注意してください。

CONVBUFSZ句を指定しなければ、Oracleランタイム・ライブラリが、ホスト変数のキャラクタ・サイズ(NLS_LANGで判別)とデータベース・キャラクタ・セットのキャラクタ・サイズとの割合に基づいてバッファ・サイズを自動的に決定します。これによって、LONGサイズのバッファが作成されることがあります。データベース表では、LONG列は1列しか格納できません。複数のLONG値が指定されると、エラーとなります。

このようなエラーを回避するには、LONGのサイズよりも短い長さを使用します。キャラクタ・セットの変換によって値がCONVBUFSZで指定した長さを超える場合は、実行時にエラーが戻されます。Pro*C/C++プリコンパイラは、ユーザー定義型の同値化に使用できるプリコンパイラのTYPEディレクティブもサポートしています。ホスト変数の同値化も参照してください。

例

この例では、ホスト変数DEPT_NAMEがデータ型STRINGに同値化され、ホスト変数BUFFERがデータ型RAW(200)に同値化されます。

EXEC SQL BEGIN DECLARE SECTION; 
    ... 
    char dept_name[15];               -- default datatype is CHAR 
    EXEC SQL VAR dept_name IS STRING; -- reset to STRING 
    ... 
    char buffer[200];                 -- default datatype is CHAR 
    EXEC SQL VAR buffer IS RAW(200); -- refer to RAW 
    ...
EXEC SQL END DECLARE SECTION;