codekingpro/portable-devtools

1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.6. Trigger Functions in PL/Tcl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-dbaccess.html" title="44.5. Database Access from PL/Tcl" /><link rel="next" href="pltcl-event-trigger.html" title="44.7. Event Trigger Functions in PL/Tcl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.6. Trigger Functions in PL/Tcl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-dbaccess.html" title="44.5. Database Access from PL/Tcl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-event-trigger.html" title="44.7. Event Trigger Functions in PL/Tcl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-TRIGGER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.6. Trigger Functions in PL/Tcl <a href="#PLTCL-TRIGGER" class="id_link">#</a></h2></div></div></div><a id="id-1.8.9.10.2" class="indexterm"></a><p>3     Trigger functions can be written in PL/Tcl.4     <span class="productname">PostgreSQL</span> requires that a function that is to be called5     as a trigger must be declared as a function with no arguments6     and a return type of <code class="literal">trigger</code>.7    </p><p>8     The information from the trigger manager is passed to the function body9     in the following variables:10 11     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">$TG_name</code></span></dt><dd><p>12         The name of the trigger from the <code class="command">CREATE TRIGGER</code> statement.13        </p></dd><dt><span class="term"><code class="varname">$TG_relid</code></span></dt><dd><p>14         The object ID of the table that caused the trigger function15         to be invoked.16        </p></dd><dt><span class="term"><code class="varname">$TG_table_name</code></span></dt><dd><p>17         The name of the table that caused the trigger function18         to be invoked.19        </p></dd><dt><span class="term"><code class="varname">$TG_table_schema</code></span></dt><dd><p>20         The schema of the table that caused the trigger function21         to be invoked.22        </p></dd><dt><span class="term"><code class="varname">$TG_relatts</code></span></dt><dd><p>23         A Tcl list of the table column names, prefixed with an empty list24         element. So looking up a column name in the list with <span class="application">Tcl</span>'s25         <code class="function">lsearch</code> command returns the element's number starting26         with 1 for the first column, the same way the columns are customarily27         numbered in <span class="productname">PostgreSQL</span>.  (Empty list28         elements also appear in the positions of columns that have been29         dropped, so that the attribute numbering is correct for columns30         to their right.)31        </p></dd><dt><span class="term"><code class="varname">$TG_when</code></span></dt><dd><p>32         The string <code class="literal">BEFORE</code>, <code class="literal">AFTER</code>, or33         <code class="literal">INSTEAD OF</code>, depending on the type of trigger event.34        </p></dd><dt><span class="term"><code class="varname">$TG_level</code></span></dt><dd><p>35         The string <code class="literal">ROW</code> or <code class="literal">STATEMENT</code> depending on the36         type of trigger event.37        </p></dd><dt><span class="term"><code class="varname">$TG_op</code></span></dt><dd><p>38         The string <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,39         <code class="literal">DELETE</code>, or <code class="literal">TRUNCATE</code> depending on the type of40         trigger event.41        </p></dd><dt><span class="term"><code class="varname">$NEW</code></span></dt><dd><p>42         An associative array containing the values of the new table43         row for <code class="command">INSERT</code> or <code class="command">UPDATE</code> actions, or44         empty for <code class="command">DELETE</code>.  The array is indexed by column45         name.  Columns that are null will not appear in the array.46         This is not set for statement-level triggers.47        </p></dd><dt><span class="term"><code class="varname">$OLD</code></span></dt><dd><p>48         An associative array containing the values of the old table49         row for <code class="command">UPDATE</code> or <code class="command">DELETE</code> actions, or50         empty for <code class="command">INSERT</code>.  The array is indexed by column51         name.  Columns that are null will not appear in the array.52         This is not set for statement-level triggers.53        </p></dd><dt><span class="term"><code class="varname">$args</code></span></dt><dd><p>54         A Tcl list of the arguments to the function as given in the55         <code class="command">CREATE TRIGGER</code> statement. These arguments are also accessible as56         <code class="literal">$1</code> ... <code class="literal">$<em class="replaceable"><code>n</code></em></code> in the function body.57        </p></dd></dl></div><p>58    </p><p>59     The return value from a trigger function can be one of the strings60     <code class="literal">OK</code> or <code class="literal">SKIP</code>, or a list of column name/value pairs.61     If the return value is <code class="literal">OK</code>,62     the operation (<code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code>)63     that fired the trigger will proceed64     normally. <code class="literal">SKIP</code> tells the trigger manager to silently suppress65     the operation for this row. If a list is returned, it tells PL/Tcl to66     return a modified row to the trigger manager; the contents of the67     modified row are specified by the column names and values in the list.68     Any columns not mentioned in the list are set to null.69     Returning a modified row is only meaningful70     for row-level <code class="literal">BEFORE</code> <code class="command">INSERT</code> or <code class="command">UPDATE</code>71     triggers, for which the modified row will be inserted instead of the one72     given in <code class="varname">$NEW</code>; or for row-level <code class="literal">INSTEAD OF</code>73     <code class="command">INSERT</code> or <code class="command">UPDATE</code> triggers where the returned row74     is used as the source data for <code class="command">INSERT RETURNING</code> or75     <code class="command">UPDATE RETURNING</code> clauses.76     In row-level <code class="literal">BEFORE</code> <code class="command">DELETE</code> or <code class="literal">INSTEAD77     OF</code> <code class="command">DELETE</code> triggers, returning a modified row has the same78     effect as returning <code class="literal">OK</code>, that is the operation proceeds.79     The trigger return value is ignored for all other types of triggers.80    </p><div class="tip"><h3 class="title">Tip</h3><p>81      The result list can be made from an array representation of the82      modified tuple with the <code class="literal">array get</code> Tcl command.83     </p></div><p>84     Here's a little example trigger function that forces an integer value85     in a table to keep track of the number of updates that are performed on the86     row. For new rows inserted, the value is initialized to 0 and then87     incremented on every update operation.88 89</p><pre class="programlisting">90CREATE FUNCTION trigfunc_modcount() RETURNS trigger AS $$91    switch $TG_op {92        INSERT {93            set NEW($1) 094        }95        UPDATE {96            set NEW($1) $OLD($1)97            incr NEW($1)98        }99        default {100            return OK101        }102    }103    return [array get NEW]104$$ LANGUAGE pltcl;105 106CREATE TABLE mytab (num integer, description text, modcnt integer);107 108CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab109    FOR EACH ROW EXECUTE FUNCTION trigfunc_modcount('modcnt');110</pre><p>111 112     Notice that the trigger function itself does not know the column113     name; that's supplied from the trigger arguments.  This lets the114     trigger function be reused with different tables.115    </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-dbaccess.html" title="44.5. Database Access from PL/Tcl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-event-trigger.html" title="44.7. Event Trigger Functions in PL/Tcl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.5. Database Access from PL/Tcl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.7. Event Trigger Functions in PL/Tcl</td></tr></table></div></body></html>