OpenAPI User Guide > OpenAPI User Guide > OpenAPI Function Reference > OpenAPI Functions > IIapi_getColumns() Function--Return Columns from a Previously Invoked Query Statement or Database Event Retrieval
Was this helpful?
IIapi_getColumns() Function--Return Columns from a Previously Invoked Query Statement or Database Event Retrieval
The IIapi_getColumns() function returns the results of a query statement or database event retrieval created by IIapi_query() or IIapi_catchEvent() to the application. It retrieves into the application's buffers the requested number of columns of data.
This function is always preceded with the IIapi_getDescriptor() or IIapi_getCopyMap() function, which describes the number, order and format of columns to be returned to the application from the server.
IIapi_getColumns() assumes the application has allocated sufficient storage for each column. The buffer size of each column should be equal to the ds_length parameter of its corresponding descriptor from IIapi_getCopyMap() or IIapi_getDescriptor().
IIapi_getColumns() can return multiple rows. If there are long varchar, nvarchar, or byte data columns, IIapi_getColumns() returns only one row at a time.
If one of the columns is a long varchar, nvarchar, or byte that requires more than one segment to be returned, the application requests the segments individually with single calls to IIapi_getColumns(). For example, a row of ten columns with a long varchar, nvarchar, or byte spanning multiple segments as the fifth column is handled as follows. The application:
1. Requests four columns with a call to IIapi_getColumns().
2. Requests one segment of the long varchar, nvarchar, or byte column with a call to IIapi_getColumns().
3. Continues making requests until all segments are retrieved.
4. Requests five columns with a call to IIapi_getColumns() to retrieve the rest of the columns in the current row.
Generally, the application calls IIapi_getColumns() repeatedly until a request completes with the status IIAPI_ST_NO_DATA. A request that returns fewer rows than requested is also an indication that the query is complete. For non-cursor based queries, no other request may be issued until the query completes. Once complete, additional query status information may be obtained by calling IIapi_getQueryInfo(). The statement handle should be freed with the IIapi_close() function.
For cursor based queries (IIAPI_QT_OPEN), each IIapi_getColumns() call results in a FETCH request being issued against the cursor. Since the query is effectively suspended in between FETCH requests, the application is permitted to issue other requests in between calls to IIapi_getColumns(). The application can also call IIapi_getQueryInfo() after each IIapi_getColumns() call to obtain information about the individual FETCH requests. IIapi_getQueryInfo() can also be called between IIapi_getDescriptor() and the first call to IIapi_getColumns() to determine the status of the cursor OPEN request.
IIapi_getColumns() can be preceded by a call to IIapi_position() or IIapi_scroll() when the associated cursor is scrollable. IIapi_position() and IIapi_scroll() initiate a positioned FETCH request. We recommend that the results of these functions be retrieved in a single call to IIapi_getColumns() by requesting the same number of rows as requested for IIapi_position() or implied by IIapi_scroll(). It is possible, however, to retrieve the results using multiple calls to IIapi_getColumns(). As with non-cursor based queries, IIapi_getColumns() should be called repeatedly until one of the following occurs:
The total number of rows returned by the combined IIapi_getColumns() calls equals the number of rows requested or implied by the positioned FETCH.
IIapi_getColumns() returns fewer rows than requested.
IIapi_getColumns() returns IIAPI_ST_NO_DATA.
When one of the conditions listed above occurs, IIapi_getQueryInfo() can be called to retrieve additional results of the positioned FETCH request. If IIapi_getQueryInfo() is called prior to one of these conditions, any remaining results will be discarded.
With scrollable cursors, an IIAPI_ST_NO_DATA result or returning fewer rows than requested does not indicate query completion as it does for non-scrollable cursors and non-cursor queries. IIAPI_ST_NO_DATA or fewer rows than requested will be returned if one of the following occurs:
Fewer rows (including 0 rows) were requested by the preceding call to IIapi_position() or IIapi_scroll().
The cursor is positioned before the first row of the result set.
The cursor reaches a row that has been deleted.
The cursor reaches the end of the result set.
IIapi_getColumns() returns columns sequentially in the order that they appear in the row, as described in IIapi_getCopyMap() and IIapi_getDescriptor(). When IIAPI_ST_NO_DATA is returned, the application should free the statement handle with the IIapi_close() function.
IIapi_getColumns() assumes the application has allocated sufficient storage for each column. The buffer size of each column should be equal to the ds_length parameter of its corresponding descriptor from IIapi_getCopyMap() or IIapi_getDescriptor().
This function has the following syntax:
II_VOID IIapi_getColumns (IIAPI_GETCOLPARM *getColParm);
typedef struct _IIAPI_GETCOLPARM
{
      IIAPI_GENPARM gc_genParm;
      II_PTR               gc_stmtHandle;
      II_INT               gc_rowCount;
      II_INT               gc_columnCount;
      IIAPI_DATAVALUE      *gc_columnData;
      II_INT               gc_rowsReturned
      II_BOOL              gc_moreSegments;
} IIAPI_GETCOLPARM;
This function has the following parameters:
gc_genParm
Type: input and delayed output
Specifies the generic parameters. For a description, see Generic Parameters).
gc_stmtHandle
Type: input
Specifies the statement handle identifying the query or event handle identifying the database event.
gc_rowCount
Type: input
Specifies the number of rows to fetch. This parameter must be 1 if the query contains any long varchar or long byte values.
gc_columnCount
Type: input
Specifies the number of columns to retrieve. This parameter must contain a non-zero positive integer, and it cannot exceed the total number of columns in a row.
gc_columnData
Type: delayed output
Specifies an array of buffers. The number of buffers in this array must equal gc_rowCount * gc_columnCount. The first gc_columnCount buffers receive the columns from the first row. The second row follows immediately after the first. Each buffer must have enough allocated memory to store the value of a column in the order specified by the descriptors returned from IIapi_getDescriptor() or IIapi_getCopyMap().
gc_rowsReturned
Type: delayed output
Specifies the number of rows actually returned in gc_columnData.
gc_moreSegments
Type: delayed output
Indicates whether there is more data to be retrieved for a column of a long varchar or long byte data type. This parameter is set to TRUE if the data type is long varchar or long byte and more data must be retrieved for the current column; otherwise, the parameter is set to FALSE.
Last modified date: 08/28/2024