I386LINUX/util/I386LINUX/doc/postgresql/html/pltcl-functions.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >PL/Tcl Functions and Arguments</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="PL/Tcl - Tcl Procedural Language"
  16 HREF="pltcl.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="PL/Tcl - Tcl Procedural Language"
  19 HREF="pltcl.html"><LINK
  20 REL="NEXT"
  21 TITLE="Data Values in PL/Tcl"
  22 HREF="pltcl-data.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="SECT1"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="pltcl.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="pltcl.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 >Chapter 38. PL/Tcl - Tcl Procedural Language</TD
  68 ><TD
  69 WIDTH="10%"
  70 ALIGN="right"
  71 VALIGN="top"
  72 ><A
  73 HREF="pltcl.html"
  74 >Fast Forward</A
  75 ></TD
  76 ><TD
  77 WIDTH="10%"
  78 ALIGN="right"
  79 VALIGN="top"
  80 ><A
  81 HREF="pltcl-data.html"
  82 ACCESSKEY="N"
  83 >Next</A
  84 ></TD
  85 ></TR
  86 ></TABLE
  87 ><HR
  88 ALIGN="LEFT"
  89 WIDTH="100%"></DIV
  90 ><DIV
  91 CLASS="SECT1"
  92 ><H1
  93 CLASS="SECT1"
  94 ><A
  95 NAME="PLTCL-FUNCTIONS"
  96 >38.2. PL/Tcl Functions and Arguments</A
  97 ></H1
  98 ><P
  99 >     To create a function in the <SPAN
 100 CLASS="APPLICATION"
 101 >PL/Tcl</SPAN
 102 > language, use the standard syntax:
 103
 104 </P><PRE
 105 CLASS="PROGRAMLISTING"
 106 >CREATE FUNCTION <VAR
 107 CLASS="REPLACEABLE"
 108 >funcname</VAR
 109 > (<VAR
 110 CLASS="REPLACEABLE"
 111 >argument-types</VAR
 112 >) RETURNS <VAR
 113 CLASS="REPLACEABLE"
 114 >return-type</VAR
 115 > AS '
 116     # PL/Tcl function body
 117 ' LANGUAGE pltcl;</PRE
 118 ><P>
 119
 120      <SPAN
 121 CLASS="APPLICATION"
 122 >PL/TclU</SPAN
 123 > is the same, except that the language has to be specified as
 124      <TT
 125 CLASS="LITERAL"
 126 >pltclu</TT
 127 >.
 128     </P
 129 ><P
 130 >     The body of the function is simply a piece of Tcl script.
 131      When the function is called, the argument values are passed as
 132      variables <TT
 133 CLASS="LITERAL"
 134 >$1</TT
 135 > ... <TT
 136 CLASS="LITERAL"
 137 >$<VAR
 138 CLASS="REPLACEABLE"
 139 >n</VAR
 140 ></TT
 141 > to the
 142      Tcl script.  The result is returned
 143      from the Tcl code in the usual way, with a <TT
 144 CLASS="LITERAL"
 145 >return</TT
 146 >
 147      statement.
 148     </P
 149 ><P
 150 >     For example, a function
 151      returning the greater of two integer values could be defined as:
 152
 153 </P><PRE
 154 CLASS="PROGRAMLISTING"
 155 >CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS '
 156     if {$1 &#62; $2} {return $1}
 157     return $2
 158 ' LANGUAGE pltcl STRICT;</PRE
 159 ><P>
 160
 161      Note the clause <TT
 162 CLASS="LITERAL"
 163 >STRICT</TT
 164 >, which saves us from
 165      having to think about null input values: if a null value is passed, the
 166      function will not be called at all, but will just return a null
 167      result automatically.
 168     </P
 169 ><P
 170 >     In a nonstrict function,
 171      if the actual value of an argument is null, the corresponding
 172      <TT
 173 CLASS="LITERAL"
 174 >$<VAR
 175 CLASS="REPLACEABLE"
 176 >n</VAR
 177 ></TT
 178 > variable will be set to an empty string.
 179      To detect whether a particular argument is null, use the function
 180      <TT
 181 CLASS="LITERAL"
 182 >argisnull</TT
 183 >.  For example, suppose that we wanted <CODE
 184 CLASS="FUNCTION"
 185 >tcl_max</CODE
 186 >
 187      with one null and one nonnull argument to return the nonnull
 188      argument, rather than null:
 189
 190 </P><PRE
 191 CLASS="PROGRAMLISTING"
 192 >CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS '
 193     if {[argisnull 1]} {
 194         if {[argisnull 2]} { return_null }
 195         return $2
 196     }
 197     if {[argisnull 2]} { return $1 }
 198     if {$1 &#62; $2} {return $1}
 199     return $2
 200 ' LANGUAGE pltcl;</PRE
 201 ><P>
 202     </P
 203 ><P
 204 >     As shown above,
 205      to return a null value from a PL/Tcl function, execute
 206      <TT
 207 CLASS="LITERAL"
 208 >return_null</TT
 209 >.  This can be done whether the
 210      function is strict or not.
 211     </P
 212 ><P
 213 >     Composite-type arguments are passed to the function as Tcl
 214      arrays.  The element names of the array are the attribute names
 215      of the composite type. If an attribute in the passed row has the
 216      null value, it will not appear in the array. Here is an example:
 217
 218 </P><PRE
 219 CLASS="PROGRAMLISTING"
 220 >CREATE TABLE employee (
 221     name text,
 222     salary integer,
 223     age integer
 224 );
 225
 226 CREATE FUNCTION overpaid(employee) RETURNS boolean AS '
 227     if {200000.0 &#60; $1(salary)} {
 228         return "t"
 229     }
 230     if {$1(age) &#60; 30 &#38;&#38; 100000.0 &#60; $1(salary)} {
 231         return "t"
 232     }
 233     return "f"
 234 ' LANGUAGE pltcl;</PRE
 235 ><P>
 236     </P
 237 ><P
 238 >     There is currently no support for returning a composite-type
 239      result value.
 240     </P
 241 ></DIV
 242 ><DIV
 243 CLASS="NAVFOOTER"
 244 ><HR
 245 ALIGN="LEFT"
 246 WIDTH="100%"><TABLE
 247 SUMMARY="Footer navigation table"
 248 WIDTH="100%"
 249 BORDER="0"
 250 CELLPADDING="0"
 251 CELLSPACING="0"
 252 ><TR
 253 ><TD
 254 WIDTH="33%"
 255 ALIGN="left"
 256 VALIGN="top"
 257 ><A
 258 HREF="pltcl.html"
 259 ACCESSKEY="P"
 260 >Prev</A
 261 ></TD
 262 ><TD
 263 WIDTH="34%"
 264 ALIGN="center"
 265 VALIGN="top"
 266 ><A
 267 HREF="index.html"
 268 ACCESSKEY="H"
 269 >Home</A
 270 ></TD
 271 ><TD
 272 WIDTH="33%"
 273 ALIGN="right"
 274 VALIGN="top"
 275 ><A
 276 HREF="pltcl-data.html"
 277 ACCESSKEY="N"
 278 >Next</A
 279 ></TD
 280 ></TR
 281 ><TR
 282 ><TD
 283 WIDTH="33%"
 284 ALIGN="left"
 285 VALIGN="top"
 286 >PL/Tcl - Tcl Procedural Language</TD
 287 ><TD
 288 WIDTH="34%"
 289 ALIGN="center"
 290 VALIGN="top"
 291 ><A
 292 HREF="pltcl.html"
 293 ACCESSKEY="U"
 294 >Up</A
 295 ></TD
 296 ><TD
 297 WIDTH="33%"
 298 ALIGN="right"
 299 VALIGN="top"
 300 >Data Values in PL/Tcl</TD
 301 ></TR
 302 ></TABLE
 303 ></DIV
 304 ></BODY
 305 ></HTML
 306 >