SQLGetLength - Retrieve length of a string value
SQLGetLength() is used to retrieve the length of a large object value referenced by a large object locator. The large object locator has been returned from the data source (as a result of a fetch or an SQLGetSubString() call) during the current transaction.
Syntax
SQLRETURN SQLGetLength (SQLHSTMT StatementHandle,
SQLSMALLINT LocatorCType,
SQLINTEGER Locator,
SQLINTEGER *StringLength,
SQLINTEGER *IndicatorValue);
Function arguments
Data type | Argument | Use | Description |
---|---|---|---|
SQLHSTMT | StatementHandle | Input | Statement handle. This can be any statement handle which has been allocated but which does not currently have a prepared statement assigned to it. |
SQLSMALLINT | LocatorCType | Input | The C type
of the source LOB locator.
|
SQLINTEGER | Locator | Input | Must be set to the LOB locator value. |
SQLINTEGER * | StringLength | Output | The length of
the specified locator.1 If the pointer is set to NULL then the SQLSTATE HY009 is returned. |
SQLINTEGER * | IndicatorValue | Output | Always set to zero. |
1. This is in bytes even for DBCLOB data. |
Usage
SQLGetLength() can be used to determine the length of the data value represented by a LOB locator. It is used by applications to determine the overall length of the referenced LOB value so that the appropriate strategy to obtain some or all of the LOB value can be chosen.
The Locator argument can contain any valid LOB locator which has not been explicitly freed using a FREE LOCATOR statement nor implicitly freed because the transaction during which it is created has terminated.
The statement handle must not have been associated with any prepared statements or catalog function calls.
DB2® for i restricts the use of LOB locators when running with no isolation level.
Return codes
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
Error conditions
SQLSTATE | Description | Explanation |
---|---|---|
07006 | Conversion that is not valid | The combination of the argumentLocatorCType and Locator is not valid. |
0F001 | LOB variable that is not valid | The value specified for the argument Locator has not been associated with a LOB locator. |
58004 | Unexpected system failure | Unrecoverable system error. |
HY003 | Program type out of range | The argument LocatorCType is not one of SQL_C_CLOB_LOCATOR, SQL_C_BLOB_LOCATOR, or SQL_C_DBCLOB_LOCATOR. |
HY009 | Argument value that is not valid | The argument StringLength or IndicatorValue is a null pointer. |
HY010 | Function sequence error | The specified argument StatementHandle is not in an allocated state. |
HY021 | Internal descriptor that is not valid | The internal descriptor cannot be addressed or allocated, or it contains a value that is not valid. |
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 a DB2 server that does not support Large Objects.