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 [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

       is  enclosed  in double-quotes, it need not even be a syn­
       tactically valid name, but can be  any  string  up  to  31
       characters 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;

       Asynchronous NOTIFY 'virtual' from backend with pid '8448' received.


COMPATIBILITY

   SQL92
       There is no LISTEN in SQL92.


Man(1) output converted with man2html