SQLBindFileToCol - Bind LOB file reference to LOB column

Purpose

SQLBindFileToCol() is used to associate (bind) an LOB column in a result set to a file reference or an array of file references. This enables data in that column to be transferred directly into a file when each row is fetched for the statement handle.

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 fetching each row, the application must make sure that these variables contain the name of a file, the length of the file name, and a file option (new / overwrite / append). These values can be changed between each fetch.

Syntax

SQLRETURN   SQLBindFileToCol (SQLHSTMT          StatementHandle,
                              SQLSMALLINT       ColumnNumber,
                              SQLCHAR           *FileName,
                              SQLSMALLINT       *FileNameLength,
                              SQLINTEGER        *FileOptions,
                              SQLSMALLINT       MaxFileNameLength,
                              SQLINTEGER        *StringLength,
                              SQLINTEGER        *IndicatorValue);

Function arguments

Table 1. SQLBindFileToCol arguments
Data type	Argument	Use	Description
SQLCHAR *	FileName	Input (deferred)	Pointer to the location that contains the file name or an array of file names at the time of the next fetch using the StatementHandle. This is either the complete path name of the file(s) or a relative file name(s). If relative file name(s) are provided, they are appended to the current path of the running application. This pointer cannot be NULL.
SQLHSTMT	StatementHandle	Input	Statement handle.
SQLINTEGER *	FileOptions	Input (deferred)	Pointer to the location that contains the file option to be used when writing the file at the time of the next fetch using the StatementHandle. The following FileOptions are supported: SQL_FILE_CREATE Create a new file. If a file by this name already exists, SQL_ERROR is returned. SQL_FILE_OVERWRITE If the file already exists, overwrite it. Otherwise, create a new file. SQL_FILE_APPEND If the file already exists, append the data to it. Otherwise, create a new file. Only one option can be chosen per file, there is no default.
SQLINTEGER *	IndicatorValue	Output (deferred)	Pointer to the location that contains an indicator value.
SQLINTEGER *	StringLength	Output (deferred)	Pointer to the location that contains the length in bytes of the LOB data that is returned. If this pointer is NULL, nothing is returned.
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 fetch 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.
SQLSMALLINT	ColumnNumber	Input	Number identifying the column. Columns are numbered sequentially, from left to right, starting at 1.
SQLSMALLINT	MaxFileNameLength	Input	This specifies the length of the FileName buffer.

Usage

The application calls SQLBindFileToCol() once for each column that should be transferred directly to a file when a row is fetched. LOB data is written directly to the file without any data conversion, and without appending null-terminators.

FileName, FileNameLength, and FileOptions must be set before each fetch. When SQLFetch() or SQLFetchScroll() is called, the data for any column which has been bound to an LOB file reference is written to the file or files pointed to by that file reference. Errors associated with the deferred input argument values of SQLBindFileToCol() are reported at fetch time. The LOB file reference, and the deferred StringLength and IndicatorValue output arguments are updated between fetch operations.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Error conditions

Table 2. SQLBindFileToCol SQLSTATEs
SQLSTATE	Description	Explanation
58004	Unexpected system failure	Unrecoverable system error.
HY002	Column number that is not valid	The value specified for the argument icol is less than 1. The value specified for the argument icol exceeded the maximum number of columns supported by the data source.
HY009	Argument value that is not valid	FileName, StringLength, or FileOptions is a null pointer.
HY010	Function sequence error	The function is called while in a data-at-processing (`SQLParamData()`, `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 argument MaxFileNameLength is less than 0.
HYC00	Driver not capable	The application is currently connected to a data source that does not support large objects.

Restrictions

This function is not available when connected to DB2^® servers that do not support Large Object data types.