PostgreSQL 7.2.1 Documentation
Prev |  | Next

# pg_listen

## Name

pg_listen -- set or change a callback for asynchronous NOTIFY messages

## Synopsis

    pg_listen dbHandle notifyName callbackCommand

### Inputs

`dbHandle`

  Specifies a valid database handle.

`notifyName`

  Specifies the notify condition name to start or stop listening to.

`callbackCommand`

  If present and not empty, provides the command string to execute when a matching notification arrives.

### Outputs

None

## Description

`pg_listen` creates, changes, or cancels a request to listen for asynchronous NOTIFY messages from the PostgreSQL backend. With a `callbackCommand` parameter, the request is established, or the command string of an already existing request is replaced. With no `callbackCommand` parameter, a prior request is canceled.

After a `pg_listen` request is established, the specified command string is executed whenever a NOTIFY message bearing the given name arrives from the backend. This occurs when any PostgreSQL client application issues a NOTIFY command referencing that name. (Note that the name can be, but does not have to be, that of an existing relation in the database.) The command string is executed from the Tcl idle loop. That is the normal idle state of an application written with Tk. In non-Tk Tcl shells, you can execute `update` or `vwait` to cause the idle loop to be entered.

You should not invoke the SQL statements LISTEN or UNLISTEN directly when using `pg_listen`. Pgtcl takes care of issuing those statements for you. But if you want to send a NOTIFY message yourself, invoke the SQL NOTIFY statement using `pg_exec`.

Prev | Home | Next
pg_select | Up | pg_lo_creat