dbcancel

Cancels the current command batch and flushes any pending results.

Syntax

RETCODE dbcancel ( PDBPROCESS dbproc );

Arguments

dbproc

Is the DBPROCESS structure that is the handle for a particular workstation/ Microsoft® SQL Server™ process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server.

Returns

SUCCEED or FAIL.

Remarks

You can call this function after calling dbsqlexec, dbsqlsend, dbsqlok, dbresults, or dbnextrow to cancel the execution of the current command batch that SQL Server is processing and eliminate any pending results. When dbcancel is called, SQL Server is interrupted and stops executing the command batch associated with the dbproc. Any pending results are read and discarded. Note that dbcancel cancels all the commands in the current command batch. Don’t use it to cancel only the current command in a multiple-command batch; use dbcanquery instead.

If you receive the DB-Library error 10038 “Results Pending,” you can call dbcancel to clear the pending results. If dbcancel returns FAIL, the server may not be able to respond to the cancel request. Either continue to call dbcancel until it returns SUCCEED, or close the DBPROCESS connection and open a new one.

See Also