SQLDA変数の使用について

この項では、SQLDA内の各変数の用途および使用方法を説明します。

N変数

Nは、DESCRIBE可能な選択リスト項目またはプレースホルダの最大数を指定します。つまり、Nによって記述子配列に含まれる要素の数が決まります。

オプションのDESCRIBEコマンドを発行する前に、ライブラリ関数SQLSQLDAAlloc()を使用してNを記述子配列の次元に設定する必要があります。また、DESCRIBEの実行後に、DESCRIBEされた変数の実際の数にNを再設定する必要があります。この数はF変数に格納されています。

V変数

Vは、選択リストまたはバインド変数の値を格納するデータ・バッファのアドレスからなる配列のポインタです。

記述子を割り当てると、SQLSQLDAAlloc()によってアドレスの配列にあるV[0]からV[N - 1]の要素が0(ゼロ)に設定されます。

選択記述子の場合は、FETCHコマンドを発行する前にデータ・バッファを割り当てて、この配列を設定する必要があります。文

EXEC SQL FETCH ... USING DESCRIPTOR ...

この文は、FETCHされた選択リストの値を、V[0]からV[N - 1]が指しているデータ・バッファに格納するようにOracleに指示します。Oracleにより、i番目の選択リストの値が、V[i]が指しているデータ・バッファに格納されます。

バインド記述子の場合は、OPENコマンドを発行する前に、この配列を設定する必要があります。文

EXEC SQL OPEN ... USING DESCRIPTOR ...

この文では、V[0]からV[N - 1]が指しているバインド変数の値を使用して動的SQL文を実行するようにOracleに指示します。Oracleでは、V[i]が指しているデータ・バッファでi番目のバインド変数の値が参照されます。

L変数

Lは、データ・バッファに格納されている選択リストまたはバインド変数の値の長さからなる配列のポインタです。

選択記述子の場合、この配列は、DESCRIBE SELECT LISTによって、各選択リスト項目に予想される最大値に設定されます。しかし、FETCHコマンドを発行する前に長さを再設定する場合も考えられます。FETCHでは最大でn文字が戻されます(nは、FETCHを実行する前のL[i]の値です)。

長さの形式はOracleデータ型によって異なります。CHARまたはVARCHAR2の選択リスト項目については、DESCRIBE SELECT LISTはL[i]を選択リスト項目の最大長に設定します。NUMBER型の選択リスト項目については、位取りおよび精度が変数の下位バイトおよびその次の上位側バイトにそれぞれ戻されます。精度と位取りの値をL[i]から抽出するには、ライブラリ関数SQLNumberPrecV6()を使用できます。精度と位取りの抽出も参照してください。

FETCHする前に、L[i]を必要なデータ・バッファの長さに再設定する必要があります。たとえば、NUMBERをC言語のchar文字列に強制変換する場合は、L[i]を精度の数値に符号と小数点のための2を加えたものに設定します。NUMBER型をC言語のfloat型に強制変換する場合は、L[i]をシステム上のfloat型の長さに設定します。強制変換したデータ型の長さの詳細は、データの変換を参照してください。

バインド記述子の場合は、OPENコマンドを発行する前に、配列の長さを設定する必要があります。たとえば、strlen()を使用してユーザーが入力したバインド変数文字列の長さを取得してから、適切な配列要素を設定します。

Oracleは、V[i]に格納されているアドレスを使用して間接的にデータ・バッファにアクセスするため、データ・バッファ内の値の長さは認識しません。i番目の選択リスト値またはバインド変数値に対してOracleが使用する長さを変更する場合は、L[i]を必要な長さに再設定してください。入力バッファまたは出力バッファにはそれぞれ異なる長さを指定できます。

T変数

Tは、選択リストまたはバインド変数の値のデータ型コードからなる配列のポインタです。これらのデータ型コードは、V配列の要素が指示するデータ・バッファにOracleデータが格納されるときのデータの変換方法を決定します。

I変数

Iは、標識変数値を格納するデータ・バッファのアドレスの配列へのポインタです。

アドレスの配列のI[0]からI[N - 1]の要素を設定する必要があります。

選択記述子の場合は、FETCHコマンドを発行する前に、アドレスの配列を設定する必要があります。次の文を実行するとします。

EXEC SQL FETCH ... USING DESCRIPTOR ...

この場合、戻されたi番目の選択リスト値がNULLの場合は、I[i]が指す標識変数値が-1に設定されます。それ以外の場合は、(値がNULLでない) 0または(値が切り捨てられている)正の整数に設定されます。

バインド記述子の場合は、OPENコマンドを発行する前に、アドレスの配列とそれに対応付けられた標識変数を設定する必要があります。次の文を実行するとします。

EXEC SQL OPEN ... USING DESCRIPTOR ...

この場合、I[i]が指しているデータ・バッファはi番目のバインド変数の値がNULLであるかどうかを決定します。標識変数の値が-1のとき、関連するバインド変数の値はNULLです。

F変数

Fは、DESCRIBEによって検出される選択リスト項目またはプレースホルダの実際の個数です。

FはDESCRIBEによって設定されます。Fの値が負のときは、割り当てられた記述子のサイズに対してDESCRIBEが検出した選択リスト項目またはプレースホルダが多すぎることを示しています。たとえば、Nを10に設定したときに、DESCRIBEで11個の選択リスト項目またはプレースホルダが検出されると、Fは-11に設定されます。この機能を使用すると、必要に応じて選択リスト項目またはプレースホルダに大きい記憶域を動的に再割当てすることができます。

S変数

Sは、データ・バッファのアドレスの配列へのポインタです。動的SQL文で選択リストまたはプレースホルダの名前が見つかると、それをそのデータ・バッファに格納します。

SQLSQLDAAlloc()を使用してデータ・バッファを割り当ててから、S配列にそれらのアドレスを格納します。

DESCRIBEは、S[i]が指すデータ・バッファ内にi番目の選択リスト項目またはプレースホルダの名前を格納するように、Oracleに指示します。

M変数

Mは、選択リストまたはプレースホルダの名前を格納するデータ・バッファの最大長からなる配列へのポインタです。このデータ・バッファのアドレスは、S配列の要素によって指定されます。

記述子を割り当てると、SQLSQLDAAlloc()は要素M[0]からM[N - 1]までを最大長の配列に設定します。S[i]が指しているデータ・バッファに格納するとき、i番目の名前は必要に応じてM[i]の長さに切り捨てられます。

C変数

Cは、選択リストまたはプレースホルダの名前の現行の長さからなる配列へのポインタです。

DESCRIBEは、現行の長さの配列の中にC[0]からC[N - 1]の要素を設定します。DESCRIBE文を実行すると、配列には選択リスト名またはプレースホルダ名の文字数が格納されます。

X変数

Xは、標識変数の名前を格納するデータ・バッファのアドレスからなる配列へのポインタです。標識変数の値は選択リスト項目およびバインド変数に対応付けできます。ただし、標識変数の名前はバインド変数にのみ対応付けできます。したがって、Xはバインド記述子専用です。

データ・バッファを割り当て、そのアドレスをX配列に保存するには、SQLSQLDAAlloc()を使用します。

DESCRIBE BIND VARIABLESは、i番目の標識変数名をX[i]が指すデータ・バッファに格納するようにOracleに指示します。

Y変数

Yは、標識変数の名前を格納するデータ・バッファの最大長からなる配列へのポインタです。Xと同様に、Yもバインド記述子専用です。

SQLSQLDAAlloc()を使用して要素Y[0]からY[N - 1]までを最大長の配列に割り当てます。X[i]が指しているデータ・バッファに格納するとき、i番目の名前は必要に応じてY[i]の長さに切り捨てられます。

Z変数

Zは、標識変数の名前の現行の長さからなる配列へのポインタです。XおよびYと同様に、Zもバインド記述子専用です。

DESCRIBE BIND VARIABLESは、現行の長さの配列にZ[0]からZ[N - 1]の要素を設定します。DESCRIBEを実行すると、それぞれの標識変数名の文字数がこの配列に格納されます。