How Unformatted Data is Handled
Long varchar and long byte data types are binary large objects (sometimes called BLOBs) that can store up to 2 GB of data. Since it is often impossible to allocate a storage buffer of this size, special handling is required to segment the unformatted data across the OpenAPI interface. This is done with the IIapi_getColumns(), IIapi_putColumns(), and IIapi_putParms() functions.
Each of these functions contain three common parameters:
parmCount or columnCount
Contain the number of parameters being sent or columns being retrieved in an SQL statement.
parmData or columnData
Contain the buffers of data being sent or retrieved.
moreSegments
Indicates if there are more data segments to be sent or retrieved for a column of long varchar or long byte data type.
Data passes between the application and OpenAPI in a row. Normally, all data in a row or all parameters in an SQL statement are passed with one call to IIapi_getColumns(), IIapi_putColumns(), or IIapi_putParms(). If one of the columns is a long varchar or long byte, however, each segment of the long varchar or long byte must be passed with a single call to the above functions. The moreSegments parameter (which is set to TRUE or FALSE) indicates whether the long varchar or long byte data is completely retrieved or sent. After it is retrieved or sent, the rest of the data, up to the next long varchar or long byte, is passed with one function call.
Example—passing unformatted data
An application calls IIapi_getColumns() to retrieve a row of ten columns in a table. The fifth column is a long varchar data type spanning multiple segments. To retrieve the data, the application does the following:
1. Requests the first four columns with a call to IIapi_getColumns().
2. Requests one segment of the long varchar column with a call to IIapi_getColumns().
3. Continues calling IIapi_getColumns() until all segments of the long varchar are retrieved (gc_moreSegments is FALSE).
4. Requests the remaining five columns with a call to IIapi_getColumns().
The same logic is used when an application is sending data to a server with IIapi_putParms() or IIapi_putColumns().
LOB Locators
Rather than retrieving long data along with other query data, an application can request a reference to the long data, called a locator, by setting the IIAPI_QF_LOCATOR flag when calling IIapi_query(). Locators are 4-byte integer values that reference the long data where it resides in the database. A locator value is only valid on the connection and during the transaction in which it is received.
A locator may be used to retrieve the referenced data by issuing the following query:
select ~V
The locator value is provided as a query parameter using IIapi_setDescriptor() and IIapi_putParams(). (See Query Parameters for details on ~V parameter markers.) To ensure the long data is returned, the IIAPI_QF_LOCATOR flag should not be set for this query. The long data is then received and processed in segments as described above.
In addition to retrieving the referenced long data, locators can also be used to operate on the long data as it resides in the database. A ~V query marker and locator query parameter can be used in SQL statements in places where long data references are permitted. In particular, the following statements provide access to long data while it resides in the database:
select length( ~V )
select substring( ~V from start for length )
select position( pattern, ~V , start )
Last modified date: 08/28/2024