1 Version 4.0 -- 5/1/89 dbnextrow
______________________________________________________________________
NAME: dbnextrow
FUNCTION:
Read the next result row.
SYNTAX:
STATUS dbnextrow(dbproc)
DBPROCESS *dbproc;
COMMENTS:
o dbnextrow() reads the next row of result data, starting with
dbnextrow Version 4.0 -- 5/1/89 2
______________________________________________________________________
the first row returned from the SQL Server. Ordinarily, the
next result row is read directly from the SQL 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.
o The application must successfully call dbresults() before it
can make any calls to dbnextrow().
o To determine whether a particular command is one that returns
rows and needs results processing with dbnextrow(), call
DBROWS() after dbresults().
o Normally, each result row is processed in turn by repeatedly
calling dbnextrow() until it returns NO_MORE_ROWS. To cancel
the current set of results instead, call dbcanquery. After a
call to dbcanquery(), it is safe to call dbresults() again.
3 Version 4.0 -- 5/1/89 dbnextrow
______________________________________________________________________
o 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 SQL Server */
dbsqlexec(dbproc);
/* get ready to process the results of the query */
dbresults(dbproc);
/* bind column data to program variables */
dbbind(dbproc, 1, INTBIND, (DBINT) 0, (BYTE *) &xvariable);
dbbind(dbproc, 2, STRINGBIND, (DBINT) 0, yvariable);
dbnextrow Version 4.0 -- 5/1/89 4
______________________________________________________________________
/* now process each row */
while (dbnextrow(dbproc) != NO_MORE_ROWS)
{
C-code to print or process row data
}
o The SQL Server can return two types of rows: regular rows con-
taining 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
SQL Server, dbnextrow() returns different values according to
the type of row. See the section "RETURNS" for details.
o To display SQL Server result data on the default output device,
you can use dbprrow() instead of dbnextrow().
o An asynchronous version of dbnextrow(), called dbnextrow_a(),
5 Version 4.0 -- 5/1/89 dbnextrow
______________________________________________________________________
is available for VMS.
PARAMETERS:
dbproc - A pointer to the DBPROCESS structure that provides the
connection for a particular front end/SQL Server process. It
contains all the information that DB-Library uses to manage
communications and data between the front end and SQL Server.
RETURNS:
dbnextrow() can return five different types of values:
o If a regular row is read, REG_ROW is returned.
o If a compute row is read, the computeid of the row is returned.
(See dbaltbind() for information on the computeid.)
o If there are no more rows to be read or the command didn't
return any rows, NO_MORE_ROWS is returned.
dbnextrow Version 4.0 -- 5/1/89 6
______________________________________________________________________
o If buffering is turned on and reading the next row would cause
the buffer to be exceeded, BUF_FULL is returned. 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 cal-
ling dbclrbuf().
o If the routine was unsuccessful, FAIL is returned.
SEE ALSO:
dbaltbind, dbbind, dbcanquery, dbclrbuf, dbgetrow, dbnextrow_a,
dbprrow, options