SQLBindFileToParam() - パラメーター・マーカーをファイル参照にバインドする
SQLBindFileToParam() は、SQL ステートメント内のパラメーター・マーカーをファイル参照またはファイル参照の配列に関連付けます。この関連付けによって、 ステートメントを後で実行するときに、ファイル内のデータを LOB 列に直接転送できます。
SQLBindFileToParam() の ODBC 仕様
| 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);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
| SQLUSMALLINT | TargetType | 入力 | パラメーター・マーカー番号。パラメーターは、左から右へ、1 から順番に番号が付けられています。 |
| SQLSMALLINT | DataType | 入力 | 列の SQL データ・タイプ。 データ・タイプは、以下のいずれかにしてください。
|
| SQLCHAR * | FileName | 入力 (据え置き) | ステートメント (StatementHandle) が実行される際に、ファイル名またはファイル名の配列が入るロケーションへのポインター。これは、ファイルの絶対パス名です。 この引数は NULL にはできません。 |
| SQLSMALLINT * | FileNameLength | 入力 (据え置き) | StatementHandle を使用した SQLExec() または SQLExecDirect() の次の実行時に、ファイル名の長さ (または長さの配列) が入るロケーションへのポインター。このポインターが NULL の場合、ODBC は FileName をヌル終了ストリングとして扱います。結果は、SQL_NTS の長さが渡された場合と同じです。 ファイル名の長さの最大値は 255 です。 |
| SQLUINTEGER * | FileOptions | 入力 (据え置き) | ファイルの読み込み時に使用されるファイル・オプション (またはファイル・オプションの配列) が入るロケーションへのポインター。ステートメント (StatementHandle) が実行されるとロケーションにアクセスします。
1 つのオプションのみがサポートされ、必ず指定する必要があります。
このポインターは 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() を使用して保管バッファーに関連付けることができます。最新のバインド・パラメーター関数呼び出しは、有効なバインドのタイプを判別します。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 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);