CLI の手引きおよび解説書

SQLBindFileToCol - LOB 列に LOB ファイル参照をバインドする

目的


仕様: 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);

関数引き数


表 17. SQLBindFileToCol 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLUSMALLINT icol 入力 列を識別する番号。列は、1 を最初の番号として順次左から右へ番号が付けられます。
SQLPOINTER FileName 入力 (据え置き) 次回の取り出しの時に StatementHandle を使用して、ファイル名またはファイル名の配列を入れる場所を指すポインター。これは、ファイルの完全パス名か相対ファイル名のどちらかです。相対ファイル名の場合は、その名前は実行中のアプリケーションの現行パスに付加されます。このポインターをヌル (NULL) にすることはできません。
SQLSMALLINT * FileNameLength 入力 (据え置き) 次回の取り出しの時に StatementHandle を使用して、ファイル名の長さ (またはファイル名の長さの配列) を入れる場所を指すポインター。このポインターがヌル (NULL) の場合は、 SQL_NTS の長さが想定されます。

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

SQLUINTEGER * FileOptions 入力 (据え置き) 次回の取り出しの時に StatementHandle を用いて、ファイルの書き込みを行うときに使用するファイル・オプション (またはファイル・オプションの配列) を入れる場所を指すポインター。以下の FileOptions がサポートされます。

SQL_FILE_CREATE
新しいファイルを作成します。この名前のファイルがすでに存在する場合は、SQL_ERROR が返されます。
SQL_FILE_OVERWRITE
ファイルがすでに存在する場合は、そのファイルを上書きします。存在しない場合は、新しいファイルを作成します。
SQL_FILE_APPEND
ファイルがすでに存在する場合は、そのファイルにデータを付加します。存在しない場合は、新しいファイルを作成します。

1 つのファイルに対してオプションは 1 つしか選択できず、省略時値はありません。

SQLSMALLINT MaxFileNameLength 入力 これは FileName バッファーの長さを指定するか、またはアプリケーションが SQLFetchScroll() を使用して LOB 列用に複数行を取り出す場合は FileName 配列内の各要素の長さを指定します。
SQLINTEGER * StringLength 出力 (据え置き) 返される LOB データのバイト単位の長さ (または長さの配列) を入れる場所を指すポインター。ポインターがヌル (NULL) の場合は、何も返されません。
SQLINTEGER * IndicatorValue 出力 (据え置き) 標識値 (または標識値の配列) を入れる場所を指すポインター。

使用法

アプリケーションは、行が取り出されるときにファイルへ直接転送しなければならない列ごとに 1 回ずつ SQLBindFileToCol() を呼び出します。 LOB データは、データ変換およびヌル終了の追加をせずに、ファイルに直接書き込まれます。

FileNameFileNameLength、および FileOptions は各取り出しの前に設定しなければなりません。 SQLFetch() または SQLFetchScroll() が呼び出されるとき、 LOB ファイル参照にバインドされている列のデータは、ファイル参照によって指されているファイル (複数を含む) に書き込まれます。取り出しの際に、 SQLBindFileToCol() の据え置き入力引き数値に関連したエラーが報告されます。 LOB ファイル参照、および据え置かれた StringLength および IndicatorValue 出力引き数は、取り出し操作が行われるたびに更新されます。

SQLFetchScroll() を使用して LOB 列用の複数行を取り出す場合、 FileName、FileNameLength、 および FileOptions は、 LOB ファイル参照変数の配列を指します。この場合、MaxFileNameLengthFileName 配列内の各要素の長さを指定し、 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 引き数値が無効です。 FileNameStringLength、または FileOptions は NULL ポインターです。
HY010 関数の順序エラーです。 実行時データ (SQLParamData()SQLPutData()) 操作中に、関数が呼び出されました。

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

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

制約

この関数は、ラージ・オブジェクト・データ・タイプをサポートしない DB2 サーバーに接続されている場合には使用できません。関数タイプを SQL_API_SQLBINDFILETOCOL に設定してある SQLGetFunctions() を呼び出し、 SupportedPtr 出力引き数を調べて、現行の接続でその関数がサポートされているかどうかを判別してください。

CLI サンプル dtlob.c

(ここで完全サンプル 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);
    
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]