Read the specified row in the row buffer.
STATUS dbgetrow(dbproc, row) DBPROCESS *dbproc; DBINT row;
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.
The number of the row to read. Rows are counted from the first row returned from the server, whose number is 1. Note that the first row in the row buffer is not necessarily the first row returned from the server.
dbgetrow can return four different types of values:
If the current row is a regular row, REG_ROW is returned.
If the current row is a compute row, the computeid of the row is returned. (See the dbaltbind reference page for information on the computeid.
If the row is not in the row buffer, NO_MORE_ROWS is returned, and the current row is left unchanged.
If the routine was unsuccessful, FAIL is returned.
dbgetrow sets the current row in the row buffer to a specific row and reads it. This routine works only if the DBBUFFER option is on, enabling row buffering. When dbgetrow is called, any binding of row data to program variables (as specified with dbbind or dbaltbind) takes effect.
Row buffering provides a way to keep a specified number of server result rows in program memory. Without row buffering, the result row generated by each new dbnextrow call overwrites the contents of the previous result row. Row buffering is therefore useful for programs that need to look at result rows in a non-sequential manner. It does, however, carry a memory and performance penalty because each row in the buffer must be allocated and freed individually. Therefore, use it only if you need to. Specifically, the application should only turn the DBBUFFER option on if it calls dbgetrow or dbsetrow. Note that row buffering has nothing to do with network buffering and is a completely independent issue.
When row buffering is not allowed, the application processes each row as it is read from the server, by calling dbnextrow repeatedly until it returns NO_MORE_ROWS. When row buffering is enabled, the application can use dbgetrow to jump to any row that has already been read from the server with dbnextrow. Subsequent calls to dbnextrow cause the application to read successive rows in the buffer. When dbnextrow reaches the last row in the buffer, it reads rows from the server again, if there are any. Once the buffer is full, dbnextrow does not read any more rows from the server until some of the rows have been cleared from the buffer with dbclrbuf.
The macros DBFIRSTROW, DBLASTROW, and DBCURROW are useful in conjunction with dbgetrow calls. DBFIRSTROW, for instance, gets the number of the first row in the buffer. Thus, the call:
dbgetrow(dbproc, DBFIRSTROW(dbproc))
sets the current row to the first row in the buffer.
The routine dbsetrow sets a buffered row to “current” but does not read the row.
For an example of row buffering, see the sample program example4.c.
dbaltbind, dbbind, dbclrbuf, DBCURROW, DBFIRSTROW, DBLASTROW, dbnextrow, dbsetrow, Options
