Debian Codegraph @

doc/html/pgtcl-pglisten.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
3 <html>
4 <head>
5 <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.6.0">
6 <title>pg_listen</title>
7 <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
8 <link rev="MADE" href="mailto:[email protected]">
9 <link rel="HOME" title="PostgreSQL Tcl Interface Documentation" href="index.html">
10 <link rel="UP" title="pgtcl Command Reference" href="libpgtcl-ref.html">
11 <link rel="PREVIOUS" title="pg_execute" href="pgtcl-pgexecute.html">
12 <link rel="NEXT" title="pg_on_connection_loss" href="pgtcl-pgon-connection-loss.html">
13 <link rel="STYLESHEET" type="text/css" href="stylesheet.css">
14 </head>
15 <body class="REFENTRY">
16 <div class="NAVHEADER">
17 <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
18 <tr>
19 <th colspan="5" align="center" valign="bottom">PostgreSQL Tcl Interface Documentation</th>
20 </tr>
21 <tr>
22 <td width="10%" align="left" valign="top"><a href="pgtcl-pgexecute.html" accesskey="P">Prev</a></td>
23 <td width="10%" align="left" valign="top"><a href="pgtcl-pgexecute.html">Fast Backward</a></td>
24 <td width="60%" align="center" valign="bottom"></td>
25 <td width="10%" align="right" valign="top"><a href="pgtcl-pgon-connection-loss.html">Fast Forward</a></td>
26 <td width="10%" align="right" valign="top"><a href="pgtcl-pgon-connection-loss.html" accesskey="N">Next</a></td>
27 </tr>
28 </table>
29 <hr align="left" width="100%"></div>
30 <h1><a name="PGTCL-PGLISTEN" id="PGTCL-PGLISTEN"></a>pg_listen</h1>
31 <div class="REFNAMEDIV"><a name="AEN1398" id="AEN1398"></a>
32 <h2>Name</h2>
33 pg_listen&nbsp;--&nbsp;set or change a callback for asynchronous notification messages<a name="IX-PGTCL-PGLISTEN-2" id="IX-PGTCL-PGLISTEN-2"></a></div>
34 <div class="REFSYNOPSISDIV"><a name="AEN1403" id="AEN1403"></a>
35 <h2>Synopsis</h2>
36 <pre class="SYNOPSIS">pg_listen <code class="PARAMETER">conn</code> <code class="PARAMETER">notifyName</code> ?<span class="OPTIONAL"><code class="PARAMETER">callbackCommand</code></span>?</pre></div>
37 <div class="REFSECT1"><a name="AEN1409" id="AEN1409"></a>
38 <h2>Description</h2>
39 <p><code class="FUNCTION">pg_listen</code> creates, changes, or cancels a request to listen for asynchronous notification messages from the <span class="PRODUCTNAME">PostgreSQL</span> server. With a <code class="PARAMETER">callbackCommand</code> parameter, the request is established, or the command string of an already existing request is replaced. With no <code class="PARAMETER">callbackCommand</code> parameter, a prior request is canceled.</p>
40 <p>After a <code class="FUNCTION">pg_listen</code> request is established, the specified command string is executed whenever a notification message bearing the given name arrives from the server. This occurs when any <span class="PRODUCTNAME">PostgreSQL</span> client application issues a <tt class="COMMAND">NOTIFY</tt><a name="AEN1420" id="AEN1420"></a> command referencing that name. The command string is executed from the Tcl idle loop. That is the normal idle state of an application written with Tk. In non-Tk Tcl shells, you can execute <code class="FUNCTION">update</code> or <code class="FUNCTION">vwait</code> to cause the idle loop to be entered.</p>
41 <p>You should not invoke the SQL statements <tt class="COMMAND">LISTEN</tt> or <tt class="COMMAND">UNLISTEN</tt> directly when using <code class="FUNCTION">pg_listen</code>. <span class="APPLICATION">pgtcl</span> takes care of issuing those statements for you. But if you want to send a notification message yourself, invoke the SQL <tt class="COMMAND">NOTIFY</tt> statement using <code class="FUNCTION">pg_exec</code>.</p>
42 </div>
43 <div class="REFSECT1"><a name="AEN1432" id="AEN1432"></a>
44 <h2>Arguments</h2>
45 <div class="VARIABLELIST">
46 <dl>
47 <dt><code class="PARAMETER">conn</code></dt>
48 <dd>
49 <p>The handle of the connection on which to listen for notifications.</p>
50 </dd>
51 <dt><code class="PARAMETER">notifyName</code></dt>
52 <dd>
53 <p>The name of the notification condition to start or stop listening to.</p>
54 </dd>
55 <dt><code class="PARAMETER">callbackCommand</code></dt>
56 <dd>
57 <p>If present, provides the command string to execute when a matching notification arrives.</p>
58 </dd>
59 </dl>
60 </div>
61 </div>
62 <div class="REFSECT1"><a name="AEN1450" id="AEN1450"></a>
63 <h2>Return Value</h2>
64 <p>None</p>
65 </div>
66 <div class="NAVFOOTER">
67 <hr align="left" width="100%">
68 <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
69 <tr>
70 <td width="33%" align="left" valign="top"><a href="pgtcl-pgexecute.html" accesskey="P">Prev</a></td>
71 <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
72 <td width="33%" align="right" valign="top"><a href="pgtcl-pgon-connection-loss.html" accesskey="N">Next</a></td>
73 </tr>
74 <tr>
75 <td width="33%" align="left" valign="top">pg_execute</td>
76 <td width="34%" align="center" valign="top"><a href="libpgtcl-ref.html" accesskey="U">Up</a></td>
77 <td width="33%" align="right" valign="top">pg_on_connection_loss</td>
78 </tr>
79 </table>
80 </div>
81 </body>
82 </html>