Install a handler routine for a registered procedure notification.
RETCODE dbreghandle(dbproc, procedure_name, namelen,
handler)
DBPROCESS *dbproc;
DBCHAR *procedure_name;
DBSMALLINT namelen;
INTFUNCPTR handler;
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 the registered procedure for which the handler is being installed.
If procedure_name is passed as NULL, the handler is installed as a default handler. The default handler will be called for all registered procedure notifications read by this DBPROCESS connection for which no other handler has been installed.
The length of procedure_name, in bytes. If procedure_name is null-terminated, pass namelen as DBNULLTERM.
A pointer to the function to be called by DB-Library/C when the registered procedure notification is read.
If handler is passed as NULL, any handler previously installed for the registered procedure is uninstalled.
SUCCEED or FAIL.
dbreghandle installs a user-supplied handler routine to be called by DB-Library/C when a DBPROCESS connection reads an asynchronous notification that a registered procedure has been executed.
Because a notification procedure is simply a special type of registered procedure, a handler for a notification procedure may also be installed using dbreghandle.
An application receives an asynchronous notification only if it has previously called dbregwatch with options passed as DBNOWAITONE or DBNOWAITALL. This call tells Open Server that the application is interested in the execution of the registered procedure, that it will receive the notification asynchronously, and that it will read the notification through a particular DBPROCESS connection.
If no handler is installed for a notification, DB-Library/C will raise an error when the DBPROCESS connection reads the notification.
Either procedure_name or handler may be NULL:
If both procedure_name and handler are supplied, dbreghandle installs the handler specified by handler for the registered procedure specified by procedure_name.
If procedure_name is NULL and handler is NULL, dbreghandle uninstalls all handlers for this DBPROCESS connection.
If procedure_name is NULL but handler is supplied, dbreghandle installs the handler specified by handler as a “default” handler for this DBPROCESS connection. This default handler will be called whenever the DBPROCESS connection reads a registered procedure notification for which no other handler has been installed.
If procedure_name is supplied but handler is NULL, dbreghandle uninstalls any handler previously installed for this registered procedure. If a default handler has been installed for this DBPROCESS connection, it remains in effect and will be called if a procedure_name notification is read.
The same handler may be used by several DBPROCESS connections, but it must be installed for each one by a separate call to dbreghandle. Because of the possibility of a single notification handler being called when different DBPROCESSes read notifications, all handlers should be written to be re-entrant.
A single DBPROCESS connection may be watching for several registered procedures to execute. This connection may have different handlers installed to process the various notifications it may read. Each handler must be installed by a separate call to dbreghandle.
A DBPROCESS connection may be idle, sending commands, reading results, or idle with results pending when a 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.
Because a notification may be read while a DBPROCESS connection is in any of several different states, the actions that a notification handler may take are restricted. A notification handler may not use an existing DBPROCESS to send a query to the server, process the results of a query, or call dbcancel or dbcanquery. A notification handler may, however, open a new DBPROCESS and use this new DBPROCESS to send queries and process results within the handler.
A notification handler can read the arguments passed to the registered procedure upon execution. To do this, the handler can use the DB-Library/C routines dbnumrets, dbrettype, dbretlen, dbretname, and dbretdata.
All notification handlers are called by DB-Library/C with the following parameters:
dbproc, a pointer to the DBPROCESS connection that has been watching for the notification
procedure_name, a pointer to the name of the registered procedure that has been executed
reserved1, a DBUSMALLINT parameter reserved for future use
reserved2, a DBUSMALLINT parameter reserved for future use
A notification handler must return INT_CONTINUE to indicate normal completion, or INT_EXIT to instruct DB-Library/C to abort the application and return control to the operating system.
Notification handlers on the Windows platform must be declared with CS_PUBLIC, as shown in the example below. For portability, callback handlers on other platforms should be declared CS_PUBLIC as well.
This is an example of a notification handler:
DBINT CS_PUBLIC my_procedure_handler(dbproc,
procedure_name, reserved1, reserved2)
/* The client connection */
DBPROCESS *dbproc;
/* A null-terminated string */
DBCHAR *procedure_name;
/* Reserved for future use */
DBUSMALLINT reserved1;
/* Reserved for future use */
DBUSMALLINT reserved2;
{
int i, type;
DBINT len;
char *name;
BYTE *data;
int params;
/*
** Find out how many parameters this
** procedure received.
*/
params = dbnumrets(dbproc);
i = 0; /* Initialize counter */
/* Now process each parameter in turn */
while(i++ < params)
{
/* Get the parameter’s datatype */
type = dbrettype(dbproc, i);
/* Get the parameter’s length */
len = dbretlen(dbproc, i);
/* Get the parameter’s name */
name = dbretname(dbproc, i);
/* Get a pointer to the parameter */
data = dbretdata(dbproc, i);
/* Process the parameter here */
}
return(INT_CONTINUE);
}
