| Specification: | DB2 CLI 2.1 |
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, /* hstmt */
SQLSMALLINT LocatorCType,
SQLINTEGER Locator,
SQLINTEGER FAR *StringLength,
SQLINTEGER FAR *IndicatorValue);
Function Arguments
Table 113. 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. | ||
| SQLSMALLINT | LocatorCType | input | The C type of the source LOB locator. This may be:
| ||
| SQLINTEGER | Locator | input | Must be set to the LOB locator value. | ||
| SQLINTEGER * | StringLength | output | The length of the returned information in rgbValue in
bytesa if the target C buffer type is intended for a binary or
character string variable and not a locator value.
If the pointer is set to NULL then the SQLSTATE HY009 is returned. | ||
| SQLINTEGER * | IndicatorValue | output | Always set to zero. | ||
| |||||
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 was created has terminated.
The statement handle must not have been associated with any prepared statements or catalog function calls.
Return Codes
Diagnostics
Table 114. SQLGetLength SQLSTATEs
| SQLSTATE | Description | Explanation |
|---|---|---|
| 07006 | Invalid conversion. | The combination of LocatorCType and Locator is not valid. |
| 40003 08S01 | Communication link failure. |
|
| 58004 | Unexpected system failure. | Unrecoverable system error. |
| HY001 | Memory allocation failure. | DB2 CLI is unable to allocate memory required to support execution or completion of the function. |
| HY003 | Program type out of range. | LocatorCType is not one of SQL_C_CLOB_LOCATOR, SQL_C_BLOB_LOCATOR, or SQL_C_DBCLOB_LOCATOR. |
| HY009 | Invalid argument value. | Pointer to StringLength was NULL. |
| HY010 | Function sequence error. | The specified StatementHandle is not in an allocated
state.
The function was called while in a data-at-execute (SQLParamData(), SQLPutData()) operation. The function was called while within a BEGIN COMPOUND and END COMPOUND SQL operation. An asynchronously executing function (not this one) was called for the StatementHandle and was still executing when this function was called. |
| HY013 | Unexpected memory handling error. | DB2 CLI was unable to access memory 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. |
| 0F001 | The LOB token variable does not currently represent any value. | The value specified for Locator has not been associated with a LOB locator. |
Restrictions
This function is not available when connected to a DB2 server that does not support Large Objects. Call SQLGetFunctions() with the function type set to SQL_API_SQLGETLENGTH and check the fExists output argument to determine if the function is supported for the current connection.
(The complete sample dtlob.c is also available here .)
/* From the CLI sample dtlob.c */
/* ... */
/* get the length of the whole CLOB data */
sqlrc = SQLGetLength( hstmtLocUse, SQL_C_CLOB_LOCATOR,
clobLoc, &clobLen, &ind ) ;
STMT_HANDLE_CHECK( hstmtLocUse, sqlrc);
References