仕様: | DB2 CLI 2.1 |
SQLBindFileToCol() は、結果セット内の LOB 列を 1 つのファイル参照またはファイル参照の配列に関連付ける (バインドする) ときに使用します。この処理により、ステートメント・ハンドル用に各行が取り出された時点で、その列のデータをファイルへ直接転送することができます。
LOB ファイル参照引き数 (ファイル名、ファイル名の長さ、ファイル参照オプション) は、アプリケーションの環境内 (クライアント上) のファイルを参照します。各行を取り出す前に、アプリケーション側でこれらの変数にファイル名、ファイル名の長さ、およびファイル・オプション (新規 / 上書き / 追加) が含まれていることを確認する必要があります。これらの値は、取り出しのたびに変更することができます。
構文
SQLRETURN SQLBindFileToCol (SQLHSTMT StatementHandle, /* hstmt */ SQLUSMALLINT ColumnNumber, /* icol */ SQLCHAR *FAR FileName, SQLSMALLINT *FAR FileNameLength, SQLUINTEGER *FAR FileOptions, SQLSMALLINT MaxFileNameLength, SQLINTEGER *FAR StringLength, SQLINTEGER *FAR IndicatorValue);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLUSMALLINT | icol | 入力 | 列を識別する番号。列は、1 を最初の番号として順次左から右へ番号が付けられます。 |
SQLPOINTER | FileName | 入力 (据え置き) | 次回の取り出しの時に StatementHandle を使用して、ファイル名またはファイル名の配列を入れる場所を指すポインター。これは、ファイルの完全パス名か相対ファイル名のどちらかです。相対ファイル名の場合は、その名前は実行中のアプリケーションの現行パスに付加されます。このポインターをヌル (NULL) にすることはできません。 |
SQLSMALLINT * | FileNameLength | 入力 (据え置き) | 次回の取り出しの時に StatementHandle を使用して、ファイル名の長さ (またはファイル名の長さの配列) を入れる場所を指すポインター。このポインターがヌル (NULL) の場合は、
SQL_NTS の長さが想定されます。
ファイル名の長さの最大値は 255 です。 |
SQLUINTEGER * | FileOptions | 入力 (据え置き) | 次回の取り出しの時に StatementHandle を用いて、ファイルの書き込みを行うときに使用するファイル・オプション (またはファイル・オプションの配列) を入れる場所を指すポインター。以下の FileOptions がサポートされます。
1 つのファイルに対してオプションは 1 つしか選択できず、省略時値はありません。 |
SQLSMALLINT | MaxFileNameLength | 入力 | これは FileName バッファーの長さを指定するか、またはアプリケーションが SQLFetchScroll() を使用して LOB 列用に複数行を取り出す場合は FileName 配列内の各要素の長さを指定します。 |
SQLINTEGER * | StringLength | 出力 (据え置き) | 返される LOB データのバイト単位の長さ (または長さの配列) を入れる場所を指すポインター。ポインターがヌル (NULL) の場合は、何も返されません。 |
SQLINTEGER * | IndicatorValue | 出力 (据え置き) | 標識値 (または標識値の配列) を入れる場所を指すポインター。 |
使用法
アプリケーションは、行が取り出されるときにファイルへ直接転送しなければならない列ごとに 1 回ずつ SQLBindFileToCol() を呼び出します。 LOB データは、データ変換およびヌル終了の追加をせずに、ファイルに直接書き込まれます。
FileName、 FileNameLength、および FileOptions は各取り出しの前に設定しなければなりません。 SQLFetch() または SQLFetchScroll() が呼び出されるとき、 LOB ファイル参照にバインドされている列のデータは、ファイル参照によって指されているファイル (複数を含む) に書き込まれます。取り出しの際に、 SQLBindFileToCol() の据え置き入力引き数値に関連したエラーが報告されます。 LOB ファイル参照、および据え置かれた StringLength および IndicatorValue 出力引き数は、取り出し操作が行われるたびに更新されます。
SQLFetchScroll() を使用して LOB 列用の複数行を取り出す場合、 FileName、FileNameLength、 および FileOptions は、 LOB ファイル参照変数の配列を指します。この場合、MaxFileNameLength は FileName 配列内の各要素の長さを指定し、 DB2 CLI が FileName 配列内の各要素の場所を判別するのに使用されます。ファイル参照の配列の内容は、SQLFetchScroll() 呼び出しの時に有効でなければなりません。 StringLength および IndicatorValue ポインターは、それぞれ SQLFetchScroll() 呼び出しの際に更新されている要素の配列を指します。
SQLFetchScroll() を使用して、指定されたファイル名に従い、複数のファイルまたは同一のファイルに複数の LOB 値を書き込むことができます。同一ファイルに書き込む場合、ファイル名を入力するたびに SQL_FILE_APPEND ファイル・オプションを指定する必要があります。ファイル参照の配列の列方向バインドは、SQLFetchScroll() を使用する場合だけサポートされます。
戻りコード
診断
表 18. SQLBindFileToCol SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
58004 | 予期しないシステム障害です。 | 回復不能システム・エラー。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY002 | 列の番号が無効です。 | 引き数 icol に指定された値は、1 より小さい値でした。
引き数 icol に指定された値が、データ・ソースでサポートされる列の最大数を超えました。 |
HY009 | 引き数値が無効です。 | FileName、StringLength、または FileOptions は NULL ポインターです。 |
HY010 | 関数の順序エラーです。 | 実行時データ (SQLParamData()、
SQLPutData()) 操作中に、関数が呼び出されました。
BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | 引き数 MaxFileNameLength に指定された値は、 0 より小さい値でした。 |
HYC00 | ドライバーが機能していません。 | アプリケーションは現在、ラージ・オブジェクトをサポートしないデータ・ソースに接続しています。 |
制約
この関数は、ラージ・オブジェクト・データ・タイプをサポートしない DB2 サーバーに接続されている場合には使用できません。関数タイプを SQL_API_SQLBINDFILETOCOL に設定してある SQLGetFunctions() を呼び出し、 SupportedPtr 出力引き数を調べて、現行の接続でその関数がサポートされているかどうかを判別してください。
(ここで完全サンプル dtlob.c を使用することもできます 。)
/* From the CLI sample dtlob.c */ /* ... */ /* bind a file to the BLOB column */ rc = SQLBindFileToCol(hstmt, 1, fileName, &fileNameLength, &fileOption, 14, NULL, &fileInd);
参照