Read the next result row into the row buffer and into any program variables that are bound to column data.
STATUS dbnextrow(dbproc) DBPROCESS *dbproc;
A pointer to the DBPROCESS structure that provides the connection for a particular front end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server.
dbnextrow returns:
REG_ROW if a regular row has been read. A regular row is any row that matches the query’s where clause.
A computeid if a compute row was read. A compute row is a row that is generated by a compute clause. The computeid matches the number of the compute row that was read; the first compute row is 1, the second is 2, and so forth. A computeid cannot match any other of the return types for this function.
BUF_FULL is returned if buffering is turned on and reading the next row would cause the buffer to be exceeded. In this case, no row will have been read. To read any more rows, at least one row must first be pruned from the top of the row buffer by calling dbclrbuf.
NO_MORE_ROWS if the last row in the result set has been read. If the query did not generate rows (for example, an update or insert, or a select with no match), then the first call to dbnextrow will return NO_MORE_ROWS. Also, dbnextrow returns this value if the query failed or if there are no pending results.
FAIL if an abnormal event, such as a network or out-of-memory error, prevented the routine from completing successfully.
dbnextrow reads the next row of result data, starting with the first row returned from the server. Ordinarily, the next result row is read directly from the server. If the DBBUFFER option is turned on and rows have been read out of order by calling dbgetrow, the next row is read instead from a linked list of buffered rows. When dbnextrow is called, any binding of row data to program variables (as specified with dbbind or dbaltbind) takes effect.
If program variables are bound to columns, then new values will be written into the bound variables before dbnextrow returns.
In regular rows, column values can be retrieved with dbdata or bound to program variables with dbbind. In compute rows, column values can be retrieved with dbadata or bound to program variables with dbaltbind.
dbresults must return SUCCEED before an application can call dbnextrow. To determine whether a particular command is one that returns rows and needs results processing with dbnextrow, call DBROWS after dbresults.
After calling dbresults, an application can either call dbcanquery or dbcancel to cancel the current set of results, or call dbnextrow in a loop to process the results row-by-row.
If it chooses to process the results, an application can either:
Process all result rows by calling dbnextrow in a loop until it returns NO_MORE_ROWS. After NO_MORE_ROWS is returned, the application can call dbresults again to set up the next result set (if any) for processing.
Process some result rows by calling dbnextrow, and then cancel the remaining result rows by calling dbcancel (to cancel all results from the command batch or RPC call) or dbcanquery (to cancel only the results associated with the last dbresults call).
An application must either cancel or process all result rows.
The typical sequence of calls is:
DBINT xvariable;
DBCHAR yvariable[10];
/* Read the query into the command buffer */
dbcmd(dbproc, "select x = 100, y = ’hello’");
/* Send the query to Adaptive Server Enterprise */
dbsqlexec(dbproc);
/* Get ready to process the query results */
dbresults(dbproc);
/* Bind column data to program variables */
dbbind(dbproc, 1, INTBIND, (DBINT) 0,
(BYTE *) &xvariable);
dbbind(dbproc, 2, STRINGBIND, (DBINT) 0,
yvariable);
/* Now process each row */
while (dbnextrow(dbproc) != NO_MORE_ROWS)
{
C-code to print or process row data
}
The server can return two types of rows: regular rows containing data from columns designated by a select statement’s select list, and compute rows resulting from the compute clause. To facilitate the processing of result rows from the server, dbnextrow returns different values according to the type of row. See the “Returns” section in this reference page for details.
To display server result data on the default output device, you can use dbprrow instead of dbnextrow.
dbaltbind, dbbind, dbcanquery, dbclrbuf, dbgetrow, dbprrow, dbsetrow, Options
