Send a command batch to the server.
RETCODE dbsqlexec(dbproc) DBPROCESS *dbproc;
A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server.
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 error. dbsqlexec also fails if previous results had not been processed, or if the command buffer was empty.
In addition, a runtime error, such as a database protection violation, can cause dbsqlexec to fail. A runtime error will cause dbsqlexec to fail:
If the command causing the error is the only command in the command buffer
If the command causing the error is the first command in a multiple-command buffer
If the command buffer contains multiple commands (and the first command in the buffer is ok), a runtime error will not cause dbsqlexec to fail. Instead, failure will occur with the dbresults call that processes the command causing the runtime error.
The situation is a bit more complicated for runtime errors and stored procedures. A runtime error on an execute command may cause dbsqlexec to fail, in accordance with the rule given in the previous paragraphs. A runtime 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 fails, but dbsqlexec will still return SUCCEED. To check for runtime errors inside stored procedures, use the dbretstatus routine to look at the procedure’s return status, and trap relevant server messages inside your message handler.
This routine sends SQL commands, stored in the command buffer of the DBPROCESS, to the server. Commands may be added to the DBPROCESS structure by calling dbcmd or dbfcmd.
Once dbsqlexec returns SUCCEED, the application must call dbresults to process the results.
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 Adaptive Server Enterprise */
dbsqlexec(dbproc);
/* Get ready to process the query results */
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
}
dbsqlexec is equivalent to dbsqlsend followed by dbsqlok. However, after sending a query to the 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 application to respond more effectively to multiple input and output streams. See the reference pages for dbsqlsend and dbsqlok.
Multiple commands may exist in the command buffer when an application calls dbsqlexec. These commands are sent to the server as a unit and are considered to be a single command batch.
dbcmd, dbfcmd, dbnextrow, dbresults, dbretstatus, dbsettime, dbsqlok, dbsqlsend