Request to be notified when a registered procedure executes.
RETCODE dbregwatch(dbproc, procedure_name,namelen,
options)
DBPROCESS *dbproc;
DBCHAR *procedure_name;
DBSMALLINT namelen;
DBUSMALLINT options;
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 the server.
A pointer to the name of a registered procedure. The registered procedure must be defined in Open Server.
The length of procedure_name, in bytes. If procedure_name is null-terminated, pass namelen as DBNULLTERM.
A two-byte bitmask: DBWAIT, DBNOWAITONE, or DBNOWAITALL.
If options is passed as DBWAIT, dbregwatch will not return until the DBPROCESS connection reads a synchronous notification that the registered procedure has executed.
If options is passed as DBNOWAITONE, dbregwatch returns -immediately. The DBPROCESS connection will receive an asynchronous notification when the registered procedure executes. The connection will receive only a single notification, even if the registered procedure executes multiple times.
If options is passed as DBNOWAITALL, dbregwatch returns immediately. The DBPROCESS connection will receive an asynchronous notification when the registered procedure executes. The connection will continue to receive notifications, one for each execution of the registered procedure, until it informs Open Server that it no longer wishes to receive them.
SUCCEED, DBNOPROC, or FAIL.
dbregwatch returns FAIL if no handler is installed for the registered procedure.
dbregwatch informs Open Server that a DBPROCESS connection should be notified when a particular registered procedure executes. Because a notification procedure is simply a special type of registered procedure, dbregwatch also informs Open Server that a DBPROCESS connection should be notified when a particular notification procedure executes.
The connection can request to be notified synchronously or asynchronously:
To request synchronous notification, an application passes options as DBWAIT in its call to dbregwatch. In this case, dbregwatch will not return until the DBPROCESS connection reads the notification that the registered procedure has executed.
Open Server will send only a single notification as the result of a synchronous notification request. If the registered procedure executes a second time, after the synchronous request has been satisfied, the client will not receive a second notification, unless another notification request is made.
To request asynchronous notification, an application passes options as DBNOWAITONE or DBNOWAITALL in its call to dbregwatch. In this case, dbregwatch returns immediately. A return code of SUCCEED indicates that Open Server has accepted the request.
If options is DBNOWAITONE, Open Server will send only a single notification, even if the registered procedure executes multiple times.
If options is DBNOWAITALL, Open Server will continue to send a notification every time the registered procedure executes, until it is informed, using dbregnowatch, that the client no longer wishes to receive them.
A DBPROCESS connection may be idle, sending commands, reading results, or idle with results pending when an asynchronous registered procedure notification arrives.
If the DBPROCESS connection is idle, it is necessary for the application to call dbpoll to allow the connection to read the notification. If a handler for the notification has been installed, it will be called before dbpoll returns.
If the DBPROCESS connection is sending commands, the notification is read and the notification handler called during dbsqlexec or dbsqlok. After the notification handler returns, flow of control continues normally.
If the DBPROCESS connection is reading results, the notification is read and the notification handler called either in dbresults or dbnextrow. After the notification handler returns, flow of control continues normally.
If the DBPROCESS connection is idle with results pending, the notification is not read until all results in the stream up to the notification have been read and processed by the connection.
An application must install a handler to process the registered procedure notification before calling dbregwatch. If no handler is installed, dbregwatch returns FAIL. An application can install a notification handler using dbreghandle.
If the handler is uninstalled after the application calls dbregwatch but before the registered procedure notification is received, DB-Library/C raises an error when the notification is received.
If the procedure referenced by procedure_name is not defined in Open Server, dbregwatch returns DBNOPROC. An application can obtain a list of procedures currently registered in Open Server using dbreglist.
An application can obtain a list of registered procedures it is watching for using dbregwatchlist.
This is an example of making a synchronous notification request:
DBPROCESS *dbproc;
DBINT handlerfunc;
DBINT ret;
/*
** The registered procedure is defined in Open
** Server as:
** shutdown msg_param varchar(255)
*/
/*
** First install the handler for this registered
** procedure:
*/
dbreghandle(dbproc, "shutdown", DBNULLTERM,
handlerfunc);
/* Make the notification request and wait: */
ret = dbregwatch(dbproc, "shutdown", DBNULLTERM,
DBWAIT);
if (ret == FAIL)
{
fprintf (stderr, "ERROR: dbregwatch() \
failed!\n");
}
else if (ret == DBNOPROC)
{
fprintf (stderr, "ERROR: procedure shutdown \
not defined.\n");
}
else
{
/*
** The registered procedure notification has
** been returned, and our registered
** procedure handler has already been called.
*/
}
This is an example of making an asynchronous notification request:
DBPROCESS *dbproc;
DBINT handlerfunc;
DBINT ret;
/*
** The registered procedure is defined in Open
** Server as:
** shutdown msg_param varchar(255)
*/
/*
** First install the handler for this registered
** procedure:
*/
dbreghandle(dbproc, "shutdown", DBNULLTERM,
handlerfunc);
/* Make the asynchronous notification request: */
ret = dbregwatch(dbproc, "shutdown", DBNULLTERM,
DBNOWAITALL);
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 asychronous
** registered procedure notification mechanism,
** the application can continue doing other work
** while waiting for the notification. All we
** have to do is call dbpoll() once in a while to
** read the registered procedure notification
** when it arrives.
*/
while (1)
{
/* Have dbpoll() block for one second */
dbpoll (NULL, 1000, NULL, &ret);
/*
** If we got the notification, then exit
** the loop
*/
if (ret == DBNOTIFICATION)
break;
/* Handle other program tasks here */
}
dbpoll, dbregexec, dbregparam, dbreglist, dbregwatchlist, dbregnowatch
