1 Version 4.0 -- 5/1/89dbnextrow_a (VMS only)
______________________________________________________________________
NAME: dbnextrow_a (VMS only)
FUNCTION:
Read the next result row.
SYNTAX:
STATUS dbnextrow_a(dbproc , final_result, ast_proc, ast_param)
DBPROCESS *dbproc;
RETCODE *final_result;
void (*ast_proc)();
BYTE *ast_param;
dbnextrow_a (VMS only)Version 4.0 -- 5/1/89 2
______________________________________________________________________
COMMENTS:
o This routine is the asynchronous version of dbnextrow().
o dbnextrow_a() causes the next row of result data to be read,
starting with the first row returned from the SQL Server.
Ordinarily, the next result row is taken 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 data row
is read instead from a linked list of buffered rows. When
dbnextrow_a() is called, any binding of row data to program
variables (as specified with dbbind() or dbaltbind()) takes
effect.
o The application must call dbresults() or dbresults_a() with a
final result of SUCCEED before it can make any calls to
dbnextrow_a().
3 Version 4.0 -- 5/1/89dbnextrow_a (VMS only)
______________________________________________________________________
o To determine whether a particular command is one that returns
rows and needs results processing with dbnextrow_a(), call
DBROWS() after dbresults() or dbresults_a().
o Normally, each row is processed in turn by repeatedly calling
dbnextrow_a() until final_result has been set to NO_MORE_ROWS.
To cancel the current set of results instead, call dbcanquery.
After a call to dbcanquery(), it is safe to call dbresults() or
dbresults_a() again.
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 rows from SQL Server,
dbnextrow_a() returns different final results according to the
type of row. See below for details.
o The following three events must occur before row data can be
examined:
dbnextrow_a (VMS only)Version 4.0 -- 5/1/89 4
______________________________________________________________________
o dbnextrow_a() must return SUCCEED.
o *final_result must be set to SUCCEED by DB-Library.
o ast_proc() must be invoked by DB-Library.
If dbnextrow_a() returns FAIL or BUF_FULL, *final_result will
not be set and ast_proc() will not be invoked. If
dbnextrow_a() returns SUCCEED, *final_result will be set (see
the description of final_result below), and ast_proc() will be
invoked by DB-Library.
o dbnextrow_a() is useful in VMS applications that use multi-
tasking or are otherwise trying to respond to multiple input
and output streams. dbnextrow() waits until a row is received
or until the timeout period has elapsed. By substituting
dbnextrow_a() for dbnextrow(), the time between the request for
SQL Server information and SQL Server's response can be used to
service other parts of the application.
5 Version 4.0 -- 5/1/89dbnextrow_a (VMS only)
______________________________________________________________________
o References in this manual to the dbnextrow() routine also per-
tain to dbnextrow_a().
o For an example that illustrates the use of dbnextrow_a(), see
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.
final_result - A pointer to a RETCODE which is set to (1)
REG_ROW if a regular row was read, (2) the row's computeid if
a compute row was read, (3) NO_MORE_ROWS if there are no more
rows to be read or if the command didn't return any rows, or
(4) FAIL if a SQL Server communications error occurred.
final_result will be set only if dbnextrow_a() returns
dbnextrow_a (VMS only)Version 4.0 -- 5/1/89 6
______________________________________________________________________
SUCCEED. For information on compute rows and the computeid,
see the manual page on dbaltbind().
ast_proc - A pointer to a user-supplied routine that will be
queued when the correctness of the command batch is finally
determined by SQL Server. *final_result will always be set
before this procedure is invoked.
ast_param - A generic BYTE pointer that will be passed to the
user-supplied ast_proc(). ast_param allows the user to pass
any parameter or structure to the ast_proc routine.
RETURNS:
dbnextrow_a() can return three different values:
o If the routine succeeded, SUCCEED is returned.
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
7 Version 4.0 -- 5/1/89dbnextrow_a (VMS only)
______________________________________________________________________
row must first be pruned from the top of the row buffer by cal-
ling dbclrbuf().
o If the routine was otherwise unsuccessful, FAIL is returned.
SEE ALSO:
dbaltbind, dbbind, dbcanquery, dbclrbuf, dbgetrow, dbnextrow,
dbprrow, options