SQLBindCol - アプリケーション・プログラム変数に対する列のバインド

SQLBindCol() は、すべてのデータ・タイプで、結果セット内の列をアプリケーション変数 (保管バッファー) に関連づける (バインドする) のに使用します。 データは、SQLFetch() の呼び出し時にデータベース管理システム (DBMS) からアプリケーション・プログラムに転送されます。

また、この関数は、必要な任意のデータ変換を指定する場合にも使用されます。 アプリケーション・プログラムで取得する必要のある結果セットの列ごとに 1 回ずつ呼び出します。

通常は、この関数より前に SQLPrepare() または SQLExecDirect() を呼び出します。 また、SQLDescribeCol() または SQLColAttribute() を呼び出して、対応する結果セット列の属性を取得しなければならない場合もあります。

この呼び出しで指定した保管バッファーにデータを転送する場合は、 SQLFetch() よりも前に SQLBindCol() を呼び出してください。

構文

SQLRETURN SQLBindCol (SQLHSTMT       hstmt,
                      SQLSMALLINT    icol,
                      SQLSMALLINT    fCType,
                      SQLPOINTER     rgbValue,
                      SQLINTEGER     cbValueMax,
                      SQLINTEGER     *pcbValue);

関数引数

表 1. SQLBindCol の引数
データ・タイプ 引数 Use 説明
SQLHSTMT hstmt (hstmt) 入力 ステートメント・ハンドル。
SQLSMALLINT アイコール 入力 列を識別する番号。 列は、1 から始めて左から右へ順に番号が付けられています。
SQLSMALLINT fCType 入力 結果セットの列の番号 icol のアプリケーション・データ・タイプ。 以下のタイプがサポートされています。
  • SQL_C_BIGINT
  • SQL_C_BINARY
  • SQL_C_BLOB
  • SQL_C_BLOB_LOCATOR
  • SQL_C_BOOLEAN
  • SQL_C_CHAR
  • SQL_C_CLOB
  • SQL_C_CLOB_LOCATOR
  • SQL_C_DATE
  • SQL_TYPE_DATE
  • SQL_C_DATETIME
  • SQL_C_DBCHAR
  • SQL_C_DBCLOB
  • SQL_C_DBCLOB_LOCATOR
  • SQL_C_DECFLOAT128
  • SQL_C_DECFLOAT64
  • SQL_C_DECFLOAT32
  • SQL_C_DOUBLE
  • SQL_C_FLOAT
  • SQL_C_LONG
  • SQL_C_SLONG
  • SQL_C_REAL
  • SQL_C_SHORT
  • SQL_C_TIME
  • SQL_C_TIMESTAMP
  • SQL_C_UTINYINT
  • SQL_TYPE_TIME
  • SQL_TYPE_TIMESTAMP
  • SQL_C_WCHAR
  • SQL_VARCHAR
  • SQL_WVARCHAR
  • SQL_VARGRAPHIC

SQL_DEFAULT を指定すると、データはデフォルトのデータ・タイプに転送されます。詳しくは、 表 1 を参照してください。

また多くの場合、SQL_DECIMAL などの SQL データ・タイプ定数も、アプリケーション・データ・タイプに使用できます。
SQLPOINTER rgbValue 出力 (据え置き) Db2 for i CLIがフェッチ時にカラムデータを格納するバッファへのポインタ。

rgbValue が NULL の場合、列はアンバインドされます。
SQLINTEGER cbValueMax 入力 列データの保管に使用可能な rgbValue バッファーのサイズ (バイト単位)。

fCType が SQL_CHAR または SQL_DEFAULT のいずれかである場合、cbValueMax は 0 でなければならず、そうでない場合はエラーが返されます。

fCType が、SQL_VARCHAR、SQL_WVARCHAR、または SQL_VARGRAPHIC を指定している場合、cbValueMax は、返される最大文字数を示します。 CLI は、最初の 2 バイトでこれらのタイプの長さを返すため、rgbValue に指定されるバッファーのサイズは、cbValueMax によって指定される長さより 2 バイト長くなければなりません。 例えば、タイプが SQL_VARCHAR で cbValueMax が 10 の場合、バッファーは少なくとも 12 バイトの長さにする必要があります。 タイプが SQL_WVARCHAR で cbValueMax が 10 の場合、バッファーは少なくとも 22 バイトの長さにする必要があります。

fCType が SQL_DECIMAL または SQL_NUMERIC の場合、cbValueMax は実際の精度と位取りでなければなりません。 この 2 つの値を指定するには、 (精度 * 256) + 位取り を使います。 またこれは、SQLColAttribute() の使用時にこれらのデータ・タイプの長さとして戻される値でもあります。

fCType が SQL_C_TIMESTAMP または SQL_TYPE_TIMESTAMP の場合、精度は cbValueMax の値に基づいて決まります。 cbValueMax が 20 から 32 の間であれば、精度は cbValueMax - 20 になります。 cbValueMax が 20 未満である場合、精度は 0 になります。 cbValueMax が 32より大きい場合、精度は 12 になります。

fcType で任意の形式の 2 バイト文字データを指定した場合は、 cbValueMax はバイト数ではなく 2 バイト文字の数でなければなりません。
SQLINTEGER * pcbValue 出力 (据え置き) Db2 for i CLI が rgbValue バッファーに戻すことができるバイト数を示す値へのポインター。

この列のデータ値が NULL になっている場合、 SQLFetch() はこの引数に SQL_NULL_DATA を戻します。 この列のデータ値が、ヌル終了ストリングで戻された場合、SQL_NTS がこの引数に戻されます。
注:

この関数の場合、rgbValue と pcbValue の両方が据え置き出力になります。つまり、これらのポインターが指す保管場所は、SQLFetch() が呼び出されるまで更新されないということです。 これらのポインターが参照する場所は、SQLFetch() が呼び出されるまでは有効になっている必要があります。

使用法

アプリケーション・プログラムは、 検索したい結果セットの列ごとに SQLBindCol() を 1 回ずつ呼び出します。 SQLFetch() が呼び出されると、これらの各バインド 列のデータは、割り当てられている場所 (rgbValue および pcbValue ポインターにより指定されている) に保管されます。

まず SQLDescribeCol() または SQLColAttribute() を呼び出せば、アプリケーション・プログラムから、この列の属性 (データ・タイプ、長さなど) を照会できます。 さらにこの情報を使用して、保管場所の正しいデータ・タイプを指定したり、他のデータ・タイプへのデータ変換を指示したりすることができます。 詳細については、 Db2 for i CLI関数のデータ型とデータ変換を参照してください。

この後の取り出し要求では、アプリケーション・プログラムは SQLBindCol() を呼び出すことにより、これらの列のバインディングを変更したり、アンバウンド列をバインドしたりすることができます。 新規のバインドは取り出されたデータには適用されず、 SQLFetch() の次回の呼び出しの時に使用されます。 単一の列をアンバインドするには、 rgbValue を NULL に設定して SQLBindCol() を呼び出します。 すべての列をアンバインドするには、アプリケーションは、SQL_UNBIND に設定された fOption 入力を使用して SQLFreeStmt() を呼び出す必要があります。

列は番号によって識別され、左から右に順番に割り当てられ、1から始まる結果セットに表示されます。 結果セットの列数は、引数 FieldIdentifier を SQL_DESC_COUNT に設定して SQLNumResultCols() または SQLColAttribute() を呼び出すことによって判別できます。

SQL_ATTR_UTF8 環境属性が SQL_TRUE に設定されていなければ、すべての文字データはデフォルトのジョブ・コード化文字セット ID (CCSID) として扱われます。

アプリケーションでは、バインドする対象列を全く選ばないことも可能ですし、幾つか選んだり、すべての列を選んだりすることもできます。 SQLFetch() 呼び出しの後は、 アンバインドされた列のデータ (アンバインドされた列のみ) を SQLGetData() で検索できます。 SQLGetData() よりも SQLBindCol() の方が効率的なので、可能であれば常にこちらを使用するようにしてください。

検索されるデータ用に十分な大きさのストレージが、 アプリケーション・プログラムで確実に割り振られるようにする必要があります。 バッファーに可変長データを保管する場合、アプリケーションはバインド列の最大長として必須になっている大きさのストレージを割り振る必要があり、そうでない場合データは切り捨てられます。

出力文字ストリングのデフォルトは、NULL 終了です。 これを変更するには、SQLSetEnvAttr() 属性の SQL_ATTR_OUTPUT_NTS を SQL_FALSE に設定してください。 SQLFetch() の呼び出し後の pcbValue の出力値は、文字データ・タイプの場合は次のように動作します。
  • SQL_ATTR_OUTPUT_NTS 属性が SQL_TRUE に設定されている場合 (デフォルト) は、SQL_NTS が pcbValue に戻されます。
  • SQL_ATTR_OUTPUT_NTS 属性が SQL_FALSE に設定されている場合は、cbValueMax の値 (使用可能な最大バイト数) が pcbValue に戻されます。
  • 切り捨てが発生する場合は、cbValueMax の値 (実際に使用可能なバイト数) が pcbValue に戻されます。

切り捨てが起きて、SQLSetEnvAttr() 属性の SQL_ATTR_TRUNCATION_RTNC が SQL_FALSE に設定されている (これがデフォルト) 場合、SQLFetch() 戻りコードに SQL_SUCCESS が戻ります。 切り捨てが起きて属性が SQL_TRUE である場合は、SQL_SUCCESS_WITH_INFO が戻ります。 切り捨てが起きなければ、どちらの場合も SQL_SUCCESS が戻ります。

引数 cbValueMax が取り出されるデータの量に十分なスペースを割り振っていない場合、切り捨てが起こります。 NULL 終了ストリングを扱えるように環境が設定されている場合、その分の余分なバイトのスペースが cbValueMax で割り振られているようにしてください。 切り捨てに関する追加情報については、 SQLFetch - Fetch next rowを参照してください。

Db2 for i CLI は、 Linux®、UNIX、および Windows 用の DB2® CLI とは異なり、 pcbValue 引数に長さ情報を戻します。 SQL_VARCHAR 列のフェッチ後、 Db2 for i CLI は、バインドされている VARCHAR 構造体の最初の 2 バイトでフェッチされたバイトを戻します。 Db2 for i CLI は、SQL_CHAR の場合とは異なり、 pcbValue に長さを戻しません。 これは、 DB2 CLI for Linux、UNIX、および Windows とは異なります。これらは C VARCHAR の表記を持たず、アプリケーションが SQL_CHAR 列にバインドするときに pcbValue バッファーに長さ情報を組み込みます。

10 進浮動小数点データ・タイプの場合は、デフォルトの記号 C データ・タイプ定数を使用することにより、精度 32、64、または 128 を指定できます。 例えば、精度 128 バイトで 10 進浮動小数点データ・タイプを指定する場合は、fCType を SQL_C_DECIMAL128 に設定できます。

戻りコード

  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

表 2. SQLBindCol SQLSTATE
SQLSTATE 説明 説明
40 003 * ステートメントの完了が不明 関数の処理完了前に、CLI とデータ・ソースの間の通信リンクに障害が起こりました。
58004 システム・エラー リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りの失敗 ドライバーは、関数の処理または完了をサポートするのに必要なメモリーを割り振ることができません。
HY002 列番号が無効 引数 icol に指定された値が 0 です。

引数 icol に指定された値が、 データ・ソースでサポートされている列の最大数を超過しました。
HY003 (HY) プログラム・タイプが範囲外 fCType は正しいデータ・タイプではありません。
HY009 引数値が無効 rgbValue が NULL ポインターです。

引数 cbValueMax に指定された値が 1 より小さくなっており、引数 fCType は SQL_CHAR か SQL_DEFAULT のどちらかになっています。
HY 013 * メモリー管理の問題 ドライバーは、関数の処理または完了をサポートするのに必要なメモリーにアクセスできません。
HY014 (HY) ハンドルが過多 最大数のハンドルがすでに割り振られていますが、 この関数を使うには、さらに記述子ハンドルが必要です。
HY021 内部記述子が無効 内部記述子がアドレッシングできない、割り振れない、または無効な値を持っています。
HYC00 ドライバーでサポートされていない 引数 fCType に指定されているデータ・タイプは、ドライバーで認識はされますが、サポートされていません (HY003 も参照)。

例

SQLFetch - Fetch next row の例を参照してください。

参照