SQLGetLength

Purpose

SQLGetLength() is used to retrieve the length of a large object value, referenced by a large object locator that has been returned from the server (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

Table 1. SQLGetLength 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.
SQLINTEGER *	IndicatorValue	Output	Always set to zero.
SQLINTEGER *	StringLength	Output	The length of the specified locator.¹ If the pointer is set to NULL then the SQLSTATE HY009 is returned.
SQLINTEGER	Locator	Input	Must be set to the LOB locator value.
SQLSMALLINT	LocatorCType	Input	The C type of the source LOB locator. SQL_C_BLOB_LOCATOR SQL_C_CLOB_LOCATOR SQL_C_DBCLOB_LOCATOR
1. This is in bytes even for DBCLOB data.

Usage

SQLGetLength() can be used to determine the length of the data value represented by an 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.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_STILL_EXECUTING
SQL_ERROR
SQL_INVALID_HANDLE

Error conditions

Table 2. SQLGetLength SQLSTATEs
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 an 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.

SQLGetLength - Retrieve length of a string value