SQLBindFileToParam - Bind LOB file reference to LOB parameter

SQLBindFileToParam() is used to associate (bind) a parameter marker in an SQL statement to a file reference or an array of file references. In this way, data from the file can be transferred directly into a LOB column when that statement is subsequently processed.

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 make sure that this information is available in the deferred input buffers. These values can be changed between SQLExecute() calls.

Syntax

SQLRETURN SQLBindFileToParam (SQLHSTMT          StatementHandle,   
                              SQLSMALLINT       ParameterNumber,   
                              SQLSMALLINT       DataType,        
                              SQLCHAR           *FileName,
                              SQLSMALLINT       *FileNameLength,
                              SQLINTEGER        *FileOptions,
                              SQLSMALLINT       MaxFileNameLength,
                              SQLINTEGER        *IndicatorValue);

Function arguments

Table 1. SQLBindFileToParam arguments
Data type	Argument	Use	Description
SQLHSTMT	StatementHandle	Input	Statement handle.
SQLSMALLINT	ParameterNumber	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: 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 processed. This is either the complete path name of the file or a relative file name. If a relative file name is provided, it is appended to the current path of the client process. 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 the next `SQLExecute()` or `SQLExecDirect()` function is run using the StatementHandle. If this pointer is NULL, then a length of SQL_NTS is assumed. The maximum value of the file name length is 255.
SQLINTEGER *	FileOptions	Input (deferred)	Pointer to the location that contains the file option (or an array of file options) to be used when reading the file. The location is accessed when the statement (StatementHandle) is processed. 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	This specifies the length of the FileName buffer. If the application calls `SQLParamOptions()` to specify multiple values for each parameter, this is the length of each element in the FileName array.
SQLINTEGER *	IndicatorValue	Input (deferred), output (deferred)	Pointer to the location that contains an indicator value (or array of values), which is set to SQL_NULL_DATA if the data value of the parameter is to be null. It must be set to 0 (or the pointer can be set to null) when the data value is not null.

Usage

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

A LOB parameter marker can be associated with (bound to) 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

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Error conditions

Table 2. SQLBindFileToParam SQLSTATEs
SQLSTATE	Description	Explanation
58004	Unexpected system failure	Unrecoverable system error.
HY004	SQL data type out of range	The value specified for DataType is not a valid SQL type for this function call.
HY009	Argument value that is not valid	FileName, FileOptions, or FileNameLength is a null pointer.
HY010	Function sequence error	The function is called while in a data-at-processing (`SQLParamData()`or `SQLPutData()`) operation. The function is called while within a BEGIN COMPOUND and END COMPOUND SQL operation.
HY021	Internal descriptor that is not valid	The internal descriptor cannot be addressed or allocated, or it contains a value that is not valid.
HY090	String or buffer length that is not valid	The value specified for the input argument MaxFileNameLength is less than 0.
HY093	Parameter number that is not valid	The value specified for ParameterNumber is either less than 1 or greater than the maximum number of parameters supported.
HYC00	Driver not capable	The data source does not support large object data types.

Restrictions

This function is not available when the application is connected to DB2® servers that do not support large object data types.