SQLGetSubString - Retrieve portion of a string value
SQLGetSubString()
is used to retrieve
a portion of a large object value referenced by a large object locator.
The large object locator has been returned from the data source (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
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 can
be:
|
SQLINTEGER | SourceLocator | input | SourceLocator must be set to the source LOB locator value. |
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 | 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). |
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). |
SQLPOINTER | DataPtr | output | Pointer to the buffer where the retrieved string value or a LOB locator is to be stored. |
SQLINTEGER | BufferLength | input | Maximum size of the buffer pointed to by DataPtr in bytes. |
SQLINTEGER * | StringLength | output | The length of the returned information in DataPtr 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, nothing is returned. |
SQLINTEGER * | IndicatorValue | output | Always set to zero. |
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 a 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.
If a locator
entry exists in the locator table but has no data, SQLGetSubString()
will
return an SQL_NO_DATA return code.
If a remote connection has been made, the CCSID of the CLOB data (SourceLocator) must be compatible with the CCSID of the job executing the SQLGetSubString API, otherwise translation problems will occur.
Return codes
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
- SQL_NO_DATA
Error conditions
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 a 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 a LOB locator. |
Restrictions
This function is not available when connected to a DB2 server that does not support Large Objects.