1 Version 4.0 -- 5/1/89 dbresults
______________________________________________________________________
NAME: dbresults
FUNCTION:
Set up the results of the next query.
SYNTAX:
RETCODE dbresults(dbproc)
DBPROCESS *dbproc;
COMMENTS:
o This routine sets up the next command in the command batch for
dbresults Version 4.0 -- 5/1/89 2
______________________________________________________________________
processing. The application program calls it after dbsqlexec()
or dbsqlok() returns SUCCEED. The first call to dbresults()
will always return either SUCCEED or NO_MORE_RESULTS if the
call to dbsqlexec() or dbsqlok() has returned SUCCEED. Once
dbresults() returns SUCCEED, the application typically
processes any result rows with dbnextrow().
o To manage multiple input data streams efficiently, a UNIX
application can confirm that unread bytes are available, either
in the DB-Library network buffer (by calling DBRBUF()) or in
the network itself (by calling the UNIX select() function),
before calling dbresults().
o dbresults() must be called for each command in the command
batch, whether or not the command returns any rows. If the
application code doesn't know how many commands are in the
batch (for example, if the application is designed to process
ad hoc queries), it can call dbresults() until it returns
3 Version 4.0 -- 5/1/89 dbresults
______________________________________________________________________
NO_MORE_RESULTS.
dbresults() must also ordinarily be called once for any stored
procedure executed in the command batch. However, if the
stored procedure contains more than one SQL SELECT statement,
then dbresults() must be called once for each SELECT. Again,
the easiest way to do this is to continue to call dbresults()
until it returns NO_MORE_RESULTS.
o To cancel the remaining results from the command batch (and
eliminate the need to continue calling dbresults() until it
returns NO_MORE_RESULTS), call dbcancel().
o To determine whether a particular command is one that returns
rows and needs results processing with dbnextrow(), call
DBROWS() after the dbresults() call.
o The typical sequence of calls for using dbresults() with
dbsqlexec() is:
dbresults Version 4.0 -- 5/1/89 4
______________________________________________________________________
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 */
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 */
5 Version 4.0 -- 5/1/89 dbresults
______________________________________________________________________
while (dbnextrow(dbproc) != NO_MORE_ROWS)
{
C-code to print or process row data
}
Example 1 in the DB-Library Reference Supplement shows how to
use dbresults() to process a multi-query command batch.
o Another use for dbresults() is to process the results of a
remote procedure call made with dbrpcsend(). See the
dbrpcsend() manual page for details.
o An asynchronous version of dbresults(), called dbresults_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
dbresults Version 4.0 -- 5/1/89 6
______________________________________________________________________
contains all the information that DB-Library uses to manage
communications and data between the front end and SQL Server.
RETURNS:
SUCCEED, FAIL or NO_MORE_RESULTS. dbresults() returns
NO_MORE_RESULTS if all commands in the buffer have already been
processed. The most common reason for failing is a run-time
error, such as a database permission violation.
The number of commands in the command buffer determines whether
dbsqlexec() or dbresults() traps a run-time error. If the buffer
contains only a single command, a run-time error will cause
dbsqlexec() to fail. If the command buffer contains multiple
commands, a run-time error will not cause dbsqlexec() to fail.
Instead, the dbresults() call that processes the command causing
the run-time error will fail.
The situation is a bit more complicated for run-time errors and
7 Version 4.0 -- 5/1/89 dbresults
______________________________________________________________________
stored procedures. A run-time error on an EXECUTE command may
cause dbresults() 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 dbresults() 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 dbresults() will still
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:
dbbind, dbcancel, dbnextrow, DBRBUF, dbresults_a, dbretstatus,
DBROWS, dbrpcsend, dbsqlexec, dbsqlok