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().