srv_pre_handle

Installs a pre-event handler for an extended stored procedure that is called before the standard event handler.

Syntax

int srv_pre_handle (
SRV_SERVER * server,
SRV_PROC * srvproc,
DBINT event,
SRV_PRE_HANDLE_PROC handler,
BOOL remove );

where

server

Is a pointer to the SRV_SERVER structure. Use srv_init to get this pointer. If you provide a server value, you must provide a NULL srvproc value.

srvproc

Is a pointer to the SRV_PROC structure that is the handle for a particular client connection. The srvproc parameter contains the information that the Open Data Services Library uses to manage communication and data between the application and the client.

If you provide a srvproc value, you must provide a NULL server value.

event

Specifies the event assigned to handler. If you provide a server value, all events are valid. If you provide a srvproc value, the following client-generated events are valid:

• SRV_ATTENTION
• SRV_DISCONNECT
• SRV_LANGUAGE
• SRV_RPC

handler

Is a pointer to the function that is called before the standard event handler (installed by srv_handle) when the event defined by event occurs.

If a server value is provided, this function is global to the Open Data Services application and will be called (before the standard event handler) every time event occurs.

If a srvproc value is provided, this function will be called (before the standard event handler) only when event is generated by the srvproc client connection.

This function should be defined as returning an int and taking a single parameter. This parameter should be defined as SRV_SERVER * when event is one of the following:

• SRV_EXIT
• SRV_START
• SRV_SLEEP
• SRV_RESTART
• SRV_STOP

and defined as SRV_PROC * when event is one of the following:

• SRV_ATTENTION
• SRV_DISCONNECT
• SRV_LANGUAGE
• SRV_RPC

This function must return one of the following values:

Return value	Description
SRV_CONTINUE	Continue normal processing.
SRV_DISCONNECT	Fire a disconnect event to close the client connection.
SRV_EXIT	Fire a disconnect event to close the client connection.
SRV_SKIP	Skip execution of the standard event handler. The post-event handler is still executed.

remove

Is a boolean flag that determines if the specified handler should be installed or removed. Use FALSE to install a new handler for event. Use TRUE to remove an existing handler for event.

Returns

SUCCEED, FAIL, or SRV_DUPLICATE_HANDLER. SRV_DUPLICATE_HANDLER is returned if you attempt to install the same pre-event handler function multiple times for the same event.

Remarks

When an event occurs, Open Data Services calls the following functions in this order:

1. The pre-event handler (installed by srv_pre_handle)
2. The standard event handler (installed by srv_handle)
3. The post-event handler (installed by srv_post_handle)

You can install pre-event handlers dynamically. The new pre-event handler is called when the next event occurs. For each event, an extended stored procedure application can have multiple global pre-event handlers, and multiple pre-event handlers per client connection, but you cannot install the same pre-event handler function multiple times for the same event. Open Data Services will automatically remove the post-event handler when necessary; your program should not attempt to do this.

See Also