1 Version 4.0 -- 5/1/89 dbgetrow
______________________________________________________________________
NAME: dbgetrow
FUNCTION:
Read the specified row in the row buffer.
SYNTAX:
STATUS dbgetrow(dbproc, row)
DBPROCESS *dbproc;
DBINT row;
COMMENTS:
dbgetrow Version 4.0 -- 5/1/89 2
______________________________________________________________________
o dbgetrow() sets the current row in the row buffer to a specific
row and reads it. This routine only works if the DBBUFFER
option is on, enabling row buffering. When dbgetrow() is
called, any binding of row data to program variables (as speci-
fied with dbbind() or dbaltbind()) takes effect.
o Row buffering provides a way to keep a specified number of
SQL Server result rows in program memory. Without row buffer-
ing, 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().
Note that row buffering has nothing to do with network
3 Version 4.0 -- 5/1/89 dbgetrow
______________________________________________________________________
buffering and is a completely independent issue.
o When row buffering is not enabled, the application processes
each row as it is read from the SQL Server, by calling dbnex-
trow() 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 SQL Server
with dbnextrow(). Subsequent calls to dbnextrow() cause the
application to read successive rows in the buffer. When dbnex-
trow() reaches the last row in the buffer, it reads rows from
SQL Server again, if there are any. Once the buffer is full,
dbnextrow() does not read any more rows from SQL Server until
some of the rows have been cleared from the buffer with
dbclrbuf().
o 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.
dbgetrow Version 4.0 -- 5/1/89 4
______________________________________________________________________
Thus, the call:
dbgetrow(dbproc, DBFIRSTROW(dbproc))
sets the current row to the first row in the buffer.
o For an example of row buffering, see Example 4 in the
DB-Library Reference Supplement.
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.
row - The number of the row to read. Rows are counted from the
first row returned from SQL Server, whose number is 1. Note
that the first row in the row buffer is not necessarily the
first row returned from SQL Server.
5 Version 4.0 -- 5/1/89 dbgetrow
______________________________________________________________________
RETURNS:
dbgetrow() can return four different types of values:
o If the current row is a regular row, REG_ROW is returned.
o If the current row is a compute row, the computeid of the row
is returned. (See dbaltbind() for information on the compu-
teid.)
o If the row is not in the row buffer, NO_MORE_ROWS is returned
and the current row is left unchanged.
o If the routine was unsuccessful, FAIL is returned.
SEE ALSO:
dbaltbind, dbbind, dbclrbuf, DBCURROW, DBFIRSTROW, DBLASTROW,
dbnextrow, options