Set a buffered row to “current.”
STATUS dbsetrow(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 the server.
An integer representing the row number of the row to make current. Row number 1 is the first row returned from the server. This is not necessarily the first row in the row buffer.
MORE_ROWS, NO_MORE_ROWS, or FAIL.
dbsetrow returns:
MORE_ROWS if it found row in the row buffer, or
NO_MORE_ROWS if it did not find row in the row buffer or if row buffering is not enabled, or
FAIL if the dbproc DBPROCESS is dead or not enabled.
dbsetrow sets a buffered row to “current.” After dbsetrow is called, the application’s next call to dbnextrow will read this row.
dbgetrow, another DB-Library/C routine, also sets a specific row in the row buffer to “current.” However, unlike dbsetrow, dbgetrow reads the row. Any binding of row data to program variables (as specified with dbbind and dbaltbind) takes effect.
dbsetrow has no effect unless the DB-Library/C option DBBUFFER is on.
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 enabled, the application processes each row as it reads it from the server by calling dbnextrow repeatedly until it returns NO_MORE_ROWS. When row buffering is enabled, the application can use dbsetrow to jump to any row that has already been read from the server with dbnextrow. Subsequent calls to dbnextrow will cause the application to read successive rows in the buffer, starting with the row specified by the row parameter. 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 macro DBFIRSTROW, which returns the number of the first row in the row buffer, is useful in conjunction with dbsetrow. Thus, the call:
dbsetrow(dbproc, DBFIRSTROW(dbproc))
sets the current row so that the next call to dbnextrow will read the first row in the buffer.
dbclrbuf, DBCURROW, DBFIRSTROW, dbgetrow, DBLASTROW, dbnextrow, Options
