← Back to branch summary

~ubuntu-branches/ubuntu/precise/postgresql-9.1/precise-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/pltcl-functions.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

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