SQLGetPosition - Return starting position of string
SQLGetPosition()
is
used to return the starting position of one string within a LOB value
(the source). The source value must be a LOB locator; the search string
can be a LOB locator or a literal string.
The source
and search LOB locators can be any that have been returned from the
database from a fetch or an SQLGetSubString()
call
during the current transaction.
Syntax
SQLRETURN SQLGetPosition (SQLHSTMT StatementHandle,
SQLSMALLINT LocatorCType,
SQLINTEGER SourceLocator,
SQLINTEGER SearchLocator,
SQLCHAR *SearchLiteral,
SQLINTEGER SearchLiteralLength,
SQLINTEGER FromPosition,
SQLINTEGER *LocatedAt,
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. |
SQLINTEGER | SearchLocator | Input | If the SearchLiteral pointer is NULL and if SearchLiteralLength is set to 0, then SearchLocator must be set to the LOB locator associated with the search string; otherwise, this argument is ignored. The lob locator type for the SearchLocator must be the same as the locator type used by the SourceLocator. This locator type is set for argument LocatorCType. |
SQLCHAR * | SearchLiteral | Input | This argument points to the area
of storage that contains the search string literal. If SearchLiteralLength is 0, this pointer must be NULL. If the LocatorCType is set to SQL_C_DBCLOB_LOCATOR, and the call to SQLGetPositionW was made, then the string literal is assumed to be double byte data. If a call to the non Wide API was made, then this string literal is assumed to be single byte data |
SQLINTEGER | SearchLiteralLength | Input | The length of the string in SearchLiteral(in
bytes).1 If this argument value is 0, then the argument SearchLocator is meaningful. |
SQLINTEGER | FromPosition | Input | For BLOBs and CLOBs, this is the position of the first byte within the source string at which the search is to start. to be returned by the function. For DBCLOBs, this is the first character. The start byte or character is numbered 1. |
SQLINTEGER * | LocatedAt | Output | For BLOBs and CLOBs, this is the byte position
at which the string is located or, if not located, the value zero.
For DBCLOBs, this is the character position. If the length of the source string is zero, the value 1 is returned. |
SQLINTEGER * | IndicatorValue | Output | Always set to zero. |
1. This is in double byte characters for a call to the SQLGetPositionW API, but in bytes for a call to the SQLGetPosition API for DBCLOB data. |
Usage
SQLGetPosition()
is
used in conjunction with SQLGetSubString()
in order
to obtain any portion of a string in a random manner. In order to
use SQLGetSubString()
, the location of the substring
within the overall string must be known in advance. In situations
where the start of that substring can be found by a search string, SQLGetPosition()
can
be used to obtain the starting position of that substring.
The Locator and SearchLocator (if used) arguments can contain any valid LOB locator which has not been explicitly freed using a FREE LOCATOR statement or implicitly freed because the transaction during which it is created has terminated.
The Locator and SearchLocator must have the same LOB locator type.
The statement handle must not have been associated with any prepared statements or catalog function calls.
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
Error conditions
SQLSTATE | Description | Explanation |
---|---|---|
07006 | Conversion that is not valid | The combination of the LocatorCType argument and either of the LOB locator values is not valid. |
0F001 | LOB variable that is not valid | The value specified for argument Locator or SearchLocator is not currently a LOB locator. |
22522 | CCSID not valid. | The specified LocatorCType argument does not match the actual LOB type of the input locator. |
42818 | Length that is not valid | The length of the pattern is too long. |
58004 | Unexpected system failure | Unrecoverable system error. |
HY009 | Argument value that is not valid | The argument LocatedAt or IndicatorValue is
a null pointer. The argument value for FromPosition is not greater than 0. LocatorCType is not one of SQL_C_CLOB_LOCATOR, SQL_C_BLOB_LOCATOR, or SQL_C_DBCLOB_LOCATOR. |
HY010 | Function sequence error | The specified StatementHandle argument 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 SearchLiteralLength is less than 1, and not SQL_NTS. |
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.