| <!-- |
| $PostgreSQL: pgsql/doc/src/sgml/ref/unlisten.sgml,v 1.30 2008/11/14 10:22:47 petere Exp $ |
| PostgreSQL documentation |
| --> |
| |
| <refentry id="SQL-UNLISTEN"> |
| <refmeta> |
| <refentrytitle id="SQL-UNLISTEN-TITLE">UNLISTEN</refentrytitle> |
| <manvolnum>7</manvolnum> |
| <refmiscinfo>SQL - Language Statements</refmiscinfo> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>UNLISTEN</refname> |
| <refpurpose>stop listening for a notification</refpurpose> |
| </refnamediv> |
| |
| <indexterm zone="sql-unlisten"> |
| <primary>UNLISTEN</primary> |
| </indexterm> |
| |
| <refsynopsisdiv> |
| <synopsis> |
| UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * } |
| </synopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para> |
| <command>UNLISTEN</command> is used to remove an existing |
| registration for <command>NOTIFY</command> events. |
| <command>UNLISTEN</command> cancels any existing registration of |
| the current <productname>PostgreSQL</productname> session as a |
| listener on the notification <replaceable |
| class="PARAMETER">name</replaceable>. The special wildcard |
| <literal>*</literal> cancels all listener registrations for the |
| current session. |
| </para> |
| |
| <para> |
| <xref endterm="sql-notify-title" linkend="sql-notify"> |
| contains a more extensive |
| discussion of the use of <command>LISTEN</command> and |
| <command>NOTIFY</command>. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Parameters</title> |
| |
| <variablelist> |
| <varlistentry> |
| <term><replaceable class="PARAMETER">name</replaceable></term> |
| <listitem> |
| <para> |
| Name of a notification (any identifier). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>*</literal></term> |
| <listitem> |
| <para> |
| All current listen registrations for this session are cleared. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Notes</title> |
| |
| <para> |
| You can unlisten something you were not listening for; no warning or error |
| will appear. |
| </para> |
| |
| <para> |
| At the end of each session, <command>UNLISTEN *</command> is |
| automatically executed. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Examples</title> |
| |
| <para> |
| To make a registration: |
| |
| <programlisting> |
| LISTEN virtual; |
| NOTIFY virtual; |
| Asynchronous notification "virtual" received from server process with PID 8448. |
| </programlisting> |
| </para> |
| |
| <para> |
| Once <command>UNLISTEN</> has been executed, further <command>NOTIFY</> |
| commands will be ignored: |
| |
| <programlisting> |
| UNLISTEN virtual; |
| NOTIFY virtual; |
| -- no NOTIFY event is received |
| </programlisting> |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Compatibility</title> |
| |
| <para> |
| There is no <command>UNLISTEN</command> command in the SQL standard. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| |
| <simplelist type="inline"> |
| <member><xref linkend="sql-listen" endterm="sql-listen-title"></member> |
| <member><xref linkend="sql-notify" endterm="sql-notify-title"></member> |
| </simplelist> |
| </refsect1> |
| </refentry> |