SQLGetLength() - Retrieve length of a string value

SQLGetLength() retrieves the length (in bytes) of a large object value. The large object value is referenced by a large object locator that the server returns. The locator can be the result of a fetch, or an SQLGetSubString() call during the current transaction.

ODBC specifications for SQLGetLength()

Table 1. SQLGetLength() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
No No No

Syntax

SQLRETURN  SQLGetLength      (SQLHSTMT          hstmt,
                              SQLSMALLINT       LocatorCType,
                              SQLINTEGER        Locator,
                              SQLINTEGER  FAR   *StringLength,
                              SQLINTEGER  FAR   *IndicatorValue);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. SQLGetLength() arguments
Data type Argument Use Description
SQLHSTMT hstmt input Specifies a statement handle. This can be any statement handle that is allocated but does not currently have a prepared statement assigned to it.
SQLSMALLINT LocatorCType input Specifies the C type of the source LOB locator. This must be one of the following values:
  • SQL_C_BLOB_LOCATOR for BLOB data
  • SQL_C_CLOB_LOCATOR for CLOB data
  • SQL_C_DBCLOB_LOCATOR for DBCLOB data
SQLINTEGER Locator input Specifies the LOB locator value. This argument specifies a LOB locator value not the LOB value itself.
SQLINTEGER * StringLength output Points to a buffer that receives the length (in bytes1) of the LOB to which the locator argument refers.
SQLINTEGER * IndicatorValue output This argument is always returns zero.
Note:
  1. This is in bytes even for DBCLOB data.

Usage

SQLGetLength() can determine the length of the data value represented by a LOB locator. Applications use it to determine the overall length of the referenced LOB value so that the appropriate strategy for obtaining some or all of that value can be chosen.

The Locator argument can contain any valid LOB locator that is not explicitly freed using a FREE LOCATOR statement and that is not implicitly freed because the transaction during which it was created has terminated.

The statement handle must not be associated with any prepared statements or catalog function calls.

Return codes

After you call SQLGetLength(), it returns one of the following values:
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

40
Table 3. SQLGetLength() SQLSTATEs
SQLSTATE Description Explanation
07006 Invalid conversion. The combination of the values that the LocatorCType and Locator arguments specify is not valid.
08S01 Communication link failure. The communication link between the application and data source fails before the function completes.
0F001 The LOB token variable does not currently represent any value. The value that the Locator argument specifies is not associated with a LOB locator.
58004 Unexpected system failure. Unrecoverable system error.
HY001 Memory allocation failure. Db2 ODBC is not able to allocate the required memory to support the execution or the completion of the function.
HY003 Program type out of range. The LocatorCType argument does not specify one of the following values:
  • SQL_C_CLOB_LOCATOR
  • SQL_C_BLOB_LOCATOR
  • SQL_C_DBCLOB_LOCATOR
HY009 Invalid use of a null pointer. The StringLength argument specifies a null pointer.
HY013 Unexpected memory handling error. Db2 ODBC is not able to access the memory that is required to support execution or completion of the function.
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 you connect to a Db2 server that does not support large objects. Call SQLGetFunctions() with the fFunction argument set to SQL_API_SQLGETLENGTH and check the fExists output argument to determine if the function is supported for the current connection.

Example

Refer to the function SQLGetPosition() for a related example.