1 Version 4.0 -- 5/1/89 dbsqlok
______________________________________________________________________
NAME: dbsqlok
FUNCTION:
Wait for results from the SQL Server and verify the correctness
of the instructions the SQL Server is responding to.
SYNTAX:
RETCODE dbsqlok(dbproc)
DBPROCESS *dbproc;
COMMENTS:
dbsqlok Version 4.0 -- 5/1/89 2
______________________________________________________________________
o This routine waits for results from the SQL Server and verifies
the correctness of the instructions that the SQL Server is
responding to.
The "instructions that the SQL Server is responding to" can be
any of the following:
o A command batch (when dbsqlok() is used with dbsqlsend()).
o Processing information for handling chunks of text or image
data (when dbsqlok() is used with dbmoretext()).
o A remote procedure call (when dbsqlok() is used with
dbrpcsend()).
o The application must call dbsqlok() after a call to dbsqlsend()
or dbrpcsend(), and before and after a set of dbmoretext()
calls. A successful dbsqlok() call must always be followed by
a call to dbresults() to process the results.
3 Version 4.0 -- 5/1/89 dbsqlok
______________________________________________________________________
o dbsqlexec() is equivalent to dbsqlsend() followed by dbsqlok().
o The use of dbsqlsend() with dbsqlok() is of particular value in
UNIX applications. 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
a UNIX application to respond more effectively to multiple
input and output streams. The time between the request for
information from SQL Server (made via a call to dbsqlsend())
and SQL Server's response (read by calling dbsqlok()) can be
used, in conjunction with DBIORDESC() or DBIOWDESC(), to ser-
vice other parts of the application. DBIORDESC() and
DBIOWDESC() are available for UNIX only. See the manual pages
for those two routines for more information.
To manage input data streams efficiently, a UNIX application
using dbsqlok() should confirm that unread bytes are available,
dbsqlok Version 4.0 -- 5/1/89 4
______________________________________________________________________
either in the DB-Library network buffer (by calling DBRBUF())
or in the network itself (by calling the UNIX select() func-
tion), before calling dbresults().
For a UNIX example that illustrates the use of dbsqlok() with
dbsqlsend(), DBRBUF(), DBIORDESC(), and DBIOWDESC(), see the
DB-Library Reference Supplement.
On occasion the operating system may inform the application
that data is ready for dbsqlok() to read when only the first
part of the SQL Server response is present. When this occurs,
dbsqlok() waits for the rest of the response or until the
timeout period has elapsed, just like dbsqlexec(). In prac-
tice, however, the entire response is usually available at one
time.
o dbsqlok() is also useful in text update operations. When
chunks of text are sent to SQL Server via dbwritetext() and
dbmoretext(), dbsqlok() must be called before the first call to
5 Version 4.0 -- 5/1/89 dbsqlok
______________________________________________________________________
dbmoretext() and after the last call to dbmoretext(). For an
example of its use in this context, see the manual page for
dbwritetext().
o dbsqlok() is also necessary when making remote procedure calls.
The application must call it after dbrpcsend() and before
dbresults().
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 syn-
tax error. dbsqlok() will also fail if there are semantic
errors, such as incorrect column or table names. Failure occurs
dbsqlok Version 4.0 -- 5/1/89 6
______________________________________________________________________
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 vio-
lation, will cause dbsqlok() 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 dbsqlok() 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 dbsqlok() 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 dbsqlok() 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 dbsqlok() will still return
7 Version 4.0 -- 5/1/89 dbsqlok
______________________________________________________________________
SUCCEED. To check for run-time errors inside stored procedures,
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, DBIORDESC, DBIOWDESC, dbmoretext, dbnextrow,
DBRBUF, dbresults, dbretstatus, dbrpcsend, dbsettime, dbsqlexec,
dbsqlsend, dbwritetext