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

User comments:

Extend this topic - Post a comment