PostgreSQL Tcl Interface 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