仕様: | DB2 CLI 2.1 |
SQLBindFileToParam() は、 SQL ステートメント内のパラメーター・マーカーをファイル参照またはファイル参照の配列に関連付ける (バインドする) ときに使用されます。この処理により、このステートメントが続けて実行されたときに、その列のデータを LOB 列に直接転送することができます。
LOB ファイル参照引き数 (ファイル名、ファイル名の長さ、ファイル参照オプション) は、アプリケーションの環境内 (クライアント上) のファイルを参照します。 SQLExecute() または SQLExecDirect() を呼び出す前に、アプリケーションはこの情報が据え置き入力バッファーで使用できるかどうかを確認する必要があります。これらの値は、SQLExecute() 呼び出しの間に変更することができます。
構文
SQLRETURN SQLBindFileToParam (SQLHSTMT StatementHandle, SQLUSMALLINT TargetType, SQLSMALLINT DataType, SQLCHAR *FAR FileName, SQLSMALLINT *FAR FileNameLength, SQLUINTEGER *FAR FileOptions, SQLSMALLINT MaxFileNameLength, SQLINTEGER *FAR IndicatorValue);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 (据え置き) | ステートメント・ハンドル。 |
SQLUSMALLINT | TargetType | 入力 (据え置き) | パラメーター・マーカー番号。パラメーターは、1 を最初の番号として順次左から右へ番号が付けられます。 |
SQLSMALLINT | DataType | 入力 | 列の SQL データ・タイプ。データ・タイプは、次のうちの 1 つでなければなりません。
|
SQLCHAR * | FileName | 入力 (据え置き) | ステートメント (StatementHandle) が実行されるときに、ファイル名またはファイル名の配列を入れる場所を指すポインター。これは、ファイルの完全パス名か相対ファイル名のどちらかです。相対ファイル名の場合は、その名前はクライアント・プロセスの現行パスに付加されます。
この引き数をヌル (NULL) にすることはできません。 |
SQLSMALLINT * | FileNameLength | 入力 (据え置き) | 次回の SQLExecute() または SQLExecDirect() のときに StatementHandle を使用して、ファイル名の長さ (またはファイル名の長さの配列) を入れる場所を指すポインター。
このポインターがヌル (NULL) の場合は、 SQL_NTS の長さが想定されます。
ファイル名の長さの最大値は 255 です。 |
SQLUINTEGER * | FileOptions | 入力 (据え置き) | ファイルの読み取りを行うときに、ファイル・オプション (またはファイル・オプションの配列) を入れる場所を指すポインター。この場所は、ステートメント (StatementHandle) を実行するときにアクセスされます。オプションは 1 つしかサポートされません (また、そのオプションを指定する必要があります) 。
このポインターをヌル (NULL) にすることはできません。 |
SQLSMALLINT | MaxFileNameLength | 入力 | これは、FileName バッファーの長さを指定します。アプリケーションが SQLParamOptions() を呼び出して各パラメーターに複数値を指定する場合、これは FileName 配列内の各要素の長さになります。 |
SQLINTEGER * | IndicatorValue | 出力 (据え置き) | 標識値 (または標識値の配列) が入る場所を指すポインターで、パラメーターのデータ値がヌル (NULL) になる場合は、 SQL_NULL_DATA に設定されます。データ値がヌルでない場合は、データ値を 0 にしなければなりません (または、ポインターをヌルに設定できます)。 |
使用法
アプリケーションは、ステートメントが実行されるときにファイルから直接取得しなければならない値を持つパラメーター・マーカーごとに 1 回ずつ SQLBindFileToParam() を呼び出します。ステートメントを実行する前に、FileName、FileNameLength、および FileOptions 値を設定しなければなりません。ステートメントが実行されると、 SQLBindFIleToParam() を使用してバインドされたパラメーターの値が参照ファイルから読み取られ、サーバーに渡されます。
アプリケーションが SQLParamOptions() を使用して各パラメーターに複数値を指定する場合、 FileName、FileNameLength、および FileOptions は、 LOB ファイル参照変数の配列を指します。この場合、MaxFileNameLength は FileName 配列内の各要素の長さを指定し、 DB2 CLI が FileName 配列内の各要素の場所を判別するのに使用されます。
LOB パラメーター・マーカーは、SQLBindFileToParam() を使用することによって入力ファイルに、または SQLBindParameter() を使用することによってストアード・バッファーに関連付ける (バインドする) ことができます。最新のバインド・パラメーター関数呼び出しは、有効なバインドのタイプを判別します。
戻りコード
診断
表 20. SQLBindFileToParam SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
58004 | 予期しないシステム障害です。 | 回復不能システム・エラー。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY004 | SQL のデータ・タイプが範囲外です。 | DataType に指定されている値は、この関数呼び出しにとって有効な SQL タイプではありませんでした。 |
HY009 | 引き数値が無効です。 | FileName、FileOptions、FileNameLength は、NULL ポインターです。 |
HY010 | 関数の順序エラーです。 | 実行時データ (SQLParamData()、SQLPutData()) 操作中に、関数が呼び出されました。
BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | 引き数 MaxFileNameLength に指定された値は、0 より小さい値でした。 |
HY093 | パラメーターの数値が無効です。 | 引き数 TargetType に指定された値は、1 より小さいか、またはサポートされるパラメーターの最大数より大きい値でした。 |
HYC00 | ドライバーが機能していません。 | サーバーは、ラージ・オブジェクト・データ・タイプをサポートしていません。 |
制約
この関数は、ラージ・オブジェクト・データ・タイプをサポートしない DB2 サーバーに接続されている場合には使用できません。関数タイプを SQL_API_SQLBINDFILETOPARAM に設定して SQLGetFunctions() を呼び出し、 SupportedPtr 出力引き数を調べて、現行の接続でその関数がサポートされているかどうかを判別してください。
(ここで完全サンプル dtlob.c を使用することもできます 。)
/* From the CLI sample dtlob.c */ /* ... */ /* bind the file-parameter */ rc = SQLBindFileToParam(hstmt, 3, SQL_BLOB, fileName, &fileNameLength, &fileOption, 14, &fileInd);
参照