Firebird 2.0
PHP5 Programming

Overview of Firebird events

Firebird “events” are named messages that the server can send to client applications that have registered an interest in such events. Events are used to announce the occurrence of a specified condition or action, usually a database change such as an INSERT, UPDATE, or DELETE.

The Firebird event mechanism enables applications to respond to actions and database changes made by other, concurrently running applications without the need for those applications to communicate directly with one another, and without incurring the expense of CPU time required for periodic polling to determine if an event has occurred.

The Firebird event mechanism consists of four parts:

  • A PSQL program that posts an event (to the event manager)

  • An event manager that maintains an event queue and notifies applications when an event is committed.

  • A first client application (or application thread) that registers interest in the event and waits for it to occur.

  • A second client application (or application thread) that uses the event-posting PSQL routine (i.e. calls a procedure or causes a trigger to fire) so that the first client (thread) can resume processing.

Events are not database objects and do not have to be declared or created before use. Event names are restricted to 78 characters in size.

Events are under transaction control. This is implemented thtough an event manager: an event is a message passed by a PSQL program to the event manager. The event manager queues the event messages for later processing:

  • The event manager maintains a list of events posted to it by PSQL programs. If the transaction in which the event posting took place is commited, the event is passed on to the client application(s). If that transaction is rolled back, the posting is removed from the queue.

  • Within a single transaction all postings of the same event are merged, i.e. Multiple postings of the same event within a single transaction are reported to the relevant clients as a single event when the transaction is committed.

  • The event manager also maintains a list of applications that have registered an interest in events. Each time a new event is committed, the event manager notifies interested applications that the event has occurred.

  • After the interested application(s) have been notified (possibly none), the event is removed from the queue.

Event handling in PHP5

Firebird's PHP5 driver allows PHP programs to act as event clients. There are two ways to handle events: synchroneously and asynchroneously.

  • In the synchroneous case, the PHP program reports an interest in certain events occuring and then proceeds to wait for such an event.

  • In the asynchroneous case, the PHP program sets up an event handler function and continues processing. If a relevant event occurs, PHP will interupt its normal processing and call the event handler function. Upon completion of the event handlert normal processing continues.


<event_function> ::=
   | <free_event_handler>
   | <wait_evetn>


The following three functions deal with events:

  • set_event_handler
    This function registers an event handler function for certain events. When the event occurs, the handler function is called.

  • free_event_handler
    This function unregisters an event handler function and frees the resources associated with that.

  • wait_event
    The wait_event function registers interest in certain events and proceeds to wait for any of those events occuring

previous page goto index next page

Legal information