← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/plpgsql-declarations.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/plpgsql-declarations.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
>Declarations</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/pgSQL - SQL Procedural Language"
 
16
HREF="plpgsql.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Structure of PL/pgSQL"
 
19
HREF="plpgsql-structure.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="Expressions"
 
22
HREF="plpgsql-expressions.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="Structure of PL/pgSQL"
 
57
HREF="plpgsql-structure.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/pgSQL - SQL Procedural Language"
 
67
HREF="plpgsql.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
>Chapter 39. <SPAN
 
75
CLASS="APPLICATION"
 
76
>PL/pgSQL</SPAN
 
77
> - <ACRONYM
 
78
CLASS="ACRONYM"
 
79
>SQL</ACRONYM
 
80
> Procedural Language</TD
 
81
><TD
 
82
WIDTH="10%"
 
83
ALIGN="right"
 
84
VALIGN="top"
 
85
><A
 
86
TITLE="PL/pgSQL - SQL Procedural Language"
 
87
HREF="plpgsql.html"
 
88
>Fast Forward</A
 
89
></TD
 
90
><TD
 
91
WIDTH="10%"
 
92
ALIGN="right"
 
93
VALIGN="top"
 
94
><A
 
95
TITLE="Expressions"
 
96
HREF="plpgsql-expressions.html"
 
97
ACCESSKEY="N"
 
98
>Next</A
 
99
></TD
 
100
></TR
 
101
></TABLE
 
102
><HR
 
103
ALIGN="LEFT"
 
104
WIDTH="100%"></DIV
 
105
><DIV
 
106
CLASS="SECT1"
 
107
><H1
 
108
CLASS="SECT1"
 
109
><A
 
110
NAME="PLPGSQL-DECLARATIONS"
 
111
>39.3. Declarations</A
 
112
></H1
 
113
><P
 
114
>     All variables used in a block must be declared in the
 
115
     declarations section of the block.
 
116
     (The only exceptions are that the loop variable of a <TT
 
117
CLASS="LITERAL"
 
118
>FOR</TT
 
119
> loop
 
120
     iterating over a range of integer values is automatically declared as an
 
121
     integer variable, and likewise the loop variable of a <TT
 
122
CLASS="LITERAL"
 
123
>FOR</TT
 
124
> loop
 
125
     iterating over a cursor's result is automatically declared as a
 
126
     record variable.)
 
127
    </P
 
128
><P
 
129
>     <SPAN
 
130
CLASS="APPLICATION"
 
131
>PL/pgSQL</SPAN
 
132
> variables can have any SQL data type, such as
 
133
     <TT
 
134
CLASS="TYPE"
 
135
>integer</TT
 
136
>, <TT
 
137
CLASS="TYPE"
 
138
>varchar</TT
 
139
>, and
 
140
     <TT
 
141
CLASS="TYPE"
 
142
>char</TT
 
143
>.
 
144
    </P
 
145
><P
 
146
>     Here are some examples of variable declarations:
 
147
</P><PRE
 
148
CLASS="PROGRAMLISTING"
 
149
>user_id integer;
 
150
quantity numeric(5);
 
151
url varchar;
 
152
myrow tablename%ROWTYPE;
 
153
myfield tablename.columnname%TYPE;
 
154
arow RECORD;</PRE
 
155
><P>
 
156
    </P
 
157
><P
 
158
>     The general syntax of a variable declaration is:
 
159
</P><PRE
 
160
CLASS="SYNOPSIS"
 
161
><TT
 
162
CLASS="REPLACEABLE"
 
163
><I
 
164
>name</I
 
165
></TT
 
166
> [<SPAN
 
167
CLASS="OPTIONAL"
 
168
> CONSTANT </SPAN
 
169
>] <TT
 
170
CLASS="REPLACEABLE"
 
171
><I
 
172
>type</I
 
173
></TT
 
174
> [<SPAN
 
175
CLASS="OPTIONAL"
 
176
> COLLATE <TT
 
177
CLASS="REPLACEABLE"
 
178
><I
 
179
>collation_name</I
 
180
></TT
 
181
> </SPAN
 
182
>] [<SPAN
 
183
CLASS="OPTIONAL"
 
184
> NOT NULL </SPAN
 
185
>] [<SPAN
 
186
CLASS="OPTIONAL"
 
187
> { DEFAULT | := } <TT
 
188
CLASS="REPLACEABLE"
 
189
><I
 
190
>expression</I
 
191
></TT
 
192
> </SPAN
 
193
>];</PRE
 
194
><P>
 
195
      The <TT
 
196
CLASS="LITERAL"
 
197
>DEFAULT</TT
 
198
> clause, if given, specifies the initial value assigned
 
199
      to the variable when the block is entered.  If the <TT
 
200
CLASS="LITERAL"
 
201
>DEFAULT</TT
 
202
> clause
 
203
      is not given then the variable is initialized to the
 
204
      <ACRONYM
 
205
CLASS="ACRONYM"
 
206
>SQL</ACRONYM
 
207
> null value.
 
208
      The <TT
 
209
CLASS="LITERAL"
 
210
>CONSTANT</TT
 
211
> option prevents the variable from being
 
212
      assigned to after initialization, so that its value will remain constant
 
213
      for the duration of the block.
 
214
      The <TT
 
215
CLASS="LITERAL"
 
216
>COLLATE</TT
 
217
> option specifies a collation to use for the
 
218
      variable (see <A
 
219
HREF="plpgsql-declarations.html#PLPGSQL-DECLARATION-COLLATION"
 
220
>Section 39.3.6</A
 
221
>).
 
222
      If <TT
 
223
CLASS="LITERAL"
 
224
>NOT NULL</TT
 
225
>
 
226
      is specified, an assignment of a null value results in a run-time
 
227
      error. All variables declared as <TT
 
228
CLASS="LITERAL"
 
229
>NOT NULL</TT
 
230
>
 
231
      must have a nonnull default value specified.
 
232
     </P
 
233
><P
 
234
>      A variable's default value is evaluated and assigned to the variable
 
235
      each time the block is entered (not just once per function call).
 
236
      So, for example, assigning <TT
 
237
CLASS="LITERAL"
 
238
>now()</TT
 
239
> to a variable of type
 
240
      <TT
 
241
CLASS="TYPE"
 
242
>timestamp</TT
 
243
> causes the variable to have the
 
244
      time of the current function call, not the time when the function was
 
245
      precompiled.
 
246
     </P
 
247
><P
 
248
>      Examples:
 
249
</P><PRE
 
250
CLASS="PROGRAMLISTING"
 
251
>quantity integer DEFAULT 32;
 
252
url varchar := 'http://mysite.com';
 
253
user_id CONSTANT integer := 10;</PRE
 
254
><P>
 
255
     </P
 
256
><DIV
 
257
CLASS="SECT2"
 
258
><H2
 
259
CLASS="SECT2"
 
260
><A
 
261
NAME="PLPGSQL-DECLARATION-PARAMETERS"
 
262
>39.3.1. Declaring Function Parameters</A
 
263
></H2
 
264
><P
 
265
>      Parameters passed to functions are named with the identifiers
 
266
      <TT
 
267
CLASS="LITERAL"
 
268
>$1</TT
 
269
>, <TT
 
270
CLASS="LITERAL"
 
271
>$2</TT
 
272
>,
 
273
      etc.  Optionally, aliases can be declared for
 
274
      <TT
 
275
CLASS="LITERAL"
 
276
>$<TT
 
277
CLASS="REPLACEABLE"
 
278
><I
 
279
>n</I
 
280
></TT
 
281
></TT
 
282
>
 
283
      parameter names for increased readability.  Either the alias or the
 
284
      numeric identifier can then be used to refer to the parameter value.
 
285
     </P
 
286
><P
 
287
>      There are two ways to create an alias.  The preferred way is to give a
 
288
      name to the parameter in the <TT
 
289
CLASS="COMMAND"
 
290
>CREATE FUNCTION</TT
 
291
> command,
 
292
      for example:
 
293
</P><PRE
 
294
CLASS="PROGRAMLISTING"
 
295
>CREATE FUNCTION sales_tax(subtotal real) RETURNS real AS $$
 
296
BEGIN
 
297
    RETURN subtotal * 0.06;
 
298
END;
 
299
$$ LANGUAGE plpgsql;</PRE
 
300
><P>
 
301
      The other way, which was the only way available before
 
302
      <SPAN
 
303
CLASS="PRODUCTNAME"
 
304
>PostgreSQL</SPAN
 
305
> 8.0, is to explicitly
 
306
      declare an alias, using the declaration syntax
 
307
 
 
308
</P><PRE
 
309
CLASS="SYNOPSIS"
 
310
><TT
 
311
CLASS="REPLACEABLE"
 
312
><I
 
313
>name</I
 
314
></TT
 
315
> ALIAS FOR $<TT
 
316
CLASS="REPLACEABLE"
 
317
><I
 
318
>n</I
 
319
></TT
 
320
>;</PRE
 
321
><P>
 
322
 
 
323
      The same example in this style looks like:
 
324
</P><PRE
 
325
CLASS="PROGRAMLISTING"
 
326
>CREATE FUNCTION sales_tax(real) RETURNS real AS $$
 
327
DECLARE
 
328
    subtotal ALIAS FOR $1;
 
329
BEGIN
 
330
    RETURN subtotal * 0.06;
 
331
END;
 
332
$$ LANGUAGE plpgsql;</PRE
 
333
><P>
 
334
     </P
 
335
><DIV
 
336
CLASS="NOTE"
 
337
><BLOCKQUOTE
 
338
CLASS="NOTE"
 
339
><P
 
340
><B
 
341
>Note: </B
 
342
>      These two examples are not perfectly equivalent.  In the first case,
 
343
      <TT
 
344
CLASS="LITERAL"
 
345
>subtotal</TT
 
346
> could be referenced as
 
347
      <TT
 
348
CLASS="LITERAL"
 
349
>sales_tax.subtotal</TT
 
350
>, but in the second case it could not.
 
351
      (Had we attached a label to the inner block, <TT
 
352
CLASS="LITERAL"
 
353
>subtotal</TT
 
354
> could
 
355
      be qualified with that label, instead.)
 
356
     </P
 
357
></BLOCKQUOTE
 
358
></DIV
 
359
><P
 
360
>      Some more examples:
 
361
</P><PRE
 
362
CLASS="PROGRAMLISTING"
 
363
>CREATE FUNCTION instr(varchar, integer) RETURNS integer AS $$
 
364
DECLARE
 
365
    v_string ALIAS FOR $1;
 
366
    index ALIAS FOR $2;
 
367
BEGIN
 
368
    -- some computations using v_string and index here
 
369
END;
 
370
$$ LANGUAGE plpgsql;
 
371
 
 
372
 
 
373
CREATE FUNCTION concat_selected_fields(in_t sometablename) RETURNS text AS $$
 
374
BEGIN
 
375
    RETURN in_t.f1 || in_t.f3 || in_t.f5 || in_t.f7;
 
376
END;
 
377
$$ LANGUAGE plpgsql;</PRE
 
378
><P>
 
379
     </P
 
380
><P
 
381
>      When a <SPAN
 
382
CLASS="APPLICATION"
 
383
>PL/pgSQL</SPAN
 
384
> function is declared
 
385
      with output parameters, the output parameters are given
 
386
      <TT
 
387
CLASS="LITERAL"
 
388
>$<TT
 
389
CLASS="REPLACEABLE"
 
390
><I
 
391
>n</I
 
392
></TT
 
393
></TT
 
394
> names and optional
 
395
      aliases in just the same way as the normal input parameters.  An
 
396
      output parameter is effectively a variable that starts out NULL;
 
397
      it should be assigned to during the execution of the function.
 
398
      The final value of the parameter is what is returned.  For instance,
 
399
      the sales-tax example could also be done this way:
 
400
 
 
401
</P><PRE
 
402
CLASS="PROGRAMLISTING"
 
403
>CREATE FUNCTION sales_tax(subtotal real, OUT tax real) AS $$
 
404
BEGIN
 
405
    tax := subtotal * 0.06;
 
406
END;
 
407
$$ LANGUAGE plpgsql;</PRE
 
408
><P>
 
409
 
 
410
      Notice that we omitted <TT
 
411
CLASS="LITERAL"
 
412
>RETURNS real</TT
 
413
> &mdash; we could have
 
414
      included it, but it would be redundant.
 
415
     </P
 
416
><P
 
417
>      Output parameters are most useful when returning multiple values.
 
418
      A trivial example is:
 
419
 
 
420
</P><PRE
 
421
CLASS="PROGRAMLISTING"
 
422
>CREATE FUNCTION sum_n_product(x int, y int, OUT sum int, OUT prod int) AS $$
 
423
BEGIN
 
424
    sum := x + y;
 
425
    prod := x * y;
 
426
END;
 
427
$$ LANGUAGE plpgsql;</PRE
 
428
><P>
 
429
 
 
430
      As discussed in <A
 
431
HREF="xfunc-sql.html#XFUNC-OUTPUT-PARAMETERS"
 
432
>Section 35.4.4</A
 
433
>, this
 
434
      effectively creates an anonymous record type for the function's
 
435
      results.  If a <TT
 
436
CLASS="LITERAL"
 
437
>RETURNS</TT
 
438
> clause is given, it must say
 
439
      <TT
 
440
CLASS="LITERAL"
 
441
>RETURNS record</TT
 
442
>.
 
443
     </P
 
444
><P
 
445
>      Another way to declare a <SPAN
 
446
CLASS="APPLICATION"
 
447
>PL/pgSQL</SPAN
 
448
> function
 
449
      is with <TT
 
450
CLASS="LITERAL"
 
451
>RETURNS TABLE</TT
 
452
>, for example:
 
453
 
 
454
</P><PRE
 
455
CLASS="PROGRAMLISTING"
 
456
>CREATE FUNCTION extended_sales(p_itemno int)
 
457
RETURNS TABLE(quantity int, total numeric) AS $$
 
458
BEGIN
 
459
    RETURN QUERY SELECT quantity, quantity * price FROM sales
 
460
                 WHERE itemno = p_itemno;
 
461
END;
 
462
$$ LANGUAGE plpgsql;</PRE
 
463
><P>
 
464
 
 
465
      This is exactly equivalent to declaring one or more <TT
 
466
CLASS="LITERAL"
 
467
>OUT</TT
 
468
>
 
469
      parameters and specifying <TT
 
470
CLASS="LITERAL"
 
471
>RETURNS SETOF
 
472
      <TT
 
473
CLASS="REPLACEABLE"
 
474
><I
 
475
>sometype</I
 
476
></TT
 
477
></TT
 
478
>.
 
479
     </P
 
480
><P
 
481
>      When the return type of a <SPAN
 
482
CLASS="APPLICATION"
 
483
>PL/pgSQL</SPAN
 
484
>
 
485
      function is declared as a polymorphic type (<TT
 
486
CLASS="TYPE"
 
487
>anyelement</TT
 
488
>,
 
489
      <TT
 
490
CLASS="TYPE"
 
491
>anyarray</TT
 
492
>, <TT
 
493
CLASS="TYPE"
 
494
>anynonarray</TT
 
495
>, or <TT
 
496
CLASS="TYPE"
 
497
>anyenum</TT
 
498
>),
 
499
      a special parameter <TT
 
500
CLASS="LITERAL"
 
501
>$0</TT
 
502
>
 
503
      is created.  Its data type is the actual return type of the function,
 
504
      as deduced from the actual input types (see <A
 
505
HREF="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC"
 
506
>Section 35.2.5</A
 
507
>).
 
508
      This allows the function to access its actual return type
 
509
      as shown in <A
 
510
HREF="plpgsql-declarations.html#PLPGSQL-DECLARATION-TYPE"
 
511
>Section 39.3.3</A
 
512
>.
 
513
      <TT
 
514
CLASS="LITERAL"
 
515
>$0</TT
 
516
> is initialized to null and can be modified by
 
517
      the function, so it can be used to hold the return value if desired,
 
518
      though that is not required.  <TT
 
519
CLASS="LITERAL"
 
520
>$0</TT
 
521
> can also be
 
522
      given an alias.  For example, this function works on any data type
 
523
      that has a <TT
 
524
CLASS="LITERAL"
 
525
>+</TT
 
526
> operator:
 
527
 
 
528
</P><PRE
 
529
CLASS="PROGRAMLISTING"
 
530
>CREATE FUNCTION add_three_values(v1 anyelement, v2 anyelement, v3 anyelement)
 
531
RETURNS anyelement AS $$
 
532
DECLARE
 
533
    result ALIAS FOR $0;
 
534
BEGIN
 
535
    result := v1 + v2 + v3;
 
536
    RETURN result;
 
537
END;
 
538
$$ LANGUAGE plpgsql;</PRE
 
539
><P>
 
540
     </P
 
541
><P
 
542
>      The same effect can be had by declaring one or more output parameters as
 
543
      polymorphic types.  In this case the
 
544
      special <TT
 
545
CLASS="LITERAL"
 
546
>$0</TT
 
547
> parameter is not used; the output
 
548
      parameters themselves serve the same purpose.  For example:
 
549
 
 
550
</P><PRE
 
551
CLASS="PROGRAMLISTING"
 
552
>CREATE FUNCTION add_three_values(v1 anyelement, v2 anyelement, v3 anyelement,
 
553
                                 OUT sum anyelement)
 
554
AS $$
 
555
BEGIN
 
556
    sum := v1 + v2 + v3;
 
557
END;
 
558
$$ LANGUAGE plpgsql;</PRE
 
559
><P>
 
560
     </P
 
561
></DIV
 
562
><DIV
 
563
CLASS="SECT2"
 
564
><H2
 
565
CLASS="SECT2"
 
566
><A
 
567
NAME="PLPGSQL-DECLARATION-ALIAS"
 
568
>39.3.2. <TT
 
569
CLASS="LITERAL"
 
570
>ALIAS</TT
 
571
></A
 
572
></H2
 
573
><PRE
 
574
CLASS="SYNOPSIS"
 
575
><TT
 
576
CLASS="REPLACEABLE"
 
577
><I
 
578
>newname</I
 
579
></TT
 
580
> ALIAS FOR <TT
 
581
CLASS="REPLACEABLE"
 
582
><I
 
583
>oldname</I
 
584
></TT
 
585
>;</PRE
 
586
><P
 
587
>    The <TT
 
588
CLASS="LITERAL"
 
589
>ALIAS</TT
 
590
> syntax is more general than is suggested in the
 
591
    previous section: you can declare an alias for any variable, not just
 
592
    function parameters.  The main practical use for this is to assign
 
593
    a different name for variables with predetermined names, such as
 
594
    <TT
 
595
CLASS="VARNAME"
 
596
>NEW</TT
 
597
> or <TT
 
598
CLASS="VARNAME"
 
599
>OLD</TT
 
600
> within
 
601
    a trigger procedure.
 
602
   </P
 
603
><P
 
604
>    Examples:
 
605
</P><PRE
 
606
CLASS="PROGRAMLISTING"
 
607
>DECLARE
 
608
  prior ALIAS FOR old;
 
609
  updated ALIAS FOR new;</PRE
 
610
><P>
 
611
   </P
 
612
><P
 
613
>    Since <TT
 
614
CLASS="LITERAL"
 
615
>ALIAS</TT
 
616
> creates two different ways to name the same
 
617
    object, unrestricted use can be confusing.  It's best to use it only
 
618
    for the purpose of overriding predetermined names.
 
619
   </P
 
620
></DIV
 
621
><DIV
 
622
CLASS="SECT2"
 
623
><H2
 
624
CLASS="SECT2"
 
625
><A
 
626
NAME="PLPGSQL-DECLARATION-TYPE"
 
627
>39.3.3. Copying Types</A
 
628
></H2
 
629
><PRE
 
630
CLASS="SYNOPSIS"
 
631
><TT
 
632
CLASS="REPLACEABLE"
 
633
><I
 
634
>variable</I
 
635
></TT
 
636
>%TYPE</PRE
 
637
><P
 
638
>    <TT
 
639
CLASS="LITERAL"
 
640
>%TYPE</TT
 
641
> provides the data type of a variable or
 
642
    table column. You can use this to declare variables that will hold
 
643
    database values. For example, let's say you have a column named
 
644
    <TT
 
645
CLASS="LITERAL"
 
646
>user_id</TT
 
647
> in your <TT
 
648
CLASS="LITERAL"
 
649
>users</TT
 
650
>
 
651
    table. To declare a variable with the same data type as
 
652
    <TT
 
653
CLASS="LITERAL"
 
654
>users.user_id</TT
 
655
> you write:
 
656
</P><PRE
 
657
CLASS="PROGRAMLISTING"
 
658
>user_id users.user_id%TYPE;</PRE
 
659
><P>
 
660
   </P
 
661
><P
 
662
>    By using <TT
 
663
CLASS="LITERAL"
 
664
>%TYPE</TT
 
665
> you don't need to know the data
 
666
    type of the structure you are referencing, and most importantly,
 
667
    if the data type of the referenced item changes in the future (for
 
668
    instance: you change the type of <TT
 
669
CLASS="LITERAL"
 
670
>user_id</TT
 
671
>
 
672
    from <TT
 
673
CLASS="TYPE"
 
674
>integer</TT
 
675
> to <TT
 
676
CLASS="TYPE"
 
677
>real</TT
 
678
>), you might not need
 
679
    to change your function definition.
 
680
   </P
 
681
><P
 
682
>    <TT
 
683
CLASS="LITERAL"
 
684
>%TYPE</TT
 
685
> is particularly valuable in polymorphic
 
686
    functions, since the data types needed for internal variables can
 
687
    change from one call to the next.  Appropriate variables can be
 
688
    created by applying <TT
 
689
CLASS="LITERAL"
 
690
>%TYPE</TT
 
691
> to the function's
 
692
    arguments or result placeholders.
 
693
   </P
 
694
></DIV
 
695
><DIV
 
696
CLASS="SECT2"
 
697
><H2
 
698
CLASS="SECT2"
 
699
><A
 
700
NAME="PLPGSQL-DECLARATION-ROWTYPES"
 
701
>39.3.4. Row Types</A
 
702
></H2
 
703
><PRE
 
704
CLASS="SYNOPSIS"
 
705
><TT
 
706
CLASS="REPLACEABLE"
 
707
><I
 
708
>name</I
 
709
></TT
 
710
> <TT
 
711
CLASS="REPLACEABLE"
 
712
><I
 
713
>table_name</I
 
714
></TT
 
715
><TT
 
716
CLASS="LITERAL"
 
717
>%ROWTYPE</TT
 
718
>;
 
719
<TT
 
720
CLASS="REPLACEABLE"
 
721
><I
 
722
>name</I
 
723
></TT
 
724
> <TT
 
725
CLASS="REPLACEABLE"
 
726
><I
 
727
>composite_type_name</I
 
728
></TT
 
729
>;</PRE
 
730
><P
 
731
>    A variable of a composite type is called a <I
 
732
CLASS="FIRSTTERM"
 
733
>row</I
 
734
>
 
735
    variable (or <I
 
736
CLASS="FIRSTTERM"
 
737
>row-type</I
 
738
> variable).  Such a variable
 
739
    can hold a whole row of a <TT
 
740
CLASS="COMMAND"
 
741
>SELECT</TT
 
742
> or <TT
 
743
CLASS="COMMAND"
 
744
>FOR</TT
 
745
>
 
746
    query result, so long as that query's column set matches the
 
747
    declared type of the variable.
 
748
    The individual fields of the row value
 
749
    are accessed using the usual dot notation, for example
 
750
    <TT
 
751
CLASS="LITERAL"
 
752
>rowvar.field</TT
 
753
>.
 
754
   </P
 
755
><P
 
756
>    A row variable can be declared to have the same type as the rows of
 
757
    an existing table or view, by using the
 
758
    <TT
 
759
CLASS="REPLACEABLE"
 
760
><I
 
761
>table_name</I
 
762
></TT
 
763
><TT
 
764
CLASS="LITERAL"
 
765
>%ROWTYPE</TT
 
766
>
 
767
    notation; or it can be declared by giving a composite type's name.
 
768
    (Since every table has an associated composite type of the same name,
 
769
    it actually does not matter in <SPAN
 
770
CLASS="PRODUCTNAME"
 
771
>PostgreSQL</SPAN
 
772
> whether you
 
773
    write <TT
 
774
CLASS="LITERAL"
 
775
>%ROWTYPE</TT
 
776
> or not.  But the form with
 
777
    <TT
 
778
CLASS="LITERAL"
 
779
>%ROWTYPE</TT
 
780
> is more portable.)
 
781
   </P
 
782
><P
 
783
>    Parameters to a function can be
 
784
    composite types (complete table rows). In that case, the
 
785
    corresponding identifier <TT
 
786
CLASS="LITERAL"
 
787
>$<TT
 
788
CLASS="REPLACEABLE"
 
789
><I
 
790
>n</I
 
791
></TT
 
792
></TT
 
793
> will be a row variable, and fields can
 
794
    be selected from it, for example <TT
 
795
CLASS="LITERAL"
 
796
>$1.user_id</TT
 
797
>.
 
798
   </P
 
799
><P
 
800
>    Only the user-defined columns of a table row are accessible in a
 
801
    row-type variable, not the OID or other system columns (because the
 
802
    row could be from a view).  The fields of the row type inherit the
 
803
    table's field size or precision for data types such as
 
804
    <TT
 
805
CLASS="TYPE"
 
806
>char(<TT
 
807
CLASS="REPLACEABLE"
 
808
><I
 
809
>n</I
 
810
></TT
 
811
>)</TT
 
812
>.
 
813
   </P
 
814
><P
 
815
>    Here is an example of using composite types.  <TT
 
816
CLASS="STRUCTNAME"
 
817
>table1</TT
 
818
>
 
819
    and <TT
 
820
CLASS="STRUCTNAME"
 
821
>table2</TT
 
822
> are existing tables having at least the
 
823
    mentioned fields:
 
824
 
 
825
</P><PRE
 
826
CLASS="PROGRAMLISTING"
 
827
>CREATE FUNCTION merge_fields(t_row table1) RETURNS text AS $$
 
828
DECLARE
 
829
    t2_row table2%ROWTYPE;
 
830
BEGIN
 
831
    SELECT * INTO t2_row FROM table2 WHERE ... ;
 
832
    RETURN t_row.f1 || t2_row.f3 || t_row.f5 || t2_row.f7;
 
833
END;
 
834
$$ LANGUAGE plpgsql;
 
835
 
 
836
SELECT merge_fields(t.*) FROM table1 t WHERE ... ;</PRE
 
837
><P>
 
838
   </P
 
839
></DIV
 
840
><DIV
 
841
CLASS="SECT2"
 
842
><H2
 
843
CLASS="SECT2"
 
844
><A
 
845
NAME="PLPGSQL-DECLARATION-RECORDS"
 
846
>39.3.5. Record Types</A
 
847
></H2
 
848
><PRE
 
849
CLASS="SYNOPSIS"
 
850
><TT
 
851
CLASS="REPLACEABLE"
 
852
><I
 
853
>name</I
 
854
></TT
 
855
> RECORD;</PRE
 
856
><P
 
857
>    Record variables are similar to row-type variables, but they have no
 
858
    predefined structure.  They take on the actual row structure of the
 
859
    row they are assigned during a <TT
 
860
CLASS="COMMAND"
 
861
>SELECT</TT
 
862
> or <TT
 
863
CLASS="COMMAND"
 
864
>FOR</TT
 
865
> command.  The substructure
 
866
    of a record variable can change each time it is assigned to.
 
867
    A consequence of this is that until a record variable is first assigned
 
868
    to, it has no substructure, and any attempt to access a
 
869
    field in it will draw a run-time error.
 
870
   </P
 
871
><P
 
872
>    Note that <TT
 
873
CLASS="LITERAL"
 
874
>RECORD</TT
 
875
> is not a true data type, only a placeholder.
 
876
    One should also realize that when a <SPAN
 
877
CLASS="APPLICATION"
 
878
>PL/pgSQL</SPAN
 
879
>
 
880
    function is declared to return type <TT
 
881
CLASS="TYPE"
 
882
>record</TT
 
883
>, this is not quite the
 
884
    same concept as a record variable, even though such a function might
 
885
    use a record variable to hold its result.  In both cases the actual row
 
886
    structure is unknown when the function is written, but for a function
 
887
    returning <TT
 
888
CLASS="TYPE"
 
889
>record</TT
 
890
> the actual structure is determined when the
 
891
    calling query is parsed, whereas a record variable can change its row
 
892
    structure on-the-fly.
 
893
   </P
 
894
></DIV
 
895
><DIV
 
896
CLASS="SECT2"
 
897
><H2
 
898
CLASS="SECT2"
 
899
><A
 
900
NAME="PLPGSQL-DECLARATION-COLLATION"
 
901
>39.3.6. Collation of <SPAN
 
902
CLASS="APPLICATION"
 
903
>PL/pgSQL</SPAN
 
904
> Variables</A
 
905
></H2
 
906
><P
 
907
>    When a <SPAN
 
908
CLASS="APPLICATION"
 
909
>PL/pgSQL</SPAN
 
910
> function has one or more
 
911
    parameters of collatable data types, a collation is identified for each
 
912
    function call depending on the collations assigned to the actual
 
913
    arguments, as described in <A
 
914
HREF="collation.html"
 
915
>Section 22.2</A
 
916
>.  If a collation is
 
917
    successfully identified (i.e., there are no conflicts of implicit
 
918
    collations among the arguments) then all the collatable parameters are
 
919
    treated as having that collation implicitly.  This will affect the
 
920
    behavior of collation-sensitive operations within the function.
 
921
    For example, consider
 
922
 
 
923
</P><PRE
 
924
CLASS="PROGRAMLISTING"
 
925
>CREATE FUNCTION less_than(a text, b text) RETURNS boolean AS $$
 
926
BEGIN
 
927
    RETURN a &lt; b;
 
928
END;
 
929
$$ LANGUAGE plpgsql;
 
930
 
 
931
SELECT less_than(text_field_1, text_field_2) FROM table1;
 
932
SELECT less_than(text_field_1, text_field_2 COLLATE "C") FROM table1;</PRE
 
933
><P>
 
934
 
 
935
    The first use of <CODE
 
936
CLASS="FUNCTION"
 
937
>less_than</CODE
 
938
> will use the common collation
 
939
    of <TT
 
940
CLASS="STRUCTFIELD"
 
941
>text_field_1</TT
 
942
> and <TT
 
943
CLASS="STRUCTFIELD"
 
944
>text_field_2</TT
 
945
> for
 
946
    the comparison, while the second use will use <TT
 
947
CLASS="LITERAL"
 
948
>C</TT
 
949
> collation.
 
950
   </P
 
951
><P
 
952
>    Furthermore, the identified collation is also assumed as the collation of
 
953
    any local variables that are of collatable types.  Thus this function
 
954
    would not work any differently if it were written as
 
955
 
 
956
</P><PRE
 
957
CLASS="PROGRAMLISTING"
 
958
>CREATE FUNCTION less_than(a text, b text) RETURNS boolean AS $$
 
959
DECLARE
 
960
    local_a text := a;
 
961
    local_b text := b;
 
962
BEGIN
 
963
    RETURN local_a &lt; local_b;
 
964
END;
 
965
$$ LANGUAGE plpgsql;</PRE
 
966
><P>
 
967
   </P
 
968
><P
 
969
>    If there are no parameters of collatable data types, or no common
 
970
    collation can be identified for them, then parameters and local variables
 
971
    use the default collation of their data type (which is usually the
 
972
    database's default collation, but could be different for variables of
 
973
    domain types).
 
974
   </P
 
975
><P
 
976
>    A local variable of a collatable data type can have a different collation
 
977
    associated with it by including the <TT
 
978
CLASS="LITERAL"
 
979
>COLLATE</TT
 
980
> option in its
 
981
    declaration, for example
 
982
 
 
983
</P><PRE
 
984
CLASS="PROGRAMLISTING"
 
985
>DECLARE
 
986
    local_a text COLLATE "en_US";</PRE
 
987
><P>
 
988
 
 
989
    This option overrides the collation that would otherwise be
 
990
    given to the variable according to the rules above.
 
991
   </P
 
992
><P
 
993
>    Also, of course explicit <TT
 
994
CLASS="LITERAL"
 
995
>COLLATE</TT
 
996
> clauses can be written inside
 
997
    a function if it is desired to force a particular collation to be used in
 
998
    a particular operation.  For example,
 
999
 
 
1000
</P><PRE
 
1001
CLASS="PROGRAMLISTING"
 
1002
>CREATE FUNCTION less_than_c(a text, b text) RETURNS boolean AS $$
 
1003
BEGIN
 
1004
    RETURN a &lt; b COLLATE "C";
 
1005
END;
 
1006
$$ LANGUAGE plpgsql;</PRE
 
1007
><P>
 
1008
 
 
1009
    This overrides the collations associated with the table columns,
 
1010
    parameters, or local variables used in the expression, just as would
 
1011
    happen in a plain SQL command.
 
1012
   </P
 
1013
></DIV
 
1014
></DIV
 
1015
><DIV
 
1016
CLASS="NAVFOOTER"
 
1017
><HR
 
1018
ALIGN="LEFT"
 
1019
WIDTH="100%"><TABLE
 
1020
SUMMARY="Footer navigation table"
 
1021
WIDTH="100%"
 
1022
BORDER="0"
 
1023
CELLPADDING="0"
 
1024
CELLSPACING="0"
 
1025
><TR
 
1026
><TD
 
1027
WIDTH="33%"
 
1028
ALIGN="left"
 
1029
VALIGN="top"
 
1030
><A
 
1031
HREF="plpgsql-structure.html"
 
1032
ACCESSKEY="P"
 
1033
>Prev</A
 
1034
></TD
 
1035
><TD
 
1036
WIDTH="34%"
 
1037
ALIGN="center"
 
1038
VALIGN="top"
 
1039
><A
 
1040
HREF="index.html"
 
1041
ACCESSKEY="H"
 
1042
>Home</A
 
1043
></TD
 
1044
><TD
 
1045
WIDTH="33%"
 
1046
ALIGN="right"
 
1047
VALIGN="top"
 
1048
><A
 
1049
HREF="plpgsql-expressions.html"
 
1050
ACCESSKEY="N"
 
1051
>Next</A
 
1052
></TD
 
1053
></TR
 
1054
><TR
 
1055
><TD
 
1056
WIDTH="33%"
 
1057
ALIGN="left"
 
1058
VALIGN="top"
 
1059
>Structure of <SPAN
 
1060
CLASS="APPLICATION"
 
1061
>PL/pgSQL</SPAN
 
1062
></TD
 
1063
><TD
 
1064
WIDTH="34%"
 
1065
ALIGN="center"
 
1066
VALIGN="top"
 
1067
><A
 
1068
HREF="plpgsql.html"
 
1069
ACCESSKEY="U"
 
1070
>Up</A
 
1071
></TD
 
1072
><TD
 
1073
WIDTH="33%"
 
1074
ALIGN="right"
 
1075
VALIGN="top"
 
1076
>Expressions</TD
 
1077
></TR
 
1078
></TABLE
 
1079
></DIV
 
1080
></BODY
 
1081
></HTML
 
1082
>
 
 
b'\\ No newline at end of file'