← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/listen.sgml

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/listen.sgml
 
1
<!--
 
2
$PostgreSQL: pgsql/doc/src/sgml/ref/listen.sgml,v 1.21 2003-11-29 19:51:39 pgsql Exp $
 
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>
 
123
 
 
124
<!-- Keep this comment at the end of the file
 
125
Local variables:
 
126
mode: sgml
 
127
sgml-omittag:nil
 
128
sgml-shorttag:t
 
129
sgml-minimize-attributes:nil
 
130
sgml-always-quote-attributes:t
 
131
sgml-indent-step:1
 
132
sgml-indent-data:t
 
133
sgml-parent-document:nil
 
134
sgml-default-dtd-file:"../reference.ced"
 
135
sgml-exposed-tags:nil
 
136
sgml-local-catalogs:"/usr/lib/sgml/catalog"
 
137
sgml-local-ecat-files:nil
 
138
End:
 
139
-->