Once 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 routine accomplishes this. Each call to dbnextrow reads the next row returned from the server. The row is read directly from the network.
Once 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 may be automatically saved in a row buffer, if desired. The application accomplishes this by setting the DBBUFFER option with the dbsetopt routine. Row buffering is useful for applications that need to process result rows in a non-sequential manner. Without row buffering, the application must process each row as it is read in by dbnextrow, because the next call to dbnextrow will overwrite the row. If the application has allowed row buffering, the rows are added to a row buffer as they are read in by dbnextrow. The application can then use the dbgetrow routine to skip around in the buffer and return to previously read rows. Since row buffering carries a memory and performance penalty, use it with discretion. Note that row buffering has nothing to do with network buffering and is a completely independent issue.
Routines are also available to print result rows in a default format. Because the format is predetermined, these routines are of limited usefulness and are appropriate primarily for debugging.
Note that DB-Library/C processes results one command at a time. When the application has read all the results for one command, it must call dbresults again to set up the results for the next command in the command buffer. To ensure that all results are handled, Sybase strongly recommends that dbresults be called in a loop.
The following routines are used to process result rows:
dbnextrow – reads in the next row. The return value from dbnextrow tells the application whether the row is a regular row or a compute row, whether the row buffer is full, and whether the last result row has been read.
DBCURROW – returns the number of the row currently being read.
dbprhead – prints default column headings for result rows. This routine is used in conjunction with dbprrow.
dbprrow – prints all the result rows in a default format. When this routine is used, the program does not need to bind results or call dbnextrow.
