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.2. PL/Tcl Functions and Arguments</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-overview.html" title="44.1. Overview" /><link rel="next" href="pltcl-data.html" title="44.3. Data Values 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.2. PL/Tcl Functions and Arguments</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-overview.html" title="44.1. Overview">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-data.html" title="44.3. Data Values in PL/Tcl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-FUNCTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.2. PL/Tcl Functions and Arguments <a href="#PLTCL-FUNCTIONS" class="id_link">#</a></h2></div></div></div><p>3     To create a function in the <span class="application">PL/Tcl</span> language, use4     the standard <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> syntax:5 6</p><pre class="programlisting">7CREATE FUNCTION <em class="replaceable"><code>funcname</code></em> (<em class="replaceable"><code>argument-types</code></em>) RETURNS <em class="replaceable"><code>return-type</code></em> AS $$8    # PL/Tcl function body9$$ LANGUAGE pltcl;10</pre><p>11 12     <span class="application">PL/TclU</span> is the same, except that the language has to be specified as13     <code class="literal">pltclu</code>.14    </p><p>15     The body of the function is simply a piece of Tcl script.16     When the function is called, the argument values are passed to the17     Tcl script as variables named <code class="literal">1</code>18     ... <code class="literal"><em class="replaceable"><code>n</code></em></code>.  The result is19     returned from the Tcl code in the usual way, with20     a <code class="literal">return</code> statement.  In a procedure, the return value21     from the Tcl code is ignored.22    </p><p>23     For example, a function24     returning the greater of two integer values could be defined as:25 26</p><pre class="programlisting">27CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS $$28    if {$1 &gt; $2} {return $1}29    return $230$$ LANGUAGE pltcl STRICT;31</pre><p>32 33     Note the clause <code class="literal">STRICT</code>, which saves us from34     having to think about null input values: if a null value is passed, the35     function will not be called at all, but will just return a null36     result automatically.37    </p><p>38     In a nonstrict function,39     if the actual value of an argument is null, the corresponding40     <code class="literal">$<em class="replaceable"><code>n</code></em></code> variable will be set to an empty string.41     To detect whether a particular argument is null, use the function42     <code class="literal">argisnull</code>.  For example, suppose that we wanted <code class="function">tcl_max</code>43     with one null and one nonnull argument to return the nonnull44     argument, rather than null:45 46</p><pre class="programlisting">47CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS $$48    if {[argisnull 1]} {49        if {[argisnull 2]} { return_null }50        return $251    }52    if {[argisnull 2]} { return $1 }53    if {$1 &gt; $2} {return $1}54    return $255$$ LANGUAGE pltcl;56</pre><p>57    </p><p>58     As shown above,59     to return a null value from a PL/Tcl function, execute60     <code class="literal">return_null</code>.  This can be done whether the61     function is strict or not.62    </p><p>63     Composite-type arguments are passed to the function as Tcl64     arrays.  The element names of the array are the attribute names65     of the composite type. If an attribute in the passed row has the66     null value, it will not appear in the array. Here is an example:67 68</p><pre class="programlisting">69CREATE TABLE employee (70    name text,71    salary integer,72    age integer73);74 75CREATE FUNCTION overpaid(employee) RETURNS boolean AS $$76    if {200000.0 &lt; $1(salary)} {77        return "t"78    }79    if {$1(age) &lt; 30 &amp;&amp; 100000.0 &lt; $1(salary)} {80        return "t"81    }82    return "f"83$$ LANGUAGE pltcl;84</pre><p>85    </p><p>86     PL/Tcl functions can return composite-type results, too.  To do this,87     the Tcl code must return a list of column name/value pairs matching88     the expected result type.  Any column names omitted from the list89     are returned as nulls, and an error is raised if there are unexpected90     column names.  Here is an example:91 92</p><pre class="programlisting">93CREATE FUNCTION square_cube(in int, out squared int, out cubed int) AS $$94    return [list squared [expr {$1 * $1}] cubed [expr {$1 * $1 * $1}]]95$$ LANGUAGE pltcl;96</pre><p>97    </p><p>98     Output arguments of procedures are returned in the same way, for example:99 100</p><pre class="programlisting">101CREATE PROCEDURE tcl_triple(INOUT a integer, INOUT b integer) AS $$102    return [list a [expr {$1 * 3}] b [expr {$2 * 3}]]103$$ LANGUAGE pltcl;104 105CALL tcl_triple(5, 10);106</pre><p>107    </p><div class="tip"><h3 class="title">Tip</h3><p>108      The result list can be made from an array representation of the109      desired tuple with the <code class="literal">array get</code> Tcl command.  For example:110 111</p><pre class="programlisting">112CREATE FUNCTION raise_pay(employee, delta int) RETURNS employee AS $$113    set 1(salary) [expr {$1(salary) + $2}]114    return [array get 1]115$$ LANGUAGE pltcl;116</pre><p>117     </p></div><p>118     PL/Tcl functions can return sets.  To do this, the Tcl code should119     call <code class="function">return_next</code> once per row to be returned,120     passing either the appropriate value when returning a scalar type,121     or a list of column name/value pairs when returning a composite type.122     Here is an example returning a scalar type:123 124</p><pre class="programlisting">125CREATE FUNCTION sequence(int, int) RETURNS SETOF int AS $$126    for {set i $1} {$i &lt; $2} {incr i} {127        return_next $i128    }129$$ LANGUAGE pltcl;130</pre><p>131 132     and here is one returning a composite type:133 134</p><pre class="programlisting">135CREATE FUNCTION table_of_squares(int, int) RETURNS TABLE (x int, x2 int) AS $$136    for {set i $1} {$i &lt; $2} {incr i} {137        return_next [list x $i x2 [expr {$i * $i}]]138    }139$$ LANGUAGE pltcl;140</pre><p>141    </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-overview.html" title="44.1. Overview">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-data.html" title="44.3. Data Values in PL/Tcl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.1. Overview </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.3. Data Values in PL/Tcl</td></tr></table></div></body></html>