SQLBindFileToParam() - パラメーター・マーカーをファイル参照にバインドする

SQLBindFileToParam() は、SQL ステートメント内のパラメーター・マーカーをファイル参照またはファイル参照の配列に関連付けます。この関連付けによって、 ステートメントを後で実行するときに、ファイル内のデータを LOB 列に直接転送できます。

SQLBindFileToParam() の ODBC 仕様

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

構文

SQLRETURN SQLBindFileToParam (
             SQLHSTMT          StatementHandle,           /* hstmt */
             SQLUSMALLINT      TargetType,                /* ipar */
             SQLSMALLINT       DataType,                  /* fSqlType */
             SQLCHAR           *FileName,
             SQLSMALLINT       *FileNameLength,
             SQLUINTEGER       *FileOptions,
             SQLSMALLINT       MaxFileNameLength,
             SQLINTEGER        *IndicatorValue);

関数の引数

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

表 2. SQLBindFileToParam の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLUSMALLINT TargetType 入力 パラメーター・マーカー番号。パラメーターは、左から右へ、1 から順番に番号が付けられています。
SQLSMALLINT DataType 入力 列の SQL データ・タイプ。 データ・タイプは、以下のいずれかにしてください。
  • SQL_BLOB
  • SQL_CLOB
  • SQL_DBCLOB
SQLCHAR * FileName 入力 (据え置き)

ステートメント (StatementHandle) が実行される際に、ファイル名またはファイル名の配列が入るロケーションへのポインター。これは、ファイルの絶対パス名です。

この引数は NULL にはできません。

SQLSMALLINT * FileNameLength 入力 (据え置き)

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

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

SQLUINTEGER * FileOptions 入力 (据え置き) ファイルの読み込み時に使用されるファイル・オプション (またはファイル・オプションの配列) が入るロケーションへのポインター。ステートメント (StatementHandle) が実行されるとロケーションにアクセスします。 1 つのオプションのみがサポートされ、必ず指定する必要があります。
SQL_FILE_READ
オープン、読み取り、クローズが可能な通常のファイル。ファイルがオープンされると、長さが計算されます。

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

SQLSMALLINT MaxFileNameLength 入力

FileName バッファーの長さ。アプリケーションが SQLSetStmtAttr を呼び出し、各パラメーターに対して複数の値を指定する場合、これは、FileName 配列にある各エレメントの長さになります。

SQLINTEGER * IndicatorValue 入力 (据え置き) インディケーター値または値の配列を含むロケーションへのポインター。これは LOB データ値を NULL にする場合 SQL_NULL_DATA に設定されます。 データ値がヌル以外の場合は、ロケーションの値を、0 に設定するか、ポインターを NULL に設定する必要があります。

使用法

LOB ファイル参照引数 (ファイル名、ファイル名の長さ、ファイル参照オプション) は、アプリケーションの環境 (クライアントでの) 内にあるファイルを参照します。SQLExecute() または SQLExecDirect() の呼び出しの前に、アプリケーションによって、この情報が据え置かれた入力バッファーで使用できるかを確認する必要があります。これらの値は SQLExecute() 呼び出しの間に変更できます。

アプリケーションが各パラメーター・マーカーにつき 1 回 SQLBindFileToParam() を呼び出します。ステートメントが実行されると、パラメーター・マーカーの値がファイルから直接取得されます。ステートメントを実行する前に、FileName、FileNameLength および FileOptions の値を設定しておいてください。ステートメントの実行時に、SQLBindFileToParam() を使用してバインドされたパラメーターのデータが、参照ファイルから読み込まれサーバーに渡されます。

アプリケーションが、SQLSetStmtAttr を使用して各パラメーターに複数の値を指定する場合、FileName、FileNameLength、 および FileOptions は LOB ファイル参照変数の配列を指します。この場合、MaxFileNameLength は、FileName 配列内の各エレメントの長さを指定し、Db2® ODBC によって使用され、FileName 配列内の各エレメントのロケーションを決定します。

LOB パラメーター・マーカーを、SQLBindFileToParam() を使用して、入力ファイルに関連付けるか、SQLBindParameter() を使用して保管バッファーに関連付けることができます。最新のバインド・パラメーター関数呼び出しは、有効なバインドのタイプを判別します。

戻りコード

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

診断

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

表 3. SQLBindFileToParam の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY004 SQL データ・タイプが範囲外です。 DataType に指定した値が、この関数呼び出しの有効な SQL タイプではありませんでした。
HY009 引数の値が無効です。 FileName または FileOptions が NULL ポインターです。
HY010 関数シーケンス・エラーが発生しました。 関数が、実行時データ (SQLParamdata()、SQLPutData()) の操作中に呼び出されました。

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

HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできませんでした。
HY090 ストリングまたはバッファーの長さが無効です。 入力引数 MaxFileNameLength に指定された値は 0 より小さい値でした。
HY093 パラメーター番号が無効です。 TargetType に指定した値が 1 より小さい値でした。
HYC00 ドライバーは使用できません。 Db2 ODBC は、表名の修飾子として 'catalog' はサポートしていません。

例

  /* Bind a file reference to a parameter */
  rc = SQLBindFileToParam(hstmt,
                          3,
                          SQL_BLOB,
                          fileName,
                          &fileNameLength,
                          &fileOption,
                          14,
                          &fileInd);