Accessing Result Rows

After dbresults has returned SUCCEED and any binding of columns to variables has been specified, the application is ready to process the results. The first step is to make the result rows available to the application. The dbnextrow function accomplishes this. Each call to dbnextrow reads the next row returned from Microsoft® SQL Server™ 2000. The row is read directly from the network. As an alternative, you can do the same thing through cursors, often more simply and with more power. For details, see Bulk-Copy Functions.

After a row has been read in by dbnextrow, the application can perform any processing desired on the data in the row. If the result columns have been bound to program variables, the data in the row will have been automatically copied into the variables. Alternatively, the data is accessible through dbdata or dbadata.

Rows read in by dbnextrow can be automatically saved in a row buffer, if desired. This is accomplished by setting the DBBUFFER option. Without row buffering, each row must be processed as it is read in by dbnextrow because the next call to dbnextrow will overwrite the previously read row. If row buffering has been turned on, the rows are added to a row buffer as they are read in by dbnextrow. Row buffering allows the application to skip around in the buffer and return to previously read rows.

After all result rows have been returned, the final call to dbnextrow returns the NO_MORE_ROWS indication. You must continue calling dbnextrow until it returns NO_MORE_ROWS, even if you know that the query produces only one result row.

Also available are functions that print result rows in a default format. They are often used for debugging. (These are not available with the Microsoft Windows® operating system.)

DB-Library processes results one statement at a time, although multiple statements can be sent. When all the results for one statement have been read, dbresults must be called again to set up the results for the next statement in the command buffer and one final time to return NO_MORE_RESULTS.

Information covering several areas, including regular result columns, compute result columns, row buffers, and the command state, can be retrieved from the DBPROCESS structure. Regular result columns correspond to columns in the SELECT statement's select list, and compute result columns correspond to columns in the SELECT statement's optional COMPUTE clause.