PostgreSQL 7.4beta4 Documentation
Prev | Fast Backward |  | Fast Forward | Next

# pg_listen

## Name

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

## Synopsis

    pg_listen conn notifyName ?callbackCommand?

## Description

`pg_listen` creates, changes, or cancels a request to listen for asynchronous notification messages from the PostgreSQL server. 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 notification message bearing the given name arrives from the server. This occurs when any PostgreSQL client application issues a `NOTIFY` command referencing that name. 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 notification message yourself, invoke the SQL `NOTIFY` statement using `pg_exec`.

## Arguments

conn

  The handle of the connection on which to listen for notifications.

notifyName

  The name of the notification condition to start or stop listening to.

callbackCommand

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

## Return Value

None

Prev | Home | Next
pg_execute | Up | pg_on_connection_loss