LISTEN(l)                                               LISTEN(l)

NAME
       LISTEN - Listen for a response on a notify condition

SYNOPSIS
       LISTEN name

   INPUTS
       name   Name of notify condition.

   OUTPUTS
       LISTEN Message returned upon successful completion of reg-
              istration.

       NOTICE Async_Listen: We are already listening on name
              If this backend  is  already  registered  for  that
              notify condition.

DESCRIPTION
       LISTEN  registers  the  current Postgres backend as a lis-
       tener on the notify condition name.

       Whenever the command NOTIFY name  is  invoked,  either  by
       this   backend  or  another  one  connected  to  the  same
       database, all the backends  currently  listening  on  that
       notify  condition  are  notified,  and  each  will in turn
       notify its connected frontend application. See the discus-
       sion of NOTIFY for more information.

       A backend can be unregistered for a given notify condition
       with the UNLISTEN command. Also, a backend's listen regis-
       trations  are  automatically cleared when the backend pro-
       cess exits.

       The method a  frontend  application  must  use  to  detect
       notify  events  depends on which Postgres application pro-
       gramming interface it uses. With the basic libpq  library,
       the  application issues LISTEN as an ordinary SQL command,
       and then must periodically call the routine PQnotifies  to
       find  out  whether  any  notify events have been received.
       Other interfaces such  as  libpgtcl  provide  higher-level
       methods  for handling notify events; indeed, with libpgtcl
       the application programmer should not even issue LISTEN or
       UNLISTEN  directly.  See the documentation for the library
       you are using for more details.

       notify(l) contains a more extensive discussion of the  use
       of LISTEN and NOTIFY.

   NOTES
       name can be any string valid as a name; it need not corre-
       spond to the name of any actual table.  If  notifyname  is
       enclosed in double-quotes, it need not even be a syntacti-
       cally valid name, but can be any string up to  31  charac-
       ters long.

       In  some  previous  releases  of  Postgres, name had to be
       enclosed in double-quotes when it did  not  correspond  to
       any  existing table name, even if syntactically valid as a
       name. That is no longer required.

USAGE
       Configure and execute a listen/notify sequence from psql:

       LISTEN virtual;
       NOTIFY virtual;

       ASYNC NOTIFY of 'virtual' from backend pid '11239' received

COMPATIBILITY
   SQL92
       There is no LISTEN in SQL92.

SQL - Language Statements 15 August 1999                        1