SQLGetSubString

Purpose

SQLGetSubString() is used to retrieve a portion of a large object value, referenced by a large object locator that has been returned from the server (returned by a fetch or a previous SQLGetSubString() call) during the current transaction.

Syntax

SQLRETURN  SQLGetSubString   (
                SQLHSTMT          StatementHandle,
                SQLSMALLINT       LocatorCType,
                SQLINTEGER        SourceLocator,
                SQLINTEGER        FromPosition,
                SQLINTEGER        ForLength,
                SQLSMALLINT       TargetCType,
                SQLPOINTER        DataPtr, 
                SQLINTEGER        BufferLength,
                SQLINTEGER        *StringLength,
                SQLINTEGER        *IndicatorValue);

Function arguments

Table 1. SQLGetSubString 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 returned information in DataPtr in bytes^a 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, nothing is returned.
SQLINTEGER	BufferLength	input	Maximum size of the buffer pointed to by DataPtr in bytes.
SQLINTEGER	ForLength	input	This is the length of the string to be returned by the function. For BLOBs and CLOBs, this is the length in bytes. For DBCLOBs, this is the length in characters. If FromPosition is less than the length of the source string but FromPosition + ForLength - 1 extends beyond the end of the source string, the result is padded on the right with the necessary number of characters (X'00' for BLOBs, single byte blank character for CLOBs, and double byte blank character for DBCLOBs).
SQLINTEGER	FromPosition	input	For BLOBs and CLOBs, this is the position of the first byte to be returned by the function. For DBCLOBs, this is the first character. The start byte or character is numbered 1.
SQLINTEGER	SourceLocator	input	SourceLocator must be set to the source LOB locator value.
SQLPOINTER	DataPtr	output	Pointer to the buffer where the retrieved string value or an LOB locator is to be stored.
SQLSMALLINT	LocatorCType	input	The C type of the source LOB locator. This can be: SQL_C_BLOB_LOCATOR SQL_C_CLOB_LOCATOR SQL_C_DBCLOB_LOCATOR
SQLSMALLINT	TargetCType	input	The C data type of the DataPtr. The target must be a C string variable (SQL_C_CHAR, SQL_C_WCHAR, SQL_C_BINARY, or SQL_C_DBCHAR).
Note: 1. This is in bytes even for DBCLOB data.

Usage

SQLGetSubString() is used to obtain any portion of the string that is represented by the LOB locator. There are two choices for the target:

The target can be an appropriate C string variable.
A new LOB value can be created on the server and the LOB locator for that value can be assigned to a target application variable on the client.

SQLGetSubString() can be used as an alternative to SQLGetData() for getting data in pieces. In this case a column is first bound to an LOB locator, which is then used to fetch the LOB as a whole or in pieces.

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. SQLGetSubString SQLSTATEs
SQLSTATE	Description	Explanation
01004	Data truncated	The amount of data to be returned is longer than BufferLength. Actual length available for return is stored in StringLength.
07006	Conversion that is not valid	The value specified for TargetCType is not SQL_C_CHAR, SQL_C_BINARY, SQL_C_DBCHAR, or an LOB locator. The value specified for TargetCType is inappropriate for the source (for example SQL_C_DBCHAR for a BLOB column).
22011	Substring error occurred	FromPosition is greater than the length of the source string.
58004	Unexpected system failure	Unrecoverable system error.
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	Argument value that is not valid	The value specified for FromPosition or ForLength is not a positive integer. The argument DataPtr, StringLength, or IndicatorValue is a null pointer
HY010	Function sequence error	The specified 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.
HY090	String or buffer length that is not valid	The value of BufferLength is less than 0.
HYC00	Driver not capable	The application is currently connected to a data source that does not support large objects.
0F001	No locator currently assigned	The value specified for Locator is not currently an LOB locator.

Restrictions

This function is not available when connected to a DB2^® server that does not support Large Objects.

SQLGetSubString - Retrieve portion of a string value