dbnextrow

Reads in the next row.

Syntax

STATUS dbnextrow ( PDBPROCESS dbproc );

where

dbproc

Is the DBPROCESS structure that is the handle for a particular workstation/ SQL Server process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server.

Returns

One of five different types of values:

• If a regular row is read, REG_ROW is returned. Regular rows contain data from columns designated by a SELECT statement.
• If a compute row is read, the computeid of the row is returned. (For information about computeid, see "dbaltbind.")
• If there are no more rows to be read, if the statement didn't return any rows, or if the server was unable to return more rows (for example, when a deadlock occurs), NO_MORE_ROWS is returned.
• 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 has been read. To read more rows, first clear at least one row from the top of the row buffer. To clear the row buffer, call dbclrbuf.
• If the function was unsuccessful, FAIL is returned.

Remarks

The dbnextrow function causes the next data row to be made available through the dbproc. If the DBBUFFER option is turned on and rows have been read out of order by calling dbgetrow, the next data row is read from the buffered rows. Any specified binding of row data to program variables takes effect.

The dbresults function must be called and must have returned SUCCEED before you make any calls to dbnextrow.

Even if dbrows or dbcmdrow returns FAIL (indicating that no rows were returned), you must process the results by calling dbnextrow until it returns NO_MORE_ROWS.

Normally, each row is processed in turn by repeatedly calling dbnextrow. If row buffering is enabled and the row buffer has been cleared by the dbclrbuf function, the discarded rows are no longer available (even if dbgetrow tries to position to a discarded row). When row buffering is disabled, the last row is cleared when dbnextrow returns no_more_rows.

SQL Server can return two types of rows:

• Regular rows containing data from columns designated by a SELECT statement's select list.
• Compute rows resulting from the COMPUTE clause.

To help process data rows from SQL Server, dbnextrow returns different values according to the type of row. For details, see the previous section, "Returns."

If you want data returned from SQL Server to be displayed on the default output device, use dbprrow instead of dbnextrow (except with the Windows operating system).

Note This function is one of the four that do not return control to the application until the server sends the required response. The application can be blocked for a considerable time if the server is waiting for a lock or is processing a large sort. If this is unacceptable, always call dbdataready before dbnextrow and set the DB-Library timeout to regain control periodically.

Example

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);

// Now process each row. 
while (dbnextrow(dbproc) != NO_MORE_ROWS)
{
    //    C-code to print or process row data 
}

Note that if you are not using row buffering, you must continue calling dbnextrow until it returns NO_MORE_ROWS. This is true even if you are sure that your query only generates one results row. The while loop in the preceding example illustrates the correct way to use dbnextrow.

See Also

dbaltbind, dbbind, dbclrbuf, dbgetrow, dbprrow, dbresults; Bulk-Copy Functions, and DB-Library Options