`SQLBindFileToParam()` - Bind a parameter marker to a file reference

SQLBindFileToParam() associates a parameter marker in an SQL statement to a file reference or to an array of file references. This association enables data from the file to be transferred directly into a LOB column when the statement is executed later.

ODBC specifications for `SQLBindFileToParam()`

Table 1. `SQLBindFileToParam()` specifications
ODBC specification level	In X/Open CLI CAE specification?	In ISO CLI specification?
No	No	No

Syntax

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

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. SQLBindFileToParam arguments
Data type	Argument	Use	Description
SQLHSTMT	StatementHandle	input	Statement handle.
SQLUSMALLINT	TargetType	input	Parameter marker number. Parameters are numbered sequentially, from left to right, starting at 1.
SQLSMALLINT	DataType	input	SQL data type of the column. The data type must be one of these types: SQL_BLOB SQL_CLOB SQL_DBCLOB
SQLCHAR *	FileName	input (deferred)	Pointer to the location that contains the file name or an array of file names when the statement (StatementHandle) is executed. This is the absolute path name of the file. This argument cannot be NULL.
SQLSMALLINT *	FileNameLength	input (deferred)	Pointer to the location that contains the length of the file name (or an array of lengths) at the time of the next `SQLExec()` or `SQLExecDirect()` using StatementHandle. If this pointer is NULL, ODBC treats FileName as a null-terminated string. The result is the same as if a length of SQL_NTS is passed. The maximum value of the file name length is 255.
SQLUINTEGER *	FileOptions	input (deferred)	Pointer to the location that contains the file option (or an array of file options) to be used when the file is read. The location is accessed when the statement (StatementHandle) is executed. Only one option is supported, and it must be specified: SQL_FILE_READ A regular file that can be opened, read, and closed. The length is computed when the file is opened. This pointer cannot be NULL.
SQLSMALLINT	MaxFileNameLength	input	The length of the FileName buffer. If the application calls `SQLSetStmtAttr()` to specify multiple values for each parameter, this is the length of each element in the FileName array.
SQLINTEGER *	IndicatorValue	input (deferred)	The pointer to the location that contains an indicator value or array of values, which are set to SQL_NULL_DATA if the LOB data value is to be null. The value at the location must be set to 0 or the pointer must be set to null when the data value is not null.

Usage

The LOB file reference arguments (file name, file name length, file reference options) refer to a file within the application's environment (on the client). Before calling SQLExecute() or SQLExecDirect(), the application must ensure that this information is available in the deferred input buffers. These values can be changed between SQLExecute() calls.

The application calls SQLBindFileToParam() once for each parameter marker whose valueis obtained directly from a file when a statement is executed. Before the statement is executed, the FileName, FileNameLength, and FileOptions values must be set. When the statement is executed, the data for any parameter that has been bound using SQLBindFileToParam() is read from the referenced file and passed to the server.

If the application uses SQLSetStmtAttr() to specify multiple values for each parameter, FileName, FileNameLength, and FileOptions point to an array of LOB file reference variables. In this case, MaxFileNameLength specifies the length of each element in the FileName array and is used by Db2 ODBC to determine the location of each element in the FileName array.

A LOB parameter marker can be associated with an input file using SQLBindFileToParam(), or with a stored buffer using SQLBindParameter(). The most recent bind parameter function call determines the type of binding that is in effect.

Return codes

After you call SQLBindFileToParam(), it returns one of the following values:

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. SQLBindFileToParam SQLSTATEs
SQLSTATE	Description	Explanation
08S01	Communication link failure.	The communication link between the application and data source fails before the function completes.
58004	Unexpected system failure.	Unrecoverable system error.
HY001	Memory allocation failure.	Db2 ODBC is unable to allocate the memory that is required to support execution or completion of the function.
HY004	SQL data type out of range.	The value specified for DataType was not a valid SQL type for this function call.
HY009	Invalid argument value.	FileName or FileOptions is a null pointer.
HY010	Function sequence error.	The function was called while in a data-at-execute (`SQLParamdata()`, `SQLPutData()`) operation. The function was called while within a BEGIN COMPOUND and END COMPOUND SQL operation.
HY013	Unexpected memory handling error.	Db2 ODBC was unable to access memory that is required to support execution or completion of the function.
HY090	Invalid string or buffer length.	The value specified for the input argument MaxFileNameLength was less than 0.
HY093	Invalid parameter number.	The value specified for TargetType was less than 1.
HYC00	Driver not capable.	Db2 ODBC does not support "catalog" as a qualifier for table name.

Example

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