Set up the results of the next query.
RETCODE dbresults(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, 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 runtime error, such as a database permission violation.
The number of commands in the command buffer determines whether dbsqlexec or dbresults traps a runtime error. If the buffer contains only a single command, a runtime error will cause dbsqlexec to fail. If the command buffer contains multiple commands, a runtime error will not cause dbsqlexec to fail. Instead, the dbresults call that processes the command causing the runtime error fails.
The situation is a bit more complicated for runtime errors and stored procedures. A runtime error on an execute command may cause dbresults to fail, in accordance with the rule given in the previous paragraph. A runtime 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 fails, but dbresults 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 sets up the next command in the command batch for 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.
If a command batch contains only a single command, and that command does not return rows, for example a “use database” command, a DB-Library/C application does not have to call dbresults to process the results of the command. However, if the command batch contains more than one command, a DB-Library/C application must call dbresults once for every command in the batch, whether or not the command returns rows.
dbresults must also be called at least once for any stored procedure executed in a command batch, whether or not the stored procedure returns rows. If the stored procedure contains more than one Transact-SQL select, then dbresults must be called once for each select.
To ensure that dbresults is called the correct number of times, Sybase strongly recommends that dbresults always be called in a loop that terminates when dbresults returns NO_MORE_RESULTS.
All Transact-SQL commands
are considered commands by dbresults.
For a list of Transact-SQL commands,
see the Adaptive Server Enterprise Reference Manual.
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.
To determine whether a particular command is one that returns rows and needs results processing with dbnextrow, call DBROWS after the dbresults call.
The typical sequence of calls for using dbresults with dbsqlexec is:
DBINT xvariable;
DBCHAR yvariable[10];
RETCODE return_code;
/* 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 results of the query.
** Note that dbresults is called in a loop even
** though only a single set of results is expected.
** This is simply because it is good programming
** practice to always code dbresults calls in loop.
*/
while ((return_code
=dbresults(dbproc)!=NO_MORE_RESULTS)
{
if ((return_code == SUCCEED)
& & (DBROWS(dbproc) == SUCCEED))
{
/* 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
}
}
}
The sample program example1.c shows how to use dbresults to process a multiquery command batch.
To manage multiple input data streams efficiently, an application can confirm that unread bytes are available, either in the DB-Library network buffer or in the network itself. The application can either:
(For UNIX only) call DBRBUF to test whether bytes remain in the network buffer, and call DBIORDESC and the UNIX select to test whether bytes remain in the network itself, or
(For all systems) call dbpoll.
Another use for dbresults is to process the results of a remote procedure call made with dbrpcsend. See the dbrpcsend reference page for details.
dbbind, dbcancel, dbnextrow, dbpoll, DBRBUF, dbretstatus, DBROWS, dbrpcsend, dbsqlexec, dbsqlok
