1 Version 4.0 -- 5/1/89dbsqlexec_a (VMS only)
______________________________________________________________________
NAME: dbsqlexec_a (VMS only)
FUNCTION:
Send a command batch to SQL Server and verify its correctness
asynchronously.
SYNTAX:
RETCODE dbsqlexec_a(dbproc, final_result, ast_proc, ast_param)
DBPROCESS *dbproc;
RETCODE *final_result;
void (*ast_proc)();
dbsqlexec_a (VMS only)Version 4.0 -- 5/1/89 2
______________________________________________________________________
BYTE *ast_param;
COMMENTS:
o This routine is the asynchronous version of dbsqlexec().
o This routine sends SQL commands, stored in the command buffer
of the DBPROCESS, to SQL Server. Commands may be added to the
DBPROCESS structure by calling dbcmd() or dbfcmd().
o The following three events must occur before dbresults() or
dbresults_a() can be called to process the query results:
o dbsqlexec_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 dbsqlexec_a() returns FAIL, *final_result will not be set
and ast_proc() will not be invoked. If dbsqlexec_a() returns
3 Version 4.0 -- 5/1/89dbsqlexec_a (VMS only)
______________________________________________________________________
SUCCEED, *final_result will be set to SUCCEED or FAIL (depend-
ing on whether SQL Server verifies the command batch as
correct) and ast_proc() will be invoked by DB-Library.
o dbsqlexec_a() is useful in VMS applications that use multi-
tasking or are otherwise trying to respond to multiple input
and output streams. After sending a query to SQL Server,
dbsqlexec() waits until a response is received or until the
timeout period has elapsed. By substituting dbsqlexec_a() for
dbsqlexec(), the time between the request for SQL Server infor-
mation and SQL Server's response can be used to service other
parts of the application.
o References in this manual to the dbsqlexec() routine also per-
tain to dbsqlexec_a().
o For an example that illustrates the use of dbsqlexec_a(), see
the DB-Library Reference Supplement.
dbsqlexec_a (VMS only)Version 4.0 -- 5/1/89 4
______________________________________________________________________
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 dbsqlexec_a() returns SUCCEED. *final_result will be
set to SUCCEED if SQL Server determines that the command
batch is correct. The most common reason that *final_result
gets set to FAIL is a SQL syntax error. *final_result also
gets set to FAIL if there are semantic errors, such as
incorrect column or table names. Failure occurs if any of
the commands in the batch contains a semantic or syntax
error.
In addition, a run-time error, such as a database protection
violation, will set *final_result to FAIL if the command
5 Version 4.0 -- 5/1/89dbsqlexec_a (VMS only)
______________________________________________________________________
buffer contains only a single command. If the command buffer
contains multiple commands, a run-time error will not set
*final_result to FAIL. Instead, failure will occur with the
dbresults() or 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
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
dbsqlexec_a (VMS only)Version 4.0 -- 5/1/89 6
______________________________________________________________________
messages inside your message handler.
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:
SUCCEED or FAIL. dbsqlexec_a() will return FAIL if any of the
following conditions are true: previous results were not pro-
cessed, the command buffer was empty, or there was an error in
sending the command batch to SQL Server.
SEE ALSO:
dbcancel, dbcancel_a, dbcmd, dbfcmd, dbnextrow, dbnextrow_a,
7 Version 4.0 -- 5/1/89dbsqlexec_a (VMS only)
______________________________________________________________________
dbresults, dbresults_a, dbretstatus, dbsqlexec, dbsqlok,
dbsqlsend