1 Version 4.0 -- 5/1/89dbresults_a (VMS only)
______________________________________________________________________
NAME: dbresults_a (VMS only)
FUNCTION:
Set up the results of the next query.
SYNTAX:
RETCODE dbresults_a(dbproc, final_result, ast_proc, ast_param)
DBPROCESS *dbproc;
RETCODE *final_result;
void (*ast_proc)();
BYTE *ast_param;
dbresults_a (VMS only)Version 4.0 -- 5/1/89 2
______________________________________________________________________
COMMENTS:
o This routine is the asynchronous version of dbresults().
o This routine sets up the next command in the command batch for
processing. The application program calls it after dbsqlexec()
or dbsqlexec_a() returns SUCCEED. The first call to
dbresults_a() will always return either SUCCEED or
NO_MORE_RESULTS if the call to dbsqlexec() or dbsqlexec_a() has
returned SUCCEED.
o The following three events must occur before dbnextrow() or
dbnextrow_a() can be called to process any result rows:
o dbresults_a() must return SUCCEED.
o *final_result must be set to SUCCEED by DB-Library.
o ast_proc() must be invoked by DB-Library.
3 Version 4.0 -- 5/1/89dbresults_a (VMS only)
______________________________________________________________________
If dbresults_a() returns FAIL or NO_MORE_RESULTS, *final_result
will not be set and ast_proc() will not be invoked. If
dbresults_a() returns SUCCEED, *final_result will be set to
SUCCEED or FAIL and ast_proc() will be invoked by DB-Library.
o dbresults_a() is useful in VMS applications that use multi-
tasking or are otherwise trying to respond to multiple input
and output streams. dbresults() waits until a SQL Server
response is received or until the timeout period has elapsed.
By substituting dbresults_a() for dbresults(), the time it
takes to receive results from SQL Server can be used to service
other parts of the application.
o dbresults_a() must be called for each command in the command
batch, whether or not the command returns any rows. If the
application code doesn't know how many commands are in the
batch (for example, if the application is designed to process
ad hoc queries), it can call dbresults_a() until it returns
dbresults_a (VMS only)Version 4.0 -- 5/1/89 4
______________________________________________________________________
NO_MORE_RESULTS.
dbresults_a() must also ordinarily be called once for any
stored procedure executed in the command batch. However, if
the stored procedure contains more than one SQL SELECT state-
ment, then dbresults_a() must be called once for each SELECT.
Again, the easiest way to do this is to continue to call
dbresults_a() until it returns NO_MORE_RESULTS.
o To cancel the remaining results from the command batch (and
eliminate the need to continue calling dbresults_a() until it
returns NO_MORE_RESULTS), call dbcancel() or dbcancel_a.
o To determine whether a particular command is one that returns
rows and needs results processing with dbnextrow() or
dbnextrow_a(), call DBROWS() after the dbresults_a() call.
o Another use for dbresults_a() is to process the results of a
remote procedure call made with dbrpcsend(). See the
5 Version 4.0 -- 5/1/89dbresults_a (VMS only)
______________________________________________________________________
dbrpcsend() manual page for details.
o References in this manual to the dbresults() routine also per-
tain to dbresults_a().
o For an example that illustrates the use of dbresults_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 SUCCEED or
FAIL if dbresults_a() returns SUCCEED. *final_result will be
set to SUCCEED if SQL Server determines that the current com-
mand is successful. The most common reason that
*final_result gets set to FAIL is a run-time error, such as a
dbresults_a (VMS only)Version 4.0 -- 5/1/89 6
______________________________________________________________________
database permission violation.
The number of commands in the command buffer determines
whether dbsqlexec() or dbresults_a() traps a run-time error.
If the buffer contains only a single command, a run-time
error will cause dbsqlexec() to fail. If the command buffer
contains multiple commands, a run-time error will not cause
dbsqlexec() to fail. Instead, DB-Library will return FAIL in
the *final_result of the dbresults_a() call that processes
the command causing the run-time error.
The situation is a bit more complicated for run-time errors
and stored procedures. A run-time error on an EXECUTE com-
mand may set *final_result to FAIL, in accordance with the
rule given in the previous paragraph. A run-time error on a
statement inside a stored procedure will not set
*final_result to FAIL, however. For example, if the stored
procedure contains an INSERT statement and the user does not
7 Version 4.0 -- 5/1/89dbresults_a (VMS only)
______________________________________________________________________
have insert permission on the database table, the INSERT
statement will fail, but *final_result will still be set to
SUCCEED. To check for run-time errors inside stored pro-
cedures, use the dbretstatus() routine to look at the
procedure's return status, and trap relevant SQL Server mes-
sages inside your message handler.
ast_proc - A pointer to a user-supplied routine that will be
queued when the success of the current command 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:
SUCCEED, FAIL or NO_MORE_RESULTS. dbresults_a() returns
NO_MORE_RESULTS if all commands in the buffer have already been
dbresults_a (VMS only)Version 4.0 -- 5/1/89 8
______________________________________________________________________
processed. dbresults_a will return FAIL if there are still rows
pending from a previous query.
SEE ALSO:
dbbind, dbcancel, dbnextrow, dbnextrow_a, dbresults, dbretstatus,
DBROWS, dbsqlexec, dbsqlexec_a, dbsqlok