Firebird 2.0
PHP5 Programming
Manual

FBIRD_SET_EVENT_HANDLER

Purpose

Use the fbird_set_event_handler function to register a handler for specified Firebird events.

Syntax

<set_event_handler> ::=
   fbird_set_event_handler( [ conn_hndl, ] handler, <events> )

<events> ::=
     event
   | event , <events>


Element 
Type
Description
conn_hndl
resource
A valid connection handle
handler
callback
A callback function name
event
string
A event name (15 max)
<return>
mixed
An event handler handle on success, False on failure

Semantics

The fbird_set_event handler function registers a PHP user function as event handler for the specified events. It accepts up to 15 event name arguments.

On success, the return value is an event handle. This handle can be used to free the event handler using fbird_free_event_handler. On failure, the function returns False.

If a connection handle is not provided, then the "default" connection will be used. The default connection is assigned every time you call fbird_connect or fbird_pconnect, so if you have multiple connections it will be whichever one was connected last.

The event handler function must have the following signature:

<event_handler> ::=
   function <name> ( event, conn_hndl )


Element 
Type
Description
event
string
A event name
conn_hndl
resource
A valid connection handle
<return>
bool
False deallocates the handler, True leaves it in place for a next event occurence

The callback function must accept two arguments: an event name and a connection handle. When a Firebird procedure commits a POST_EVENT statement, the callback function is called with the event name and the connection handle as arguments. The callback must return False if the event handler should be canceled. Any other return value is ignored.

Example

The below example shows a simple event handler function and the activation of the function for two Firebird events.

function event_handler($event_name, $conn)
{
   if ($event_name=="NEW ORDER") {
      // process new order
      fbird_query($conn, "UPDATE orders SET status='handled'");
   } else if ($event_name=="DB_SHUTDOWN") {
      // free event handler
      return false;
   }
}

fbird_set_event_handler($conn, "event_handler", "NEW_ORDER",
                        "DB_SHUTDOWN");



See also

fbird_free_event_handler


previous page goto index next page

Legal information