SQLBindFileToCol - Bind LOB file reference to LOB column
SQLBindFileToCol()
is used to associate
(bind) a LOB column in a result set to a file reference or an array
of file references. In this way, data in the LOB column can 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
Data type | Argument | Use | Description |
---|---|---|---|
SQLHSTMT | StatementHandle | Input | Statement handle. |
SQLSMALLINT | ColumnNumber | Input | Number identifying the column. Columns are numbered sequentially, from left to right, starting at 1. |
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. |
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. |
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:
Only one option can be chosen per file, there is no default. |
SQLSMALLINT | MaxFileNameLength | Input | This specifies the length of the FileName buffer. |
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. |
SQLINTEGER * | IndicatorValue | Output (deferred) | Pointer to the location that contains an indicator value. |
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 a 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
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.