SQLBindFileToCol() - 列をファイル参照と関連付ける

SQLBindFileToCol() は、結果セット内の LOB 列をファイル参照またはファイル参照の配列に関連付けます。この関連によって、ステートメント・ハンドルの各行がフェッチされる時、列内のデータがファイルに直接転送されます。

SQLBindFileToCol() の ODBC 仕様

表 1. SQLBindFileToCol() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
なし なし なし

構文

SQLRETURN   SQLBindFileToCol (SQLHSTMT          StatementHandle,   /* hstmt */
                              SQLUSMALLINT      ColumnNumber,      /* icol */
                              SQLCHAR           *FileName,
                              SQLSMALLINT       *FileNameLength,
                              SQLUINTEGER       *FileOptions,
                              SQLSMALLINT       MaxFileNameLength,
                              SQLINTEGER        *StringLength,
                              SQLINTEGER        *IndicatorValue);

関数の引数

この関数のそれぞれの引数のデータ・タイプ、使用、および説明は、SQLBindCol() 引数のデータ・タイプ、使用、説明に似ています。

表 2. SQLBindFileToCol の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLUSMALLINT icol 入力 列を識別する番号。列は、左から右へ、1 から順番に番号が付けられています。
SQLCHAR * FileName 入力 (据え置き)

StatementHandle を使用した次のフェッチ時に、ファイル名またはファイル名の配列が入るロケーションへのポインター。 名前は、各ファイルの絶対パス名です。

このポインターは NULL にはできません。

SQLSMALLINT * FileNameLength 入力 (据え置き) StatementHandle を使用した次のフェッチ時に、ファイル名の長さまたは長さの配列が入るロケーションへのポインター。 このポインターが NULL の場合、ODBC は FileName をヌル終了ストリングとして扱います。結果は、SQL_NTS の長さが渡された場合と同じです。

ファイル名の長さの最大値は 255 です。

SQLUINTEGER * FileOptions 入力 (据え置き) StatementHandle を使用した次のフェッチ時に、データがファイルに書き込まれる際に使用されるファイル・オプションまたはファイル・オプションの配列が入るロケーションへのポインター。 以下の FileOptions 値がサポートされています。
SQL_FILE_CREATE
新規ファイルを作成します。この名前のファイルが既にある場合は、SQL_ERROR が戻されます。
SQL_FILE_OVERWRITE
ファイルが既にある場合、それを上書きします。それ以外の場合、新規ファイルを作成します。
SQL_FILE_APPEND
ファイルが既にある場合、それにデータを追加します。それ以外の場合、新規ファイルを作成します。

ファイルには、1 つのオプションのみを指定できます。デフォルトはありません。

SQLSMALLINT MaxFileNameLength 入力 FileName バッファーの長さを指定します。 アプリケーションで SQLExtendedFetch() を使用して LOB 列の複数行を取り出す場合は、FileName 配列で各エレメントの長さを指定します。
SQLINTEGER * StringLength 出力 (据え置き) 配列または戻される LOB データの長さの配列が入るロケーションへのポインター。このポインターが NULL の場合、何も戻りません。
SQLINTEGER * IndicatorValue 出力 (据え置き) インディケーター値またはフェッチした LOB 値が NULL であるかどうかを示す値の配列が入るロケーションへのポインター。

使用法

LOB ファイル参照引数 (ファイル名、ファイル名の長さ、ファイル参照オプション) は、アプリケーションの環境 (クライアントでの) にあるファイルを参照します。各行を取り出す前に、アプリケーションは、これらの変数にファイルの名前、ファイル名の長さ、およびファイル・オプション (作成、上書き、または追加) が含まれていることを確認する必要があります。これらの値は行のフェッチ操作中に変更できます。

アプリケーションは、行がフェッチされた時にファイルに直接転送される各列につき 1 回 SQLBindFileToCol() を呼び出します。LOB データは、データ変換されず、NULL 終止符を追加することなしに、ファイルに直接書き込まれます。

FileName、FileNameLength、および FileOptions はそれぞれのフェッチの前に設定しておいてください。SQLFetch() または SQLExtendedFetch() が呼び出されると、LOB ファイル参照にバインドされている列のデータが、ファイル参照で示されているファイルに書き込まれます。 SQLBindFileToCol() の据え置かれた入力引数値に関連のあるエラーはフェッチ時に報告されます。LOB ファイル参照、および据え置かれた StringLength と IndicatorValue 出力引数はフェッチ操作中に更新されます。

SQLExtendedFetch() が LOB 列の複数行の取り出しに使用される場合、FileName、FileNameLength、および FileOptions は LOB ファイル参照変数の配列を指します。この場合、MaxFileNameLength は、FileName 配列内の各エレメントの長さを指定し、Db2® ODBC によって使用され、FileName 配列内の各エレメントのロケーションを決定します。 ファイル参照の配列の内容は、SQLExtendedFetch() 呼び出しの際に有効にしておく必要があります。StringLength および IndicatorValue ポインターはそれぞれ、SQLExtendedFetch() の呼び出し時にエレメントが更新される配列を指します。

SQLExtendedFetch() の使用で、指定したファイル名に応じて、複数の LOB 値を複数のファイルに呼び出したり、同じファイルに呼び出したりできます。同じファイルに書き込む場合は、SQL_FILE_APPEND ファイル・オプションを各ファイル名項目に対して指定してください。

戻りコード

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

診断

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

表 3. SQLBindFileToCol の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY002 列番号が無効です。 引数 icol に指定した値が 1 より小さい値でした。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC が、関数を実行または完了させるのに必要なメモリーを割り当てることができない。
HY009 NULL ポインターの使用は無効です。 FileName または FileOptions が NULL ポインターです。
HY010 関数シーケンス・エラーが発生しました。 関数が、実行時データ (SQLParamData()、SQLPutData()) の操作中に呼び出されました。

BEGIN COMPOUND と END COMPOUND 内の SQL 操作中に関数が呼び出されました。

HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできませんでした。
HY090 ストリングまたはバッファーの長さが無効です。 引数 MaxFileNameLength に指定された値は 0 より小さい値でした。
HYC00 ドライバーは使用できません。 アプリケーションは、現在、ラージ・オブジェクトをサポートしない データ・ソースに接続されています。

例

/* Bind a file to a BLOB column */
rc = SQLBindFileToCol(hstmt,
                      1,
                      fileName,
                      &fileNameLength,
                      &fileOption,
                      14,
                      NULL,
                      &fileInd);