doc/src/sgml/ref/listen.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-LISTEN">
   7  <refmeta>
   8   <refentrytitle id="SQL-LISTEN-TITLE">LISTEN</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>LISTEN</refname>
  14   <refpurpose>listen for a notification</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-listen">
  18   <primary>LISTEN</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 LISTEN <replaceable class="PARAMETER">name</replaceable>
  24 </synopsis>
  25  </refsynopsisdiv>
  26
  27  <refsect1>
  28   <title>Description</title>
  29
  30   <para>
  31    <command>LISTEN</command> registers the current session as a
  32    listener on the notification condition <replaceable
  33    class="PARAMETER">name</replaceable>.
  34    If the current session is already registered as a listener for
  35    this notification condition, nothing is done.
  36   </para>
  37
  38   <para>
  39    Whenever the command <command>NOTIFY <replaceable
  40    class="PARAMETER">name</replaceable></command> is invoked, either
  41    by this session or another one connected to the same database, all
  42    the sessions currently listening on that notification condition are
  43    notified, and each will in turn notify its connected client
  44    application.  See the discussion of <command>NOTIFY</command> for
  45    more information.
  46   </para>
  47
  48   <para>
  49    A session can be unregistered for a given notify condition with the
  50    <command>UNLISTEN</command> command.  A session's listen
  51    registrations are automatically cleared when the session ends.
  52   </para>
  53
  54   <para>
  55    The method a client application must use to detect notification events depends on
  56    which <productname>PostgreSQL</productname> application programming interface it
  57    uses.  With the <application>libpq</> library, the application issues
  58    <command>LISTEN</command> as an ordinary SQL command, and then must
  59    periodically call the function <function>PQnotifies</function> to find out
  60    whether any notification events have been received.  Other interfaces such as
  61    <application>libpgtcl</> provide higher-level methods for handling notify events; indeed,
  62    with <application>libpgtcl</> the application programmer should not even issue
  63    <command>LISTEN</command> or <command>UNLISTEN</command> directly.  See the
  64    documentation for the interface you are using for more details.
  65   </para>
  66
  67   <para>
  68    <xref linkend="sql-notify" endterm="sql-notify-title">
  69    contains a more extensive
  70    discussion of the use of <command>LISTEN</command> and
  71    <command>NOTIFY</command>.
  72   </para>
  73  </refsect1>
  74
  75  <refsect1>
  76   <title>Parameters</title>
  77
  78   <variablelist>
  79    <varlistentry>
  80     <term><replaceable class="PARAMETER">name</replaceable></term>
  81     <listitem>
  82      <para>
  83       Name of a notify condition (any identifier).
  84      </para>
  85     </listitem>
  86    </varlistentry>
  87   </variablelist>
  88  </refsect1>
  89
  90  <refsect1>
  91   <title>Examples</title>
  92
  93   <para>
  94    Configure and execute a listen/notify sequence from
  95    <application>psql</application>:
  96
  97 <programlisting>
  98 LISTEN virtual;
  99 NOTIFY virtual;
 100 Asynchronous notification "virtual" received from server process with PID 8448.
 101 </programlisting>
 102   </para>
 103  </refsect1>
 104
 105  <refsect1>
 106   <title>Compatibility</title>
 107
 108   <para>
 109    There is no <command>LISTEN</command> statement in the SQL
 110    standard.
 111   </para>
 112  </refsect1>
 113
 114  <refsect1>
 115   <title>See Also</title>
 116
 117   <simplelist type="inline">
 118    <member><xref linkend="sql-notify" endterm="sql-notify-title"></member>
 119    <member><xref linkend="sql-unlisten" endterm="sql-unlisten-title"></member>
 120   </simplelist>
 121  </refsect1>
 122 </refentry>