| 仕様: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLBindCol() は、すべての C データ・タイプについて、結果セ ット内の 列をアプリケーション変数に関連付ける (バインドする) ために 使用されます。SQLFetch() を呼び出すと、データは DBMS から アプリケーションに転送されます。 データの転送時に、データ変換が行われる場合があります。
SQLBindCol() は、アプリケーションで検索を必要とする結 果セット内の列ごとに 1 回呼び出されます。
一般に、この関数の前に SQLPrepare() または SQLExecDirect() を 呼び出し、この関数の後に SQLFetch() を呼び出します。 列属性は、SQLBindCol() の呼び出し前に必要になる場合もありますが 、SQLDescribeCol() を使用して入手することができます。
構文
SQLRETURN SQLBindCol (SQLHSTMT StatementHandle, /* hstmt */
SQLUSMALLINT ColumnNumber, /* icol */
SQLSMALLINT TargetType, /* fCType */
SQLPOINTER TargetValuePtr, /* rgbValue */
SQLINTEGER BufferLength, /* cbValueMax */
SQLINTEGER *FAR StrLen_or_IndPtr); /* pcbValue */
関数の引き数
| データ・タイプ | 引き数 | 用途 | 説明 |
|---|---|---|---|
| SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
| SQLUSMALLINT | ColumnNumber | 入力 | 列を示す番号。列は左から右へ順番に番号が付けられる。 列番号は 1 から始まる。 |
| SQLSMALLINT | TargetType | 入力 | 結果セット内の列番号 ColumnNumber の C データ・タイプ。
以下のタイプがサポートされる。
SQL_C_DEFAULT を指定すると、データがそのデフォルトの C データ・タイプに転送される。 |
| SQLPOINTER | TargetValuePtr | 入出力 (据え置き) | 列データの取り出し時に DB2 CLI が列データを保管するバッファーへのポインター。
TargetValuePtr がヌルである場合、列はアンバインドされる。 |
| SQLINTEGER | BufferLength | 入力 | 列データの保管に使用可能な TargetValuePtr バッファーのバイト単位のサイズ。
TargetType がバイナリー・ストリングまたは文字ストリングを示すか、あるい は SQL_C_DEFAULT である場合、BufferLength は > 0 でなければならない 。0 以下であれば、エラーが戻される。それ以外の場合、この引き数は無視される。 |
| SQLINTEGER * | StrLen_or_IndPtr | 入出力 (据え置き) | DB2 CLI が TargetValuePtr バッファーに戻すことができるバイト数を示す値へのポインター。
SQLFetch() は、列のデータ値がヌルの場合に、この引き数 に SQL_NULL_DATA を戻す。
SQL_NO_LENGTH も戻される場合がある。 詳細については、使用法のセクションを参照。 |
この関数の場合、TargetValuePtr と StrLen_or_Ind は両方とも 据え置き出力であり、これらのポインターが指し示す保管場所は、結果セット 行が取り出されるまでは更新されません。結果として、これらのポインターによって 参照される場所は、SQLFetch() が呼び出されるまで有効のままでなければなりません。 例えば、ローカル関数内で SQLBindCol() を呼び出す場合、SQLFetch() はこの関数の同じ効力範囲内から 呼び出される必要があります。あるいは、TargetValuePtr バッファーが静的またはグローバルとして割り当てられているか、 または宣言されている必要があります。
使用法
アプリケーションでの SQLBindCol() 呼び出しは、データを検索する必要がある 結果セット内の列ごとに 1 回です。結果セットは 、SQLExecute() または SQLExecDirect() を呼び出すこと によって生成されます。SQLFetch() を呼び出すと、このような バインド された各列内のデータは、割り当てられた 場所 (ポインター TargetValuePtr と StrLen_or_Ind によって 示される) に入れられます。
列は番号によって識別され、左から右へ順番に割り当てられます。 列番号は 1 から始まります。
結果セット内の列数は、SQLNumResultCols() を呼び出すことによって 判別することができます。
アプリケーションでは、最初に SQLDescribeCol() を呼び出すことによって、列の属性 (データ・タイプや長さなど) を照会することができます。 次に、この情報を使用して、正しいデータ・タイプと長さの保管場所を割り当て、 別のデータ・タイプへのデータ変換を指示することができます。
アプリケーションでは各列だけをバインドしないように選択することもでき ますし、どの列もバインドしないように選択することさえできます。現在行に関してバインドされた列を取り出し た後に、SQLGetData() を使用することにより、どの列のデータを検索することもできます。
以後の取り出しで、アプリケーションでは、SQLBindCol() を呼び出すこと によって、これらの列のバインディングを変更したり、以前にアンバインドした列を バインドすることができます。新しいバインディングは、すでに取り出されたデータには適用 されずに、次の取り出し時に使用されます。単一の列をアンバインドするた めには、TargetValuePtr ポインターを NULL に設定 して SQLBindCol() を呼び出します。すべての列をアンバイン ドするためには、アプリケーションで SQLFreeStmt() を呼び出す必要があります。
アプリケーションでは、取り出すべきデータのために確実に十分なストレージを 割り当てておかねばなりません。バッファーに可変長データを入れる場合、 アプリケーションではバインドされた列が必要とする最大長のサイズのストレージを 割り当てる必要があります。 さもないと、データが切り捨てられる可能性があります。バッファーに固定長データを 入れる場合、DB2 CLI は、バッファーのサイズが C データ・タイプの長さであ ると見なします。 データ変換を指定した場合、必要とされるサイズが影響を受ける可能性があり ます。
ストリングの切り捨てが発生した場合、SQL_SUCCESS_WITH_INFO が戻され、 StrLen_or_IndPtr が、アプリケーションへの戻りのために使用可能な TargetValuePtr の実際のサイズに設定されます。
戻りコード
診断
| SQLSTATE | 説明 | 解説 |
|---|---|---|
| 07009 | 無効な記述子索引。 | 引き数 ColumnNumber に指定した値が、結果セット内の最大列数を超えている。 |
| 40003 08S01 | 通信リンク・エラー。 | 関数の完了前に、アプリケーションとデータ・ソース間の通信リンクに障害が生じた。 |
| 58004 | 予期しないシステム障害。 | 回復不能なシステム・エラー。 |
| HY001 | メモリーの割り振りの失敗。 | DB2 CLI が、関数の実行または完了のサポートに必要なメモリーを 割り当てることができない。 |
| HY002 | 無効な列番号。 | 引き数 ColumnNumber に指定した値が 0 より小さい。
引き数 ColumnNumber に指定した値が、データ・ソースによってサポート されている最大列数を超えた。 |
| HY003 | プログラム・タイプが範囲外。 | TargetType が有効なデータ・タイプまたは SQL_C_DEFAULT ではない。 |
| HY013 | 予期しないメモリー処理エラー。 | DB2 CLI が、関数の実行または完了のサポートに必要なメモリーに アクセスできない。 |
| HY090 | 無効なストリング長またはバッファー長。 | 引き数 BufferLength に指定した値が 1 より小さく、 引き数 TargetType が SQL_C_CHAR、 SQL_C_BINARY または SQL_C_DEFAULT のいずれかである。 |
| HYC00 | ドライバーが使用不可である。 | 引き数 TargetType に指定したデータ・タイプは、DB2 CLI によって 認識されるが、サポートされない。 |
バインド列に関する追加の診断メッセージが、取り出し時に報告される場合があります。
制約事項
出力バッファーは、ワードで (均等に) 位置合わせする必要があります。 Motorola 68000 などの多くのプロセッサーにワード位置合わせの規則があり、 文字以外のデータ・タイプの場合、アプリケーションはバッファーを正しく位置合わせする必要がある。
関連した解説