postgresql/doc/src/sgml/ref/unlisten.sgml

<REFENTRY ID="SQL-UNLISTEN">
<REFMETA>
<REFENTRYTITLE>
UNLISTEN
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
UNLISTEN
</REFNAME>
<REFPURPOSE>
Stop listening for notification
</REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-19</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
UNLISTEN { <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE> | * }
</SYNOPSIS>

<REFSECT2 ID="R2-SQL-UNLISTEN-1">
<REFSECT2INFO>
<DATE>1998-10-19</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Name of previously registered notify condition.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<literal>*</literal>
</TERM>
<LISTITEM>
<PARA>
All current listen registrations for this backend are cleared.
</para>
</listitem>
</varlistentry>

</VARIABLELIST>

</REFSECT2>

<REFSECT2 ID="R2-SQL-UNLISTEN-2">
<REFSECT2INFO>
<DATE>1998-10-19</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>UNLISTEN</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Acknowledgement that statement has executed.
</para>
</listitem>
</varlistentry>

</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-SQL-UNLISTEN-1">
<REFSECT1INFO>
<DATE>1998-10-19</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>UNLISTEN</command>
is used to remove an existing <command>NOTIFY</command> registration.
UNLISTEN cancels any existing registration of the current
<productname>Postgres</productname> session as a listener on the notify
condition <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>.
The special condition wildcard "*" cancels all listener registrations
for the current session.
</para>
<para>
<xref linkend="sql-notify" endterm="sql-notify-ref">
contains a more extensive
discussion of the use of <command>LISTEN</command> and
<command>NOTIFY</command>.
</para>

<REFSECT2 ID="R2-SQL-UNLISTEN-3">
<REFSECT2INFO>
<DATE>1998-10-19</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<para>
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
needs not to be a valid class name but can be any string valid
as a name up to 32 characters long.
</para>
<para>
The backend does not complain if you UNLISTEN something you were not
listening for.
Each backend will automatically execute <command>UNLISTEN *</command> when
exiting.
</para>
<para>
A restriction in some previous releases of
 <productname>Postgres</productname> that a
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
which does not correspond to an actual table must be enclosed in double-quotes
is no longer present.
</para>
</REFSECT2>
</refsect1>

<REFSECT1 ID="R1-SQL-UNLISTEN-2">
<TITLE>
Usage
</TITLE>

<para>
<programlisting>
postgres=> LISTEN virtual;
LISTEN
postgres=> NOTIFY virtual;
NOTIFY
ASYNC NOTIFY of 'virtual' from backend pid '12317' received
</programlisting>

<programlisting>
postgres=> UNLISTEN virtual;
UNLISTEN
postgres=> NOTIFY virtual;
NOTIFY
-- notice no NOTIFY event is received
postgres=>
</programlisting>
</para>
</REFSECT1>

<REFSECT1 ID="R1-SQL-UNLISTEN-3">
<TITLE>
Compatibility
</TITLE>

<REFSECT2 ID="R2-SQL-UNLISTEN-4">
<REFSECT2INFO>
<DATE>1998-10-19</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
   There is no <command>UNLISTEN</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY>