SQLBindCol() - 列をアプリケーション変数にバインドする

SQLBindCol() は、列をアプリケーション変数にバインドします。データまたは LOB ロケーターを取り出す結果セット内の列ごとに 1 回、SQLBindCol() を呼び出します。

SQLBindCol() の ODBC 仕様

表 1. SQLBindCol() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり あり

構文

31 ビット・アプリケーションの場合、次の構文を使用します。

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

64 ビット・アプリケーションの場合、次の構文を使用します。

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

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLBindCol() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 結果が戻されるステートメント・ハンドルを指定します。
SQLUSMALLINT icol 入力 バインドする列を示す番号を指定します。 列は、左から右へ、1 から順番に番号が付けられています。
SQLSMALLINT fCType 入力 結果セット内の列番号 icol の C データ・タイプ。 以下のタイプがサポートされています。
  • SQL_C_BIGINT
  • SQL_C_BINARY
  • SQL_C_BINARYXML
  • SQL_C_BIT
  • SQL_C_BLOB_LOCATOR
  • SQL_C_CHAR
  • SQL_C_CLOB_LOCATOR
  • SQL_C_DBCHAR
  • SQL_C_DBCLOB_LOCATOR
  • SQL_C_DECIMAL64
  • SQL_C_DECIMAL128
  • SQL_C_DOUBLE
  • SQL_C_FLOAT
  • SQL_C_LONG
  • SQL_C_SHORT
  • SQL_C_TYPE_DATE
  • SQL_C_TYPE_TIME
  • SQL_C_TYPE_TIMESTAMP
  • SQL_C_TYPE_TIMESTAMP_EXT
  • SQL_C_TINYINT
  • SQL_C_WCHAR
サポートされるデータ・タイプは、接続しているデータ・ソースによって異なります。SQL_C_DEFAULT を指定するとデータがデフォルトの C データ・タイプに 転送されます。
SQLPOINTER rgbValue 出力 (据え置き) バインドされた列からデータをフェッチするときに、Db2® ODBC が列データまたは LOB ロケーターを保管しているバッファー (または、SQLExtendedFetch() 関数を使用している場合はバッファーの配列) を指します。

引数 rgbValue が NULL の場合は、列はアンバインドされます。

SQLINTEGER (31 ビット) または SQLLEN (64 ビット) 1 cbValueMax 入力 列データまたは LOB ロケーターを保管するのに使用 できる rgbValue バッファーのサイズをバイトで指定します。

引数 fCType、バイナリー・ストリングまたは文字ストリング (単一バイトもしくは 2 バイト) を 表しているか、または SQL_C_DEFAULT である場合、cbValueMax は 0 より大きくなければ なりません。そうでない場合はエラーが生じます。 引数 fCType が他のデータ・タイプを表している場合は、引数 cbValueMax は無 視されます。

SQLINTEGER * (31 ビット) または SQLLEN * (64 ビット) 1 pcbValue 出力 (据え置き) Db2 ODBC が rgbValue バッファーに戻すことができるバイト数を示す値 (または値の配列) を指すポインター。fCType が LOB ロケーターである場合、LOB データのサイズではなく、このロケーターのサイズが戻されます。

列のデータ値が NULL の場合は、SQLFetch() はこの引数に SQL_NULL_DATA を戻します。

このポインター値は NULL になることがありえます。 このポインターが NULL ではない場合は、それぞれのバインドされた列ごとに固有でなければなりません。

SQL_NO_LENGTH が戻される可能性もあります。 詳しくは、使用法を参照してください。

注:
  1. 64 ビット・アプリケーションの場合、旧バージョンの Db2 で使用されていたデータ・タイプ SQLINTEGER は、引き続き有効です。ただし、アプリケーションのポータビリティーを最大限に引き出すために、SQLLEN の使用をお勧めします。

重要: ポインター rgbValue および pcbValue が参照するロケーション は、SQLFetch() または SQLExtendedFetch() を呼び出すまでは有効であることを確認しておく必要があります。 SQLBindCol() の場合、ポインター rgbValue および pcbValue は 据え置き出力です。このことは、結果セットから行をフェッチするまでは、これらのポインターが指している 保管場所は更新されないことを意味しています。例えば、ローカル関数内で SQLBindCol() を呼び出す場合、その関数と同じ有効範囲内から SQLFetch() を呼び出すか、あるいは rgbValue バッファー を静的またはグローバルとして割り振る必要があります。

ヒント: 引数 rgbValue が指定するバッファーを、引数 pcbValue が指定するバッファーの後に隣接してメモリー内で配置すると、Db2 ODBC のパフォーマンスがすべて の可変長データ・タイプについて向上します。 詳しくは、使用法を参照してください。

使用法

SQLBindCol() を使用して、結果セットの列を以下のアプリケーションのエレメントと関連付ける、 すなわち、バインド します。
  • すべての C データ・タイプの場合 -- アプリケーション変数または アプリケーション変数の配列 (ストレージ・バッファー)。 列をアプリケーション変数にバインドすると、SQLFetch() または SQLExtendedFetch() を 呼び出したときに、データはデータベース管理システムからアプリケーションへ転送されます。この転送により、SQL タイプから、SQLBindCol() 呼び出しで指定した サポートされる任意の C タイプ変数にデータを変換します。
  • LOB 列の場合 -- LOB ロケーター。LOB ロケーターにバインドすると、SQLFetch() を 呼び出したときに、データそのものではなく、ロケーターがデータベース管理システムからアプリケーションへ転送され ます。LOB ロケーターは、データ全体またはデータの一部を表すことができます。

データまたは LOB ロケーターを取り出す結果セットのそれぞれの列ごとに 1 回、SQLBindCol() を呼び出します。SQLPrepare()、SQLExecDirect()、SQLGetTypeInfo()、またはカタログ関数の 1 つを呼び出す場合に、 結果セットを生成します。列を結果セットにバインドしてから、SQLFetch() を呼び出して、これらの列からアプリケーションの保管場所 (引数 rgbValue および cbValue が指すロケーション) へ、データを 入れます。引数 fCType が LOB ロケーターを指定している場合は、ロケーター値 (LOB データそのもの ではなく) がこれらのロケーションに入ります。このロケーター値は、サーバーでの LOB 列のデータ値 全体を参照します。 SQLBindCol() を呼び出す前に、列属性を取得する必要があることがあります。 これらの属性を取得するには、SQLDescribeCol() または SQLColAttribute() を呼び出します。

SQLFetch() の代わりに SQLExtendedFetch() を使用すると、複数の行を結果セットから取り出して配列内に入れることができます。 この場合、引数 rgbValue は配列を参照します。 同じ結果セットで、SQLExtendedFetch() への呼び出しと SQLFetch() への呼び出しを混合使用することはできません。

結果セットからの情報の取得: 列は番号によって識別され、列は、左から右へ、1 から順番に番号が付けられています。 結果セットの列の数を判別するには、SQLNumResultCols() を呼び出すか、 または引数 FieldIdentifier を SQL_COLUMN_COUNT に設定して SQLColAttribute() を呼び出します。

SQLDescribeCol() または SQLColAttribute() を呼び出して、列の属性 (データ・タイプ、長さなど) を 照会します。その後、この情報を使用し、SQL データ・タイプと結果セットの列の長さに 一致する C データ・タイプと長さを用いて、保管場所を割り振ります。LOB データ・タイプの 場合、LOB 値全体の代わりにロケーターを取り出すことができます。

バインドしたい列がある場合は、結果セットから選択することができます。 アンバインドされた列の場合は、代わりに SQLGetData() を使用するか、または 一緒に SQLBindCol() を使用してデータを取り出します。 一般的には、SQLBindCol() の方が SQLGetData() よりも効率的です。

後続のフェッチの際に、SQLBindCol() を使用して、アプリケーション変数にバインドされる列の変更、または既にアンバインド済みの列のバインドを行うことができます。 新規のバインドは、フェッチ済みデータには適用されません。このようなバインドは次回の フェッチで使用されます。1 列をアンバインドする場合は、rgbValue ポインター を NULL に設定して SQLBindCol() を呼び出します。 すべての列をアンバインドするには、fOption 入力 を SQL_UNBIND に設定して、SQLFreeStmt() を呼び出します。

バッファーの割り振り: 取り出したデータを入れるのに十分なストレージが割り振られていることを確認してください。 可変長データを入れるためにバッファーを割り振る場合は、このバッファーにバインドされる 列から作られる可能性のあるデータの最大長に等しいストレージ量を割り振ります。 この最大値よりも少ないストレージを割り振った場合は、SQLFetch() または SQLExtendedFetch() は、 割り振られたスペースよりも大きなデータがあればいずれも切り捨てます。 固定長データを入れるバッファーを割り振る場合、Db2 ODBC はバッファーのサイズ は C データ・タイプの長さであると想定しています。データ変換を指定すると、データが必要とするスペース量が変更になることがあります。

SQL_GRAPHIC、 SQL_VARGRAPHIC、 または SQL_LONGVARGRAPHIC として定義さ れた列を バインドす る場合は、引数 fCType を SQL_C_DBCHAR、 SQL_C_WCHAR、 または SQL_C_CHAR に設定するこ とができます。 引数 fCType を SQL_C_DBCHAR または SQL_C_WCHAR に設定する と、rgbValue バッファーにフェッチするデータは、2 バイトの NUL 終止符によって NUL 終了します。 引数 fCType を SQL_C_CHAR に設定した場合は、フェッチしたデータは 必ずしも NUL 終了するとは限りません。 いずれの場合も、rgbValue バッファーの長さ (cbValueMax) は バイト単位であり、値は常に 2 の倍数になります。

可変長列をバインドする場合、引数 pcbValue および rgbValue によって 指定されている両方のバッファーを隣接して割り振っておけば、Db2 ODBC は、この両方のバッファーに 一度の操作で書き込むことができます。次の例では、このようなバッファーを隣接して割り振る方法を示しています。

struct {  SQLINTEGER  pcbValue;
          SQLCHAR     rgbValue[MAX_BUFFER];
       } column;
引数 pcbValue および rgbValue が隣接している場合、 バインドが以下のすべての条件を満たして いれば、pcbValue 引数に SQL_NO_TOTAL が戻されます。
  • SQL タイプが可変長タイプ。
  • 列タイプが NOT NULLABLE。
  • ストリング切り捨てが起きている。

データ切り捨ての処理: SQLFetch() または SQLExtendedFetch() は、データを切り捨てる場合は SQL_SUCCESS_WITH_INFO を 戻し、引数 pcbValue を完全なデータに必要なスペース量 (バイト) を表す値に設定します。

切り捨ては、SQL_ATTR_MAX_LENGTH ステートメント属性の影響も受けます (この属性は、 アプリケーションが戻すデータ量を制限するために使用されます)。 以下の手順によって、切り捨ての警告を使用不可に設定することができます。
  1. SQLSetStmtAttr() を呼び出します。
    • 引数 Attribute を SQL_ATTR_MAX_LENGTH に設定します。
    • 引数 ValuePtr、受け取る可変長列の最大長 (バイト) の値を含むバッファーを 指すようにします。
  2. SQL_ATTR_MAX_LENGTH ステートメント属性に設定した値と同じサイズ (NUL 終止符を追加) の バッファーとして、rgbValue 引数を SQLBindCol() 呼び出しで割り振ります。
列データが指定した最大長よりも大きい場合は、引数 pcbValue が指している バッファーに、実際の長さではなく最大長が戻されます。 データが、SQL_ATTR_MAX_LENGTH ステートメント属性で指定している最大長を超えたために 切り捨てられた場合、この切り捨てについての警告を受け取ることはあり ません。SQLFetch() および SQLExtendedFetch() は、このようにして切り捨てられたデータに対して、SQL_SUCCESS を戻します。

SQL_ROWID データの入っている列をバインドする場合、引数 fCType を SQL_C_CHAR または SQL_C_DEFAULT に設定することができます。 引数 rgbValue が指定するバッファーの中にフェッチしたデータは NUL 終了し ます。データベース管理システムの ROWID 列の最大長は 40 バイトです。そのため、このタイプのデータを切り捨てなしで 取り出すには、少なくとも 40 バイトの rgbValue バッファーをアプリケーションで 割り振る必要があります。

コード化スキームの処理: Db2 ODBC ドライバーは、CURRENTAPPENSCH キーワード (初期化ファイルにあり) および引数 fCType (SQLBindCol() 呼び出しで指定) の設定値を通じて、 以下のコード化スキームの 1 つを文字データおよびグラフィック・データ用に決定します。
  • ODBC ドライバーは、以下の条件が両方とも満たされる場合は、EBCDIC データを アプリケーション変数に入れます。
    • CURRENTAPPENSCH = EBCDIC が初期設定ファイルで指定されているか、CURRENTAPPENSCH キーワードに指定された CCSID が EBCDIC CCSID であるか、あるいは、CURRENTAPPENSCH キーワードが初期設定ファイルで指定されていない。
    • 引数 fCType が、SQLBindCol() 呼び出しで SQL_C_CHAR または SQL_C_DBCHAR を指定している。
  • ODBC ドライバーは、引数 fCType が、SQLBindCol() 呼び出しで SQL_C_WCHAR を指定している場合は、ユニコード UCS-2 データをアプリケーション変数に入れます。
  • ODBC ドライバーは、以下の条件が両方とも満たされる場合は、ユニコード UTF-8 データを アプリケーション変数に入れます。
    • CURRENTAPPENSCH = UNICODE が初期設定ファイルで指定されているか、あるいは CURRENTAPPENSCH キーワードに指定された CCSID がユニコード CCSID (1200、1208、13488 または 17584) である。
    • 引数 fCType が、SQLBindCol() 呼び出しで SQL_C_CHAR を指定している。
  • ODBC ドライバーは、以下の条件が両方とも満たされる場合は、ASCII データを アプリケーション変数に入れます。
    • CURRENTAPPENSCH = ASCII が初期設定ファイルで指定されているか、あるいは CURRENTAPPENSCH キーワードに指定された CCSID が ASCII CCSID である。
    • 引数 fCType が、SQLBindCol() 呼び出しで SQL_C_CHAR または SQL_C_DBCHAR を指定している。

取り出された UTF-8 データは単一バイトの NUL 終止符によって終了するのに対して、 取り出された UCS-2 データは 2 バイトの NUL 終止符によって終了します。

LOB 列のバインディング: 一般には、LOB ロケーターは他のいずれのデータ・タイプとも同じように扱われます が、LOB ロケーターを使用する場合は、以下のような違いがあります。
  • LOB ロケーターにバインドされた列から C データ・タイプをフェッチすると、 サーバーは、ロケーター値を生成し、データではなくロケーターのみをアプリケーションに渡します。
  • SQLGetSubString() を呼び出してロケーターを別の LOB の部分で定義すると、サーバーは新しいロケーターを生成し、ロケーターのみをアプリケーションに転送します。
  • ロケーターの値は、現行トランザクション内でのみ有効です。 ロケーターをフェッチするために使用するカーソルを定義する際に WITH HOLD 属性を指定した場合でも、 ロケーター値を保管して、現行トランザクションを越えて使用することはできません。
  • FREE LOCATOR ステートメントを使用して、トランザクションの終了前に、 ロケーターを解放することができます。
  • アプリケーションがロケーターを受け取った場合、SQLGetSubString() を使用 して、LOB 値の一部を受け取るか、あるいはサブストリングを表す別のロケーターを生成することができます。また、ロケーター値は、(SQLBindParameter() 用いて) パラメーター・マーカーの入力 として使用することもできます。

    LOB ロケーターはデータベース位置を指すポインターではありま せん。それは、LOB 値への参照 (その LOB 値のスナップショット) です。 カーソルの現在位置と LOB 値が抜き出された行との間に関連はありません。 したがって、カーソルが別の行に移った後でも、LOB ロケーター (およびそれが表す値) を まだ参照することができます。

  • ロケーターを用いると、SQLGetSubString() とともに SQLGetPosition() および SQLGetLength() を 使用して、LOB 値のサブストリングを定義することができます。
次のいずれかのデータ・タイプに対して、LOB 列をバインドすることができます。
  • ストレージ・バッファー (LOB データ値全体を保持)
  • LOB ロケーター (ロケーター値のみを保持)

最新の列バインド関数呼び出しは、有効なバインドのタイプを判別します。

戻りコード

SQLBindCol() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLBindCol() の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY002 列番号が無効です。 引数 icol に指定された値が 0 より小さいか、 または結果セットの列の数よりも大きい値です。
HY003 プログラム・タイプが範囲外です。 引数 fCType が、有効なデータ・タイプでも SQL_C_DEFAULT でもありません。
HY010 関数シーケンス・エラーが発生しました。 この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。
HY090 ストリングまたはバッファーの長さが無効です。 引数 cbValueMax に指定された値が 0 より小さい値です。
HYC00 ドライバーは使用できません。 Db2 ODBC は、引数 fCType が指定した値をサポートしません。

重要: フェッチ時に、バインドされた列に関係する追加の診断メッセージが報告されることがあります。

例

詳しくは、SQLExtendedFetch() を参照してください。この関数はバインドされた各列に対して複数の行を含む一連のデータを戻します。