SQLGetPosition

Purpose

SQLGetPosition() is used to return the starting position of one string within an LOB value (the source). The source value must be an LOB locator, the search string can be an 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 a 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

Table 1. SQLGetPosition arguments
Data type	Argument	Use	Description
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.
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 *	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	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	SearchLiteralLength	Input	The length of the string in SearchLiteral(in bytes).¹ If this argument value is 0, then the argument SearchLocator is meaningful.
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.
SQLINTEGER	SourceLocator	Input	SourceLocator must be set to the source LOB locator.
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
1. This is in bytes even 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.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_STILL_EXECUTING
SQL_ERROR
SQL_INVALID_HANDLE

Error conditions

Table 2. SQLGetPosition SQLSTATEs
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 an LOB 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.

SQLGetPosition - Return starting position of string