1 Version 4.0 -- 5/1/89 dbsqlexec
______________________________________________________________________
NAME: dbsqlexec
FUNCTION:
Send a command batch to SQL Server.
SYNTAX:
RETCODE dbsqlexec(dbproc)
DBPROCESS *dbproc;
COMMENTS:
o This routine sends SQL commands, stored in the command buffer
dbsqlexec Version 4.0 -- 5/1/89 2
______________________________________________________________________
of the DBPROCESS, to SQL Server. Commands may be added to the
DBPROCESS structure by calling dbcmd() or dbfcmd().
o Once dbsqlexec() returns SUCCEED, the application must call
dbresults() to process the results.
o The typical sequence of calls is:
DBINT xvariable;
DBCHAR yvariable[10];
/* read the query into the command buffer */
dbcmd(dbproc, "select x = 100, y = 'hello'");
/* send the query to SQL Server */
dbsqlexec(dbproc);
/* get ready to process the results of the query */
3 Version 4.0 -- 5/1/89 dbsqlexec
______________________________________________________________________
dbresults(dbproc);
/* bind column data to program variables */
dbbind(dbproc, 1, INTBIND, (DBINT) 0, (BYTE *) &xvariable);
dbbind(dbproc, 2, STRINGBIND, (DBINT) 0, yvariable);
/* now process each row */
while (dbnextrow(dbproc) != NO_MORE_ROWS)
{
C-code to print or process row data
}
o dbsqlexec() is equivalent to dbsqlsend() followed by dbsqlok().
However, after sending a query to SQL Server, dbsqlexec() waits
until a response is received or until the timeout period has
elapsed. By substituting dbsqlsend() and dbsqlok() for
dbsqlexec(), you can sometimes provide a way for the
dbsqlexec Version 4.0 -- 5/1/89 4
______________________________________________________________________
application to respond more effectively to multiple input and
output streams. See the manual pages for those two routines
for more information.
o An asynchronous version of dbsqlexec(), called dbsqlexec_a(),
is available for VMS.
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.
RETURNS:
SUCCEED or FAIL. The most common reason for failing is a SQL
syntax error. dbsqlexec() will also 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
5 Version 4.0 -- 5/1/89 dbsqlexec
______________________________________________________________________
error. dbsqlexec() also fails if previous results had not been
processed, or if the command buffer was empty.
In addition, a run-time error, such as a database protection vio-
lation, will cause dbsqlexec() to fail if the command buffer con-
tains only a single command. If the command buffer contains mul-
tiple commands, a run-time error will not cause dbsqlexec() to
fail. Instead, failure will occur with the dbresults() 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 command may
cause dbsqlexec() 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 cause dbsqlexec() 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 dbsqlexec() will still
dbsqlexec Version 4.0 -- 5/1/89 6
______________________________________________________________________
return 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 messages inside your
message handler.
SEE ALSO:
dbcmd, dbfcmd, dbnextrow, dbresults, dbretstatus, dbsettime,
dbsqlexec_a, dbsqlok, dbsqlsend