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:

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:

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:

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:

This function has the following parameters: