1 Version 4.0 -- 5/1/89 dbcancel_a (VMS only)
______________________________________________________________________
NAME: dbcancel_a (VMS only)
FUNCTION:
Cancel the current command batch.
SYNTAX:
RETCODE dbcancel_a(dbproc, final_result, ast_proc, ast_param)
DBPROCESS *dbproc;
RETCODE *final_result;
void (*ast_proc)();
BYTE *ast_param;
dbcancel_a (VMS only)Version 4.0 -- 5/1/89 2
______________________________________________________________________
COMMENTS:
o dbcancel_a() is the asynchronous version of dbcancel().
o This routine cancels execution of the current command batch on
SQL Server and flushes any pending results. The application
can call it after calling dbsqlexec(), dbsqlexec_a(),
dbsqlsend(), dbsqlok(), dbresults(), dbresults_a(), dbnex-
trow(), or dbnextrow_a(). dbcancel_a() sends an attention
packet to SQL Server, which causes SQL Server to cease execu-
tion of the command batch. Any pending results are read and
discarded.
o dbcancel_a() cancels all the commands in the current command
batch. To cancel only the results from the current command,
call dbcanquery() instead.
o If you have set your own interrupt handler using
3 Version 4.0 -- 5/1/89 dbcancel_a (VMS only)
______________________________________________________________________
dbsetinterrupt(), you can't call dbcancel_a() in your interrupt
handler. This would cause output from SQL Server to DB-Library
to become out of sync. If you want to cancel the current com-
mand batch from your interrupt handler, the interrupt handler
should set a flag that you can check before the next call to
dbresults(), dbresults_a(), dbnextrow(), or dbnextrow_a().
o If dbcancel_a() returns FAIL, *final_result will not be set and
ast_proc() will not be invoked. If dbcancel_a() returns
SUCCEED, *final_result will be set to SUCCEED or FAIL (depend-
ing on whether the current batch was successfully canceled) and
ast_proc() will be invoked by DB-Library.
o dbcancel_a() is useful in VMS applications that use multi-
tasking or are otherwise trying to respond to multiple input
and output streams. After sending an attention packet to
SQL Server, dbcancel() waits until all pending results are read
and discarded or until the timeout period has elapsed. By
dbcancel_a (VMS only)Version 4.0 -- 5/1/89 4
______________________________________________________________________
substituting dbcancel_a() for dbcancel(), the time between the
request for SQL Server attention and SQL Server's response can
be used to service other parts of the application.
o References in this manual to the dbcancel() routine also per-
tain to dbcancel_a().
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 dbcancel_a() returns SUCCEED. *final_result will be
set to SUCCEED if the current command batch was successfully
canceled.
ast_proc - A pointer to a user-supplied routine that will be
queued when the current command batch is successfully
5 Version 4.0 -- 5/1/89 dbcancel_a (VMS only)
______________________________________________________________________
canceled or an error occurs. *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 or FAIL.
SEE ALSO:
dbcancel, dbcanquery, dbnextrow, dbnextrow_a, dbresults,
dbresults_a, dbsetinterrupt, dbsqlexec, dbsqlexec_a, dbsqlok,
dbsqlsend