Verifies that a server response has arrived for a DBPROCESS.
RETCODE dbpoll(dbproc, milliseconds, ready_dbproc,
return_reason)
DBPROCESS *dbproc;
long milliseconds;
DBPROCESS **ready_dbproc;
int *return_reason;
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/C uses to manage communications and data between the front end and server.
dbproc represents the DBPROCESS connection that dbpoll will check.
If dbproc is passed as NULL, dbpoll will check all open DBPROCESS connections to see if a response has arrived for any of them.
The maximum number of milliseconds that dbpoll should wait for a response before returning.
If milliseconds is passed as 0, dbpoll returns immediately.
If milliseconds is passed as -1, dbpoll will not return until either a server response arrives or a system interrupt occurs.
A pointer to a pointer to a DBPROCESS structure. dbpoll sets *ready_dbproc to point to the DBPROCESS for which the server response has arrived. If no response has arrived, dbpoll sets *ready_dbproc to NULL.
ready_dbproc is
not a DBPROCESS pointer.
It is a pointer to a DBPROCESS pointer.
A pointer to an integer representing the reason dbpoll has returned. The integer will be one of the following symbolic values:
DBRESULT |
A response to a server command has arrived. The application may call dbsqlok (assuming that dbsqlsend has been called) to examine the server’s response. |
DBNOTIFICATION |
A registered procedure notification has arrived. If a handler for this registered procedure has been installed using dbreghandle, dbpoll invokes this handler before it returns. If a handler for the registered procedure has not been installed and there is no default handler installed for this DBPROCESS, DB-Library raises an error when it reads the notification. |
DBTIMEOUT |
The time indicated by the milliseconds parameter elapsed before any server response arrived. |
DBINTERRUPT |
An operating-system interrupt occurred before any server response arrived and before the timeout period elapsed. |
This list may expand in the future, as more kinds of
server responses are recognized by DB-Library/C.
It is recommended that application programs be coded to handle unexpected
values in return_reason without
error.
SUCCEED or FAIL.
dbpoll returns FAIL if any of the server connections it checks has died. If dbpoll returns FAIL, ready_dbproc and return_reason are undefined.
dbpoll checks the TDS (Tabular Data Stream) buffer to see if it contains any server response not yet read by an application.
dbproc represents the DBPROCESS connection that dbpoll will check. If dbproc is passed as NULL, dbpoll examines all open connections and returns as soon as it finds one that has an unread server response.
If there is an unread response, dbpoll sets *ready_dbproc and return_reason to reflect which DBPROCESS connection the response is for and what the response is.
Note that ready_dbproc is not a pointer to a DBPROCESS structure. It is a pointer to the address of a DBPROCESS. dbpoll sets *ready_dbproc to point to the DBPROCESS for which the server response has arrived. If no server response has arrived, dbpoll sets *ready_dbproc to NULL.
dbpoll can be used for two purposes:
To allow an application to implement non-blocking reads (calls to dbsqlok) from the server
To check if a registered procedure notification has arrived for a DBPROCESS
dbpoll can be used to check whether bytes are available for dbsqlok to read.
Depending on the nature of an application, the time between the moment when a command is sent to the server (made using dbsqlsend or dbrpcsend) and the server’s response (initially read with dbsqlok) may be significant.
During this time, the server is processing the command and building the result data. An application may use this time to perform other duties. When ready, the application can call dbpoll to check if a server response arrived while it was busy elsewhere. For an example of this usage, see the reference page for dbsqlok.
On occasion dbpoll may
report that data is ready for dbsqlok to
read when only the first bytes of the server response are present.
When this occurs, dbsqlok waits
for the rest of the response or until the timeout period has elapsed,
just like dbsqlexec.
In practice, however, the entire response is usually available at
one time.
dbpoll should not be used with dbresults or dbnextrow. dbpoll cannot determine if calls to these routines will block. This is because dbpoll works by checking whether or not bytes are available on a DBPROCESS connection, and these two routines do not always read from the network.
If all of the results from a command have been read, dbresults returns NO_MORE_RESULTS. In this case, dbresults does not block even if no bytes are available to be read.
If all of the rows for a result set have been read, dbnextrow returns NO_MORE_ROWS. In this case, dbnextrow does not block even if no bytes are available to be read.
For non-blocking reads, alternatives to dbpoll are DBRBUF and DBIORDESC. These routines are specific to the UNIX-specific platform. They are not portable, so their use should be avoided whenever possible. They do, however, provide a way for application programs to integrate handling of DB-Library/C sockets with other sockets being used by an application.
DBRBUF is a UNIX-specific routine. It checks an internal DB-Library network buffer to see if a server response has already been read. dbpoll checks one or all connections used by an application’s DBPROCESSes, to see if a response is ready to be read.
DBIORDESC, another UNIX-specific routine, is similar in function to dbpoll. DBIORDESC provides the socket handle used for network reads by the DBPROCESS. The socket handle can be used with the UNIX select function.
An application may have one or more DBPROCESS connections waiting for registered procedure notifications. A DBPROCESS connection will not be aware that a registered procedure notification has arrived unless it reads results from the server. If a connection is not reading results, it can use dbpoll to check if a registered procedure notification has arrived. If so, dbpoll reads the registered procedure notification stream and calls the handler for that registered procedure.
Here is a code fragment that uses dbpoll to poll for a registered procedure notification:
/*
** This code fragment illustrates the use of
** dbpoll() to processan event notification.
**
** The code fragment will ask the Server to
** notify the Client when the event "shutdown"
** occurs. When the event notification is
** received from the Server, DB-Library will call
** the handler installed for that event. This
** event handler routine can then access the
** event’s parameters, and take any appropriate
** action.
*/
DBINT handlerfunc();
DBINT ret;
/* First install the handler for this event */
dbreghandle(dbproc, "shutdown", handlerfunc);
/*
** Now make the asynchronous notification
** request.
*/
ret = dbregwatch(dbproc, "shutdown", DBNULLTERM,
DBNOWAITONE);
if (ret == FAIL)
{
fprintf(stderr, "ERROR: dbregwatch() \
failed!!\n");
}
else if (ret == DBNOPROC)
{
fprintf(stderr, "ERROR: procedure shutdown \
not defined!\n");
}
/*
** Since we are making use of the asynchronous
** event notification mechanism, the application
** can continue doing other work. All we have to
** do is call dbpoll() once in a while, to deal
** with the event notification when it arrives.
*/
while (1)
{
/* Have dbpoll() block for one second */
dbpoll(NULL, 1000, NULL, &ret);
/*
** If we got the event, then get out of this
** loop.
*/
if (ret == DBNOTIFICATION)
{
break;
}
/* Deal with our other tasks here */
}
